CLI command reference

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`

linguana create app [directory] [options]

Create a standalone app from a template. See Create an 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`

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

linguana login [--no-browser]

Start browser authorization and save a CLI account session for the API origin. See Sign in from the terminal.

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

JSON result: user and origin.

`logout`

linguana logout

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

`whoami`

linguana whoami

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

`orgs list`

linguana orgs list

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

`projects list`

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`

linguana link [project options]

Connect the app in the current directory and write environment configuration. See Connect an existing app.

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

`env pull`

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`

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.

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

Did this page get you to a working result?

Edit on GitHubllms.txt llms-full.txt

On this page