Crowdin CLI

Crowdin CLI is the command-line tool for managing and synchronizing localization resources with a Crowdin project. It ships as a single self-contained binary — no Java or other runtime required.

Check what's installed with crowdin --version. If it prints 4.x or a Java error, the user is on the legacy CLI — commands below still mostly apply, but see references/migrating-from-v4.md for the differences.

Full documentation: https://crowdin.github.io/crowdin-cli

Install

npm install -g @crowdin/cli

Also available via Homebrew (brew tap crowdin/crowdin && brew install crowdin@5), WinGet, Chocolatey, Docker (crowdin/cli), Linux package repositories, and as a standalone binary — see references/configuration.md for every option.

Authenticate

The CLI needs an API token and (for most commands) a project ID. On a developer's machine the quickest route is:

crowdin login

It authorizes in the browser and saves the token to the identity file ~/.crowdin.yml, where every later command — run by the user or by an agent — picks it up. No configuration file is generated or required, and Crowdin Enterprise needs nothing extra: the organization comes from the account signed in. crowdin init runs the same browser authorization and then generates a crowdin.yml; login is the choice when the config is written by hand or already exists. The flow finishes through a browser callback on the same machine, so when the agent's shell may be elsewhere, the user runs it in their own terminal. The browser-issued token expires after 30 days — re-run crowdin login when a command exits 101. Details: references/commands.md.

For CI and anything long-lived, use a personal access token — it does not expire:

