---
title: "Command reference"
description: "Every Linguana CLI command, option, JSON result, environment variable, file, and error code."
canonical_url: "https://docs.linguana.dev/docs/cli/commands"
markdown_url: "https://docs.linguana.dev/docs/cli/commands.md"
x_farming_labs_generated_preamble: true
---

# Command reference
URL: /docs/cli/commands
LLM index: /llms.txt
Description: Every Linguana CLI command, option, JSON result, environment variable, file, and error code.
Related: /docs/cli/automation, /docs/troubleshooting/cli

# CLI command reference

```text
linguana [global options] <command> [options]
```

The package is `@linguanahq/cli` and the executable is `linguana`. It requires Node.js 22.12 or later, or Bun. Run any command with `--help` to print its options.

## Global options

These options work with every command and may appear before or after the command name.

| Option | Description |
| --- | --- |
| `--json` | Print one structured JSON result on standard output, without secrets. Implies noninteractive mode |
| `--yes` | Use defaults without prompting. Never selects connected mode |
| `--api-url <origin>` | Linguana API origin. HTTPS, or HTTP for loopback development only |
| `-V`, `--version` | Print the CLI version |
| `-h`, `--help` | Print help for the program or a command |

Without `--api-url`, commands use the `apiUrl` from `linguana.json` in the current directory, then `https://linguana-api.mohammedibrahim.dev`.

## Project options

`create app`, `link`, and `env pull` share these options.

| Option | Description |
| --- | --- |
| `--organization <id>` | Use an existing organization |
| `--project <id>` | Use an existing project |
| `--new-organization <name>` | Create an organization |
| `--new-project <name>` | Create a project |
| `--environment <name>` | Credential environment. Default: `defaultEnvironment` from `linguana.json`, or `development` |
| `--framework <framework>` | `react`, `vue`, `svelte`, `solidjs` (alias `solid`), or `tanstack-start` |
| `--locales <codes>` | Comma-separated target languages to enable, such as `fr,es,ar` |
| `--overwrite-env` | Replace conflicting Linguana variables and invalid existing tokens |

These pairs are mutually exclusive: `--organization` and `--new-organization`; `--project` and `--new-project`; `--project` and `--new-organization`. Environment names use lowercase letters, digits, and hyphens, starting with a letter.

## `create app`

```text
linguana create app [directory] [options]
```

Create a standalone app from a template. See [Create an app](/docs/cli/create-app).

| Option | Description |
| --- | --- |
| `[directory]` | Target directory. Must be new or empty apart from `.git`. Prompted, default `my-<template>` |
| `--template <template>` | `blog`, `saas`, or `storefront` |
| `--demo` | Use bundled translations without an account. Cannot be combined with `--connect` or project provisioning options |
| `--connect` | Sign in and connect a Linguana project |
| `--package-manager <manager>` | `npm`, `pnpm`, `yarn`, or `bun`. Default: the invoking package manager, otherwise npm |
| `--skip-install` | Write files without installing dependencies |
| Project options | Connected mode only; see above |

**JSON result:** `directory`, `framework`, `template`, `mode` (`demo` or `connected`), and `nextCommand`. Connected mode adds `projectId`, `projectUrl`, and `envFile`.

## `templates list`

```text
linguana templates list
```

List templates, supported frameworks, and hosted demo addresses when available. **JSON result:** `templates` (ID, name, category, description, features) and `variants` (one per template and framework, with rendering mode, locales, source URL, deployment targets, and `demoUrl` when deployed).

## `login`

```text
linguana login [--no-browser]
```

Start browser authorization and save a CLI account session for the API origin. See [Sign in from the terminal](/docs/cli/authentication).

| Option | Description |
| --- | --- |
| `--no-browser` | Print the authorization address without opening a browser |

**JSON result:** `user` and `origin`.

## `logout`

```text
linguana logout
```

Revoke the CLI session on the server and delete it locally. Your browser session is unaffected. **JSON result:** `{ "signedOut": true, "origin": "…" }`.

## `whoami`

```text
linguana whoami
```

Print the signed-in user and API origin after validating the session. **JSON result:** `user` and `origin`.

## `orgs list`

```text
linguana orgs list
```

List organizations you belong to as `ID  Name` lines. **JSON result:** an array of organizations.

## `projects list`

```text
linguana projects list [--organization <id>]
```

List an organization's projects as `ID  Name` lines. Prompts for the organization when omitted. **JSON result:** an array of projects.

## `link`

```text
linguana link [project options]
```

Connect the app in the current directory and write environment configuration. See [Connect an existing app](/docs/cli/link).

**JSON result:** `projectId`, `organizationId`, `environment`, `envFile`, `projectUrl`, and `config` (the written `linguana.json`).

## `env pull`

```text
linguana env pull [--environment <name>] [--overwrite-env]
```

Refresh credentials for the linked project in the selected environment's file. Requires a prior `link`; the project always comes from `linguana.json`. Accepts the project options; `--environment` and `--overwrite-env` are the ones you normally need.

**JSON result:** the same shape as `link`.

## `doctor`

```text
linguana doctor [--environment <name>]
```

Check SDK packages, Vite plugin order, linkage, session, environment file, and token. Exits with `1` when any check fails. See [Check your setup](/docs/cli/doctor).

**JSON result:** `ok` and `checks`, an array of `{ check, ok, message }`.

## Environment variables

