Check your setup with `doctor`

doctor inspects the app in the current directory and reports whether Linguana is installed, configured, and connected correctly. It never changes files.

terminal

npx @linguanahq/cli doctor
npx @linguanahq/cli doctor --environment production

Each check prints ✓ or ✗, its name, and a message. For a demo app, the output looks like this:

output

✓ framework: react
✓ sdk: Install @linguanahq/react and @linguanahq/vite.
✓ vite: Vite configuration must run linguana() before the framework plugin.
✓ configuration: demo mode

The message after each check states the requirement it verifies, so a passing check may still read like an instruction. doctor exits with 1 when any check fails, which makes it suitable for scripts.

Checks for every app

Check	Passes when	If it fails
`framework`	The framework can be identified from `linguana.json` or `package.json`	`doctor` stops with `FRAMEWORK_REQUIRED` or `APP_NOT_FOUND`; run it in the app directory
`sdk`	`package.json` lists the framework runtime (`@linguanahq/react`, `vue`, `svelte`, or `solid`) and `@linguanahq/vite`	Install the packages from Install Linguana
`vite`	`vite.config.ts` calls `linguana(`	Add the plugin before the framework plugin
`configuration`	`linguana.json` exists and is valid	Run `link` to create it

TanStack Start apps use the React runtime, so the sdk check looks for @linguanahq/react. The vite check reads vite.config.ts only; apps configured in vite.config.js or vite.config.mjs report this check as failing even when the plugin is present.

Additional checks for connected apps

When linguana.json has "mode": "connected", doctor also checks the environment you select with --environment (default: defaultEnvironment from linguana.json):

Check	Passes when	If it fails
`authentication`	A CLI account session for the project's API origin is valid	Run `login`
`environment`	The environment file's project ID, environment, and API URL match `linguana.json`, for both build and `VITE_` values	Run `env pull --environment <name>`
`git`	The environment file is not tracked by Git	Remove it from the Git index and rotate its token
`browser-secrets`	No `VITE_` variable contains `TOKEN`, `SECRET`, or `PASSWORD`, or a value starting with `lna_`	Move the secret to an unprefixed variable and rotate it
`token`	`LINGUANA_PROJECT_TOKEN` is present, valid, and belongs to the linked project and environment	Run `env pull`, and check network access to the API

The token check asks the API which project and environment the token belongs to. It does not upload anything and does not reveal the token.

JSON output

terminal

npx @linguanahq/cli doctor --json

output

{
  "ok": false,
  "checks": [
    { "check": "framework", "ok": true, "message": "react" },
    { "check": "authentication", "ok": false, "message": "Run linguana login to manage this project." }
  ]
}

ok is true only when every check passes.

Next.js and other apps

doctor targets Vite apps and TanStack Start. In a Next.js app, it detects React and reports the sdk and vite checks as failing because Next.js uses @linguanahq/next and next.config.ts instead. Use the Next.js verification steps instead.

doctor reads environment files from disk. In CI, where credentials are usually injected as environment variables rather than files, the environment and token checks fail. Run doctor locally, and verify CI with a build.

Did this page get you to a working result?

Edit on GitHubllms.txt llms-full.txt