• crowdin.com: create the token in Settings → API (https://crowdin.com/settings#api-key). base_url is https://api.crowdin.com (the default — no need to set it).
• Crowdin Enterprise: create it in Account Settings → Access Tokens. base_url must be set to https://{organization}.api.crowdin.com.

The project ID is numeric — get it with crowdin project list once a token is configured (project list alone needs -i 1 while no crowdin.yml carries a project_id: validation demands one even though this command ignores it), or from the project page in Crowdin.

Credentials resolve in this priority order (highest wins):

1. CLI flags: -T/--token, -i/--project-id, --base-url, --base-path
2. Identity file: --identity <path>, or ~/.crowdin.yml / ~/.crowdin.yaml if present
3. *_env keys in the config file (api_token_env: MY_VAR reads $MY_VAR)
4. Literal keys in the config file (api_token: "...")
5. CROWDIN_PERSONAL_TOKEN, CROWDIN_PROJECT_ID, CROWDIN_BASE_PATH, CROWDIN_BASE_URL environment variables

.env files in the working directory are loaded automatically, so CROWDIN_PERSONAL_TOKEN can live there. Never write a real token into crowdin.yml if the file is committed — use api_token_env or the CROWDIN_PERSONAL_TOKEN variable instead. A committed api_token_env and a local crowdin login coexist: the unset variable contributes nothing, so the identity file supplies the token on the developer's machine and the variable supplies it in CI.

Configure — crowdin.yml

Commands read crowdin.yml (or crowdin.yaml) from the current directory; override with -c/--config <path>. Minimal real-world example:

"project_id": "123456"
"api_token_env": "CROWDIN_PERSONAL_TOKEN"
"base_path": "."
"preserve_hierarchy": true

files:
  - source: "/src/locales/en/**/*.json"
    translation: "/src/locales/%two_letters_code%/**/%original_file_name%"

• source is a glob for local source files (relative to base_path); translation tells Crowdin where exported translations land, using placeholders like %two_letters_code%, %locale%, %original_file_name%, %original_path%, %file_name%.
• preserve_hierarchy: true keeps the local directory structure in Crowdin; without it, the common parent directory is stripped.
• One files entry per file group; each entry can add ignore, dest, type, update_option, labels, excluded_target_languages, languages_mapping, and more.

The full reference — all placeholders, per-entry options, language mapping, multiple file groups — is in references/configuration.md.

Before the first upload, verify the config instead of debugging a wrong upload after the fact:

crowdin config lint            # validate syntax
crowdin config sources         # list local files matched by each source pattern
crowdin config translations    # list translation paths that will be produced
crowdin upload sources --dryrun

Core workflow

The everyday cycle is: upload sources → translate → download translations.

crowdin upload sources           # push local source files (alias: crowdin push)
crowdin status                   # translation & proofreading progress per language
crowdin auto-translate --method tm   # optional: pre-fill via TM, MT, or AI
crowdin download translations    # pull completed translations (alias: crowdin pull)

Useful variants:

crowdin upload sources --cache               # skip unchanged files (checksum cache)
crowdin upload sources --delete-obsolete     # remove files from Crowdin that no longer exist locally
crowdin upload translations                  # import existing local translations
crowdin download translations -l uk -l fr    # only some languages
crowdin download translations --skip-untranslated-strings
crowdin download sources                     # pull sources back from Crowdin

Everything is branch-aware: pass -b <name> to scope upload/download/status to a Crowdin branch (create it with crowdin branch add).

auto-translate (v4's pre-translate) applies TM (--method tm), machine translation (--method mt --engine-id <id>), or AI (--method ai --ai-prompt <id>), with fine-grained control: --scope untranslated|translated|all, --skip-approved-translations, --label/--exclude-label, --replace-translations-option, --translation-modified-before, and more — see references/commands.md. It waits for the job to finish; --async returns the job identifier at once, for crowdin auto-translate status <id> [--wait] to check later.

Integrations through Crowdin apps

When the content lives in a CMS, marketing tool, help center or other platform connected through an installed Crowdin app, the sync runs through the app's API methods (crowdin app methods, crowdin app api), not upload/download. Read references/apps.md before the first call: it has the import, job and push loop, how to pass the app's IDs, and which calls replace settings.

Strings context for AI enrichment

Enriching a project's strings context (download, fill ai_context, upload) is the context-extraction skill's loop. The crowdin context commands and the JSONL format: references/context.md; its --status filter does not mean "needs context".

Output for scripts and agents

The global -o/--output option changes any command's output format:

• -o json — machine-readable JSON; pipe into jq or parse from a script
• -o toon — Token-Oriented Object Notation, same data as JSON at a fraction of the size; prefer this when the consumer is an LLM
• -o plain — minimal processable text (v4's --plain flag)

In json and toon modes stdout carries nothing but data — no spinners, colors, or decorative messages — so output is safe to parse. When running the CLI as an agent, default to -o toon for lists you only need to read and -o json when a script must parse the result.

crowdin file list -o json | jq -r '.[].path'
crowdin status -o toon

Exit codes are stable and meaningful — branch on them rather than parsing error text:

Mutating file commands accept --dryrun to preview what would happen. Add -v/--verbose when diagnosing; --no-progress/--no-colors clean up logs in CI (json/toon modes already imply this).

Command map

23 top-level commands; most have subcommands. Full option-level reference: references/commands.md.

Shell completion: source <(crowdin complete zsh) (also bash, fish, powershell).

CI/CD

• Store the token as a CI secret exposed as CROWDIN_PERSONAL_TOKEN; keep project_id in the committed crowdin.yml (it is not sensitive).
• Typical pipeline: crowdin upload sources on merge to the main branch; crowdin download translations on a schedule or before release, followed by a commit/PR of the updated files.
• For GitHub Actions prefer the official crowdin/github-action, which wraps this CLI — covered by the github-action skill.
• The CLI never prompts when all required values are provided; a missing value fails with exit code 2 rather than hanging.
• crowdin status --fail-if-incomplete exits non-zero when the project isn't fully translated — a ready-made release gate.

Related skills

• context-extraction — writes the ai_context values that crowdin context upload sends
• croql — CroQL expressions for --croql filters on string commands
• crowdin-api-client — the JS/TS API client, when a CLI command doesn't cover the need
• translate — drafts translations into local resource files with the project's glossary, TM and style guide, and uploads them as suggestions