CLI command reference

Find CLI commands for setup, translation, and catalog maintenance.

Use lingo --help for ordinary command discovery and lingo <command> --help for options. lingo --version identifies the installed generation. The current package is @lingo.dev/cli; i18n.json projects use the separate v0 manual.

For an existing i18n.json project, Migration maps the older workflows to current commands.

Init #

lingo init scaffolds source/target locales and file patterns. Force replaces existing file entries and can discard advanced options; inspect the resulting config before translation.

Login #

lingo login stores a browser session or validated API key. Its local --api-key persists the key. The global option on another command applies only to that invocation.

Logout #

lingo logout clears persisted credentials. Environment and invocation keys remain effective.

Whoami #

lingo whoami reports identity and authentication type; --json supplies machine-readable output. Connectivity fallback to stored information is not online verification.

lingo link saves the organization and localization engine IDs used by file translation. IDs select resources without granting access.

lingo unlink removes those IDs while preserving files, localization settings, and remote resources.

Push #

lingo push submits source files. Its modes distinguish baseline storage, incremental translation, missing-target backfill, key refresh, and forced replacement. --wait also retrieves output. Running it again retries failed work.

Pull #

lingo pull collects the latest locally recorded run and checks target hashes before writing. --dry-run previews write decisions but can still contact the server.

Purge #

lingo purge previews or deletes derived targets. With file or locale filters, it removes only the selected target entries from the lockfile; without filters, it removes the whole lockfile. Shared XCStrings catalogs are skipped.

Extract #

lingo extract turns supported static TypeScript/TSX calls into source JSONC and declarations. It is local extraction, not automatic rewriting or translation.

Check #

lingo check fails when a target file is missing and, with .lingo/lock.json, when a source changed since its last translation, without a network call or API key. Without the lockfile it checks only that target files exist. In React projects it also checks catalog and type freshness, context, orphans, and missing translations. It does not check keys inside non-React targets or assess translation quality.

Clean #

lingo clean immediately removes source orphans and stale target entries from JSONC catalogs. It has no dry-run flag and does not regenerate declarations.

Guide #

lingo guide [name] prints bundled offline React guidance. Names are index, setup-react, api, and migrate; omission selects the index. An unknown name reports the available choices. The guide belongs to the installed package version.

Agent guide #

lingo agent-guide [name] is for AI agents. Without a name it prints the agent guide, covering setup, sign-in, and the MCP server, and lists the agent and people guides; with a name it prints that guide, including stack guides the list leaves out. The guides belong to the installed package version.

Agent #

lingo agent setup checks whether the coding agents it detects (Claude Code, Codex, and Cursor, plus the one it runs inside) have the Lingo.dev MCP server and points to the MCP setup for those that do not; it never edits their configs. --client names the agents to check instead, including ones it did not detect. Without --status, it fails without writing anything when there is no agent to check. Inside a project it also writes the Lingo.dev block to AGENTS.md, and to an existing CLAUDE.md unless it imports an AGENTS.md that takes the block; it never creates CLAUDE.md. It leaves a file unchanged and says why when the file cannot be read, links outside the project, or has block markers that do not pair up; fix the file and run setup again. --dry-run shows the plan, -y writes without asking, and --status shows what is set up for the detected agents, ignoring --client. Set up with a coding agent has prompts to give your agent.

Update #

lingo update uses the detected installation method. Use your package manager to install a specific release. Update checks are cached and skipped in detected CI or with an environment opt-out.

Score #

lingo score is registered but omitted from ordinary help. It runs local scorer/model combinations through OpenRouter and writes local results, without adding Radar history.