---
title: "Check your setup"
description: "Run linguana doctor to verify SDK packages, Vite order, project linkage, sessions, and build tokens."
canonical_url: "https://docs.linguana.dev/docs/cli/doctor"
markdown_url: "https://docs.linguana.dev/docs/cli/doctor.md"
x_farming_labs_generated_preamble: true
---

# Check your setup
URL: /docs/cli/doctor
LLM index: /llms.txt
Description: Run linguana doctor to verify SDK packages, Vite order, project linkage, sessions, and build tokens.
Related: /docs/cli/link, /docs/troubleshooting/cli

# 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.

```bash title="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:

```text title="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](/docs/getting-started/install) |
| `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

```bash title="terminal"
npx @linguanahq/cli doctor --json
```

```json title="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](/docs/getting-started/nextjs#verify-your-integration) 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.

<ExpectedResult>
Every line starts with `✓`, and the command exits with `0`.
</ExpectedResult>

<NextStep>
For a failing check, see [CLI troubleshooting](/docs/troubleshooting/cli).
</NextStep>

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).