| Variable | Read by | Purpose |
| --- | --- | --- |
| `LINGUANA_AUTH_TOKEN` | All authenticated commands | Supplies an account session for controlled automation, instead of the saved login. Must not be a project build token |
| `LINGUANA_CONFIG_DIR` | All commands | Directory for saved account sessions |
| `XDG_CONFIG_HOME` | Linux | Base directory for sessions when `LINGUANA_CONFIG_DIR` is unset |
| `APPDATA` | Windows | Base directory for sessions when `LINGUANA_CONFIG_DIR` is unset |
| `npm_config_user_agent` | `create app` | Detects the invoking package manager; set by npm, pnpm, Yarn, and Bun |

The variables the CLI **writes** into app environment files are listed in [Connect an existing app](/docs/cli/link#the-environment-file) and [Environment variables](/docs/reference/environment-variables).

## Files

| Path | Location | Commit? | Contents |
| --- | --- | --- | --- |
| `linguana.json` | App root | Yes | Schema version, framework, template, mode, API origin, organization and project IDs, source language, default environment |
| `.env.local` | App root | No | Development build and browser values |
| `.env.<environment>.local` | App root | No | Values for another environment |
| `.linguana/setup.json` | App root | No | Nonsecret idempotency keys for resumable setup |
| `.linguana/cli.lock` | App root | No | Present only while setup runs |
| `<config directory>/<hash>.json` | User configuration directory | Never | The CLI account session for one API origin |

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success, including `--help` and `--version` |
| `1` | Operational failure, or a failed `doctor` check |
| `2` | Invalid input, conflicting options, or a missing noninteractive choice |
| `130` | Canceled |

## Error codes

With `--json`, failures print `{"error":{"code","message"}}`. API errors use the code the server returns, or `HTTP_<status>`, and include a request ID when available.

| Code | Exit | Meaning |
| --- | --- | --- |
| `INVALID_ARGUMENTS` | 2 | Unknown option or malformed command |
| `CONFLICTING_OPTIONS` | 2 | Mutually exclusive options were combined |
| `INPUT_REQUIRED` | 2 | A choice is required when running noninteractively |
| `INVALID_TEMPLATE` / `INVALID_FRAMEWORK` | 2 | Unsupported template or framework |
| `INVALID_DESTINATION` | 2 | Target is not empty, is a file, is a filesystem root, or passes through a symbolic link |
| `INVALID_PACKAGE_MANAGER` | 2 | Package manager is not npm, pnpm, yarn, or bun |
| `INSTALL_FAILED` | 1 | Dependency installation failed; the app is kept |
| `INVALID_API_URL` | 2 | The API origin is not HTTPS or loopback HTTP, or has a path, query, or credentials |
| `LOGIN_REQUIRED` | 1 | No valid session; run `login` |
| `ACCESS_DENIED` / `LOGIN_EXPIRED` | 1 | Authorization was denied, or the code expired |
| `WRONG_TOKEN_TYPE` | 2 | `LINGUANA_AUTH_TOKEN` contains a project build token |
| `INVALID_CREDENTIALS` | 1 | The saved session file is invalid; run `login` |
| `REMOTE_LOGOUT_FAILED` | 1 | Local session removed, but the server could not revoke it |
| `APP_NOT_FOUND` | 2 | No `package.json` in the current directory |
| `FRAMEWORK_REQUIRED` | 2 | Zero or several frameworks detected; pass `--framework` |
| `INVALID_PROJECT_CONFIG` / `INVALID_CONFIG` | 2 | `linguana.json` or another JSON file cannot be read or uses an unsupported schema |
| `PROJECT_NOT_LINKED` | 2 | Run `link` before `env pull` |
| `ORGANIZATION_REQUIRED` | 2 | Pass `--new-organization` to create your first organization |
| `ORGANIZATION_NOT_FOUND` | 1 | `--organization` is not in your account |
| `PROJECT_SCOPE_MISMATCH` | 2 | The project belongs to another organization |
| `INSUFFICIENT_PERMISSIONS` | 1 | Owner or Admin access to an active organization is required |
| `PROJECT_INACTIVE` | 1 | The project is pending deletion |
| `SOURCE_LOCALE_MISMATCH` | 2 | Templates require an English-source project |
| `ENVIRONMENT_NOT_FOUND` | 1 | The project does not have the requested environment |
| `INVALID_ENVIRONMENT` | 2 | Invalid environment name |
| `INVALID_LOCALE` | 2 | A `--locales` code is not in the project's language registry |
| `INVALID_NAME` | 2 | A new organization or project name has no letters or numbers |
| `ENV_CONFLICT` | 2 | Existing values or tokens were preserved; retry with `--overwrite-env` |
| `DUPLICATE_ENV` | 2 | A Linguana variable is defined twice in the environment file |
| `TRACKED_ENV` | 2 | The environment file is tracked by Git |
| `UNSAFE_PATH` | 2 | A write would pass through a symbolic link |
| `CONFIG_NOT_WRITABLE` / `ENV_NOT_WRITABLE` | 1 | Fix local file permissions |
| `SETUP_LOCKED` | 1 | Another setup is running in this app |
| `TOKEN_RECOVERY_FAILED` / `TOKEN_SECRET_UNAVAILABLE` | 1 | A replacement token could not be created; retry `env pull` or inspect tokens in the dashboard |
| `INVALID_AUTH_RESPONSE` | 1 | The server returned an invalid authorization response |
| `CANCELED` | 130 | Canceled; resume connected setup with `link` |
| `COMMAND_FAILED` | 1 | Unexpected failure |

For fixes, see [CLI troubleshooting](/docs/troubleshooting/cli).

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