Quickstart

End-to-end: install, authenticate, link to an engine, push sources, pull translations.

Prerequisites

Node.js 22+ (node -v to check). The CLI runs as lingo once installed.

Setup#

Install

bash

npm install -g @lingo.dev/cli

Or pnpm add -g @lingo.dev/cli / yarn global add @lingo.dev/cli / bun add -g @lingo.dev/cli.

Authenticate

bash

lingo login

Enter your email; the CLI sends a one-time code and stores a session token in ~/.lingo/auth.json. For CI / non-interactive contexts use an API key: lingo login --api-key lk_... (or set --api-key as a global flag on any command).

Initialize the project

In your project root:

bash

lingo init

Prompts for source locale, target locales, and file patterns (globs that point at your source files). Writes the localization section into .lingo/config.json. Commit this file — it's the source of truth for what gets translated.

Link to an engine

bash

lingo link

Pick (or create) an organization and a localization engine. The engine holds your AI model config, glossaries, brand voice, and instructions — set it up once on the Lingo.dev platform and reuse it across projects. link appends orgId and engineId to .lingo/config.json (also committed).

First push#

With a non-empty source file in place (e.g. locales/en.json):

bash

lingo push --backfill-missing

Translates every missing target across every configured pattern. The CLI waits for the run to complete and writes outputs (locales/de.json, locales/fr.json, ...) to disk. On a clean checkout this takes anywhere from seconds (small JSON) to minutes (large markdown bundles).

When it finishes:

text

✓ Run run_a8c... : localized 12 target file(s), uploaded 1 new artifact(s).

Subsequent runs#

After you edit source files, plain lingo push only translates the delta — files whose source hash didn't change are skipped server-side. Local target edits are preserved by default; pass --force (with a scope) to overwrite.

bash

lingo push                       # delta only
lingo push docs/en/**/*.md       # scoped: only this subtree
lingo push docs/en/about.md -f   # scoped + force: retranslate even if up to date

Pulling from a different machine#

push records the run ID in ~/.lingo/runs/<hash>.json (keyed by absolute project path). On any machine with the same checkout and the same credentials:

bash

lingo pull

…fetches the outputs from the last push. Useful for CI ("translator runs push from laptop, CI runs pull on every build") or just resuming after a terminal close.

Where to next#

Configuration — .lingo/config.json schema, lockfile, where run state lives.
lingo push — scoped patterns, --force, retry semantics.
lingo pull — conflict detection, --dry-run.

End-to-end: install, authenticate, link to an engine, push sources, pull translations.

Prerequisites

Node.js 22+ (node -v to check). The CLI runs as lingo once installed.

Setup#

Install

bash

npm install -g @lingo.dev/cli

Or pnpm add -g @lingo.dev/cli / yarn global add @lingo.dev/cli / bun add -g @lingo.dev/cli.

Authenticate

bash

lingo login

Initialize the project

In your project root:

bash

lingo init

Link to an engine

bash

lingo link

First push#

With a non-empty source file in place (e.g. locales/en.json):

bash

lingo push --backfill-missing

When it finishes:

text

✓ Run run_a8c... : localized 12 target file(s), uploaded 1 new artifact(s).

Subsequent runs#

bash

lingo push                       # delta only
lingo push docs/en/**/*.md       # scoped: only this subtree
lingo push docs/en/about.md -f   # scoped + force: retranslate even if up to date

Pulling from a different machine#

push records the run ID in ~/.lingo/runs/<hash>.json (keyed by absolute project path). On any machine with the same checkout and the same credentials:

bash

lingo pull

…fetches the outputs from the last push. Useful for CI ("translator runs push from laptop, CI runs pull on every build") or just resuming after a terminal close.

Where to next#

Configuration — .lingo/config.json schema, lockfile, where run state lives.
lingo push — scoped patterns, --force, retry semantics.
lingo pull — conflict detection, --dry-run.