Skip to main content

CLI Reference

The Branchlate CLI allows you to manage and synchronize translations directly from the command line. By integrating Branchlate commands into your workflow, you can streamline your translation process and automate tasks within CI/CD pipelines.

Installation​

All Branchlate CLI commands use npx to ensure you are always running the latest version.

npx branchlate@latest <command>

Commands​

Here’s an overview of all available Branchlate CLI commands, options, and usage examples.

login​

Authenticate the Branchlate CLI with your account.

npx branchlate@latest login

This command will prompt you for your Branchlate email and password, storing your authentication token locally in ~/.branchlate/authentication.json. This token is required for all subsequent commands.


init​

Initialize a Branchlate configuration in your project. This command creates a branchlate.json configuration file, specifying project settings for future syncs.

npx branchlate@latest init

This command prompts you for:

  • Project ID: Branchlate project ID.
  • Organisation ID: Branchlate organisation ID (leave blank for personal projects).
  • Translation files path: The pattern for locating translation files (e.g., i18n/{languageCode}.json).

Options:

  • --projectId <projectId>: Specify the Branchlate project ID.
  • --organisationId <organisationId>: Specify the Branchlate organisation ID.
  • --languageFilePattern <pattern>: Specify the pattern for your translation files.

Example:

npx branchlate@latest init --projectId my-project --organisationId my-org --languageFilePattern i18n/{languageCode}.json

Note: If you have an existing configuration, the command will prompt you to confirm if you want to overwrite it.


sync​

Synchronize your local translations with Branchlate, ensuring alignment across environments. By default, this command syncs using the current Git branch as the Branchlate branch.

npx branchlate@latest sync

Options:

  • --branch-name <branchName>: Specify a different branch name instead of the current Git branch.
  • --project <projectName>: Sync a specific project of a multi-project configuration. (CLI 1.3.0+)
  • --all-projects (alias --all): Sync every project of a multi-project configuration, ignoring defaultProject. (CLI 1.3.0+)
  • --flatten: Flatten nested translation keys into a single level.
  • --auto-translate: Automatically generate translations for new or updated keys and wait for the translations to complete.
  • --no-wait: Use in combination with --auto-translate to initiate auto-translation without waiting for the translations to complete.
  • --invalidate-updated-keys: When the code changes a value, flag the other values of that key as "Update needed" so that translators review them, and let the code overwrite values waiting for review. Values validated on Branchlate keep their validation. See Invalidate translations when updating keys.
  • --force: When the code changes a value that is in review on Branchlate (red or green chip), ask for each conflict whether to keep the local value. With --yes or BRANCHLATE_TOKEN, nothing is asked and the local value is kept for every conflict. See Resolve conflicts with --force.
  • -y, --yes: Skip the confirmation prompts for creating and deleting language files (automatically enabled when using BRANCHLATE_TOKEN). It does not enable --force: conflicts keep the Branchlate value.

Notes:

  • The sync command will create the project in Branchlate if it does not already exist.
  • If you have sub-projects defined in your branchlate.json, the sync command will also sync those sub-projects.
  • In a multi-project repository (branchlate-root.json), running without --project from the repository root syncs the defaultProject when defined, otherwise all linked projects.
  • The command will automatically handle creating new branches and updating existing ones.
  • After the first flattening, further syncs will auto-detect the flattened structure, so you don't need to pass --flatten again unless you change your key structure.
  • The reference language file defines which keys exist: a key removed from the local reference language file is deleted on Branchlate in every language, including validated translations, without confirmation. See Sync precedence rules.
  • sync compares your files with the current Branchlate values only. Pull the latest commits of your Git branch before syncing: a sync from an outdated copy re-creates deleted keys and restores old values. See Sync from an up-to-date copy.
  • Unless keepsReferenceLanguageOrder is enabled, sync rewrites every language file with its keys sorted alphabetically. The first sync of an existing project can therefore reorder whole files: commit that change on its own.

Use cases​

Sync with a specific branch name​
npx branchlate@latest sync --branch-name feature/new-login

This syncs translations to the feature/new-login branch on Branchlate.

Flatten translation keys during sync​
npx branchlate@latest sync --flatten

This command flattens nested translation keys into dot-notated keys during the sync.

Automatically translate keys​
npx branchlate@latest sync --auto-translate

You can execute an auto translation for all unvalidated and not already translated keys. Here is how the process works:

  • The --auto-translate option initiates the translation process for all unvalidated and not already translated keys.
  • The CLI waits for the translations to complete before proceeding.
  • After translations are completed, the CLI syncs again to update your local files with the new translations.
Asynchronous auto-translate​
npx branchlate@latest sync --auto-translate --no-wait

This command initiates the auto-translation process but does not wait for the translations to complete.

Invalidate translations when updating keys​
npx branchlate@latest sync --invalidate-updated-keys

When you change the meaning of a reference language value (e.g., the English wording of an existing key), translations in other languages may become stale. With --invalidate-updated-keys, the values the code changes and the other values of these keys are flagged as "Update needed" (red chip), so that reviewers and translators see them on Branchlate. The flag also lets your local value overwrite values waiting for review.

Values validated on Branchlate (green chip) are not flagged, nor are values added by the code and not changed since: invalidate them on Branchlate if they must be reviewed again. The values created during that sync, including new keys, are flagged as well.

Resolve conflicts with --force​
npx branchlate@latest sync --force

When the code changes a value that is in review on Branchlate (red or green chip), Branchlate keeps its value by default. With --force, the CLI shows each conflict and lets you choose whether to keep your local value or the Branchlate value. The local values you keep are flagged as "Update needed" (red chip).

warning

With --yes or BRANCHLATE_TOKEN, --force asks nothing and keeps the local value for every conflict, overwriting the work of translators, including validated translations. Don't use --force in CI.


format​

Format your local language files so that keys are sorted and indentation is consistent. This helps keep translation files readable and reduces noisy diffs. The command uses the same file patterns as sync (including sub-projects if defined in your configuration).

npx branchlate@latest format

Options:

  • --dry-run: Show a diff of what would be changed without writing to files.
  • --project <projectName>: Format a specific project of a multi-project configuration. (CLI 1.3.0+)
  • --all-projects (alias --all): Format every project of a multi-project configuration, ignoring defaultProject. (CLI 1.3.0+)

Notes:

  • If you only have sub-projects in your branchlate.json (no root languageFilePattern), the command will still find and format all files from your sub-project patterns.
  • Use --dry-run to preview changes before applying them, for example before committing.

Example:

npx branchlate@latest format --dry-run

Example output:

When some files need formatting, format --dry-run shows a diff for each file that would change. After running format, those files are updated; running format --dry-run again then reports that all files are already formatted.

format (apply changes)

$ npx branchlate@latest format
npx branchlate@latest format
📝 Formatting 4 language file(s)...
🇺🇸 src/common/i18n/translations/notifications/en.json (formatted)
🇫🇷 src/common/i18n/translations/categories/fr.json (formatted)
✅ Successfully formatted 2 file(s)

format --dry-run (with changes to apply)

$ npx branchlate@latest format --dry-run
npx branchlate@latest format --dry-run
📝 Formatting 4 language file(s)...
🇺🇸 src/common/i18n/translations/notifications/en.json (would be formatted)
Index: src/common/i18n/translations/notifications/en.json
===================================================================
--- src/common/i18n/translations/notifications/en.json original
+++ src/common/i18n/translations/notifications/en.json formatted
@@ -19,5 +19,5 @@
"postTagTitle": "You were tagged",
"postTagWithPreview": "{taggerName} tagged you in a post{bookContext}: "{contentPreview}"",
"recommendationBody": "{recommenderName} recommended you {bookTitle}. Tap for more details.",
"recommendationTitle": "New Recommendation"
-}
\ No newline at end of file
+}
🇫🇷 src/common/i18n/translations/categories/fr.json (would be formatted)
Index: src/common/i18n/translations/categories/fr.json
===================================================================
--- src/common/i18n/translations/categories/fr.json original
+++ src/common/i18n/translations/categories/fr.json formatted
@@ -871,5 +871,5 @@
"Young Adult Fiction": "Fiction pour jeunes adultes",
"Young Women": "Jeunes femmes",
"Youth": "Jeunesse",
"Youth Literature": "Littérature jeunesse"
-}
\ No newline at end of file
+}
⚠️ Dry run: 2 file(s) would be formatted

format --dry-run (all files already formatted)

$ npx branchlate@latest format --dry-run
npx branchlate@latest format --dry-run
📝 Formatting 4 language file(s)...
✅ All files are already properly formatted

status​

Print a translation coverage report for the current branch. This is especially useful in CI to ensure that all languages meet a minimum validation level before releasing—so you never ship untranslated or unvalidated keys to users.

By default, the command fails if your local files are out of sync with Branchlate (exit code 2) or if any language is below the required coverage (exit code 1).

A value counts as unvalidated only when it is flagged "Update needed" on Branchlate (red chip). Values validated on Branchlate (green chip) count as validated, and so do values written by sync that nobody has reviewed (no chip).

npx branchlate@latest status

Options:

  • --min-coverage <percent>: Minimum validated percentage required for each language (default: 100). The command exits with code 1 if any language is below this value.
  • --no-fail-on-out-of-sync: Do not exit with code 2 when local files are out of sync with remote. Use this to still get a coverage report even when a sync is pending.
  • --branch-name <branchName>: Branch to check (default: current Git branch).
  • --project <projectName>: Check a specific project of a multi-project configuration. (CLI 1.3.0+)
  • --all-projects (alias --all): Check every project of a multi-project configuration, ignoring defaultProject. (CLI 1.3.0+)
  • --json: Output the result as structured JSON for CI parsing and automation.
  • --local: Check that all translation keys are defined across all languages, without comparing against a remote branch. Useful for branches that don't have a corresponding branch in Branchlate.
  • --fallback-to-local: Run the normal remote comparison when the branch exists on Branchlate; automatically fall back to --local behavior when it doesn't. Ideal for CI pipelines that run on every branch.

Exit codes:

  • 0: Local files are in sync and all languages meet the minimum coverage.
  • 1: At least one language is below the required coverage (see --min-coverage).
  • 2: Local files are out of sync with Branchlate (run sync first, or use --no-fail-on-out-of-sync to only check coverage).

Notes:

  • The command uses the same project and sub-project configuration as sync, so it will report coverage for all configured language file sets.
  • For release branches, run branchlate status in CI to block releases when translations are incomplete or out of sync.
  • --local and --fallback-to-local are mutually exclusive.

Example:

npx branchlate@latest status --min-coverage=100

Example output:

The command lists each project (or sub-project), whether it is in sync, and for each language the validated percentage and count. Languages below the minimum coverage are shown in red; unvalidated keys are listed when there are few enough to display.

$ npx branchlate@latest status
npx branchlate@latest status
⚠️ notifications: local files are out of sync with remote
🇺🇸 en 90.5% validated (19/21)
- bookContextRelated
- bookContextAbout
🇫🇷 fr 100.0% validated (21/21)
✓ categories: in sync
🇺🇸 en 100.0% validated (873/873)
🇫🇷 fr 100.0% validated (873/873)

status --json (structured output for CI)

npx branchlate@latest status --json
{
"branch": "main",
"minCoverage": 100,
"projects": [
{
"project": "notifications",
"isOutOfSync": true,
"languages": [
{
"language": "en",
"totalKeys": 21,
"validatedCount": 19,
"unvalidatedCount": 2,
"validatedPercentage": 90.47,
"unvalidatedKeys": ["bookContextRelated", "bookContextAbout"]
},
{
"language": "fr",
"totalKeys": 21,
"validatedCount": 21,
"unvalidatedCount": 0,
"validatedPercentage": 100,
"unvalidatedKeys": []
}
]
}
],
"summary": {
"anyOutOfSync": true,
"anyBelowCoverage": true,
"exitCode": 1
}
}

Use the JSON output in CI scripts to parse results programmatically, for example with jq:

# Get languages below 100% coverage
npx branchlate@latest status --json | jq '.projects[].languages[] | select(.validatedPercentage < 100)'

Local-only check​

Not every Git branch needs a corresponding branch in Branchlate. Quick fixes, hotfixes, or translations received directly from translators may not go through the full Branchlate workflow. In those cases, you still want to make sure no translation key is missing before merging.

--local checks that every key in the reference language exists with a non-empty value in all other languages. No remote branch comparison is performed — only local file consistency is verified.

npx branchlate@latest status --local

Fallback to local (--fallback-to-local)​

In CI, you typically want to run status on every branch. Some branches are synced with Branchlate (and benefit from the full remote comparison), while others are not. --fallback-to-local handles both cases: it runs the normal remote check when the branch exists on Branchlate, and automatically falls back to a local key-completeness check when it doesn't.

This is the recommended option for CI pipelines that run on all branches:

npx branchlate@latest status --fallback-to-local --min-coverage=100

generate-token​

Generate an authentication token for CI/CD environments.

npx branchlate@latest generate-token --name "GitHub Actions"

This command outputs a token that can be used in CI/CD pipelines to authenticate non-interactively. It must be run from a session opened with login: a CI token cannot generate other tokens.

Options:

  • --name <name>: Name identifying the token in token list, for example the pipeline or the CI provider using it (up to 64 characters). (CLI 1.4.0+)

Example:

export BRANCHLATE_TOKEN=$(npx branchlate@latest generate-token --name "GitHub Actions")

Notes:

  • CI tokens do not expire. Store them as secrets in your CI provider and revoke the ones you no longer use.
  • Only the token is written to the standard output, so it can be captured with $(...). The other messages, including the ID used to revoke the token, are written to the standard error. (CLI 1.4.0+)
  • Logging out with logout does not revoke the CI tokens you generated.

token list​

List the CI/CD tokens you generated with generate-token. (CLI 1.4.0+)

npx branchlate@latest token list

For each token, the command shows its name, its ID, when it was created and when and from which IP address it was last used. A token you don't recognise, or one used from an unexpected IP address, should be revoked.

Options:

  • --json: Output the tokens as JSON.

Notes:

  • Tokens can only be managed from a session opened with login. The command fails when BRANCHLATE_TOKEN is set: a CI token cannot list or revoke tokens.

token revoke​

Revoke a CI/CD token. (CLI 1.4.0+)

npx branchlate@latest token revoke <id>

The ID of each token is shown by token list, and by generate-token when the token is created.

Options:

  • --force: Revoke without confirmation prompt.

Notes:

  • Pipelines using a revoked token can no longer authenticate. A pipeline already running when the token is revoked keeps its access for 5 minutes at most.
  • Revocation cannot be undone: generate a new token if needed.
  • Like token list, this command cannot be used with BRANCHLATE_TOKEN.

project delete​

Delete a project from Branchlate.

npx branchlate@latest project delete

Options:

  • --project-id <projectId>: Specify the slug of the project to delete.
  • --organisation-id <organisationId>: Specify the slug of the organisation.
  • --project <projectName>: Select which project of a multi-project configuration provides the default values.
  • --force: Skip confirmation prompts.

Example:

npx branchlate@latest project delete --project-id my-project --organisation-id my-org

Notes:

  • When using a CI token (BRANCHLATE_TOKEN), the --force option is automatically enabled, so you don't need to include it.
  • The command will use the project ID and organisation ID from your branchlate.json if not specified.
  • The --force option allows the command to proceed without a confirmation prompt, which is useful in automated scripts.

branch delete​

Delete a specific branch from a Branchlate project.

npx branchlate@latest branch delete

Options:

  • --branch-name <branchName>: Name of the branch to delete (defaults to current Git branch if not specified).
  • --project-id <projectId>: ID of the project containing the branch.
  • --organisation-id <organisationId>: ID of the organisation.
  • --project <projectName>: Select which project of a multi-project configuration provides the default values.
  • --force: Skip confirmation prompts.

Example:

npx branchlate@latest branch delete --branch-name feature/new-login --project-id my-project --organisation-id my-org

Notes:

  • If --branch-name is not specified, the current Git branch is used.
  • The branches that sync created for the sub-projects with the same branch name are deleted too.
  • When using a CI token (BRANCHLATE_TOKEN), the --force option is automatically enabled, so you don't need to include it.
  • The command will use the project ID and organisation ID from your branchlate.json if not specified.
  • The --force option allows the command to proceed without a confirmation prompt, which is useful in automated scripts.

CI/CD Integration​

The Branchlate CLI can be integrated into your CI/CD pipelines to automate translation synchronization and project management tasks.

Authentication in CI/CD​

To authenticate in CI/CD environments, use a token generated with the generate-token command. Set this token as an environment variable in your CI/CD environment.

Steps:

  1. Generate the token locally, naming it after the pipeline that will use it:

    npx branchlate@latest generate-token --name "GitHub Actions"
  2. Set the token as the BRANCHLATE_TOKEN environment variable in your CI/CD environment, as a secret (masked in the logs).

    export BRANCHLATE_TOKEN=<your-token>

When BRANCHLATE_TOKEN is set, the CLI operates in non-interactive mode, suitable for automated environments:

  • sync skips its confirmation prompts, as with --yes.
  • branch delete and project delete behave as with --force and --ignore-not-found.
  • sync does not enable --force: conflicts keep the Branchlate value, so a sync in CI never overwrites the work of translators. Don't add --force to a sync in CI: without prompts, it keeps the local value for every conflict.
Pin the CLI version in CI

The examples use npx branchlate@latest, which always runs the latest release. In CI, pin the version (e.g. npx branchlate@1.3.0) so that a new release cannot change the behavior of your pipelines, and upgrade it deliberately.

Securing CI/CD tokens​

A CI token gives access to your account and does not expire, so:

  • Use one token per pipeline, named with --name, so that you can revoke one without breaking the others.
  • Never commit a token or print it in the logs: store it in your CI provider's secrets.
  • Review your tokens regularly with token list, and check when and from which IP address each one was last used.
  • Revoke a token with token revoke as soon as it is no longer used or may have leaked. If you don't know which token leaked, revoke all of them and generate new ones.

A CI token is restricted to the commands of your pipelines: it cannot generate, list or revoke tokens. A leaked token therefore cannot be used to create new ones, and revoking it is enough.

Example CI/CD use cases​

In your CI/CD pipeline, you can use Branchlate commands to:

Sync translations and auto-translate on each commit​

Sync translations and automatically generate translations whenever a new commit is pushed to a branch:

npx branchlate@latest sync --branch-name ${CI_COMMIT_BRANCH} --auto-translate --no-wait

This keeps your translation files in sync with Branchlate’s database, ensuring that every commit reflects the latest translations. Using --no-wait ensures the build process isn't delayed by waiting for translations to complete.

Delete feature branches after merging​

Automatically delete feature branches in Branchlate once they are merged, cleaning up unused branches in your project.

npx branchlate@latest branch delete --branch-name ${CI_COMMIT_BRANCH} --project-id my-project --organisation-id my-org

Note: Since BRANCHLATE_TOKEN is used, the --force option is automatically enabled, so you don't need to include it.

Sync all projects of a monorepo​

In a multi-project repository, sync every linked project from the repository root in one command. Requires CLI 1.3.0 or later:

npx branchlate@latest sync --all-projects --branch-name ${CI_COMMIT_BRANCH}

Check translation coverage before release​

Ensure translations are complete and in sync before releasing. Run status on your release branch; it will exit with code 1 if any language is below 100% validated, or code 2 if local files are out of sync.

npx branchlate@latest status --min-coverage=100

If the command fails, fix translations or run sync, then re-run the check before deploying.

Check translation keys on every branch​

Not every branch needs to be synced with Branchlate — quick fixes or translations received directly from translators may skip the full workflow. Use --fallback-to-local so that synced branches get the full remote comparison, while other branches still get a local key-completeness check. This way, no branch can merge with missing translation keys.

npx branchlate@latest status --fallback-to-local --min-coverage=100

Parse status results in CI scripts​

Use --json to get structured output that can be parsed with tools like jq:

# Fail the pipeline and log which languages are incomplete
npx branchlate@latest status --json > status.json
if [ $? -ne 0 ]; then
echo "Incomplete translations:"
jq '.projects[].languages[] | select(.validatedPercentage < 100) | "\(.language): \(.validatedPercentage)%"' status.json
exit 1
fi

Best Practices​

  • Authentication: Ensure you are authenticated before running commands. Use npx branchlate@latest login to authenticate or set BRANCHLATE_TOKEN for CI/CD environments.
  • CI/CD tokens: Generate one named token per pipeline, keep it in your CI secrets, and revoke the ones you no longer use. See Securing CI/CD tokens.
  • Configuration file: The branchlate.json file stores your project configuration and should be version-controlled.
  • Monorepos: For repositories containing several applications, keep one branchlate.json per project and link them in a branchlate-root.json at the repository root, then target them with --project <name>. See Multi-Project Repositories.
  • Branch names: By default, the CLI uses the current Git branch name. Use the --branch-name option to specify a different branch if needed.
  • Error handling: The CLI provides error messages for common issues. If you encounter an error, ensure your configuration is correct and you have the necessary permissions.
  • Sub-projects: If your project uses sub-projects, ensure they are defined in your branchlate.json and understand how the sync command handles them.
  • Reference language: Define a reference language in your branchlate.json to control which keys are synchronized and maintain consistent key order across languages.
  • Flattened keys: Use the --flatten option if you prefer flat translation keys with dot notation. This can simplify key management and improve consistency.
  • Auto-translation: Use --auto-translate to automatically generate translations for new keys. Combine with --no-wait in CI/CD environments to avoid delays.
  • Formatting: Use format to keep translation files consistently sorted and indented. Use format --dry-run to preview changes before applying them.
  • Release checks: Use status in CI on release branches to ensure translations are 100% validated and in sync before deploying. The command exits with a non-zero code when coverage is insufficient or files are out of sync.
  • Non-interactive mode: When using BRANCHLATE_TOKEN, the CLI operates in non-interactive mode. Confirmation prompts are skipped, and branch delete and project delete automatically use --force and --ignore-not-found. sync never enables --force automatically, so the work of translators is preserved.
  • Up-to-date copy: Pull the latest commits of your Git branch before running sync, as it doesn't merge with the state of the previous sync.
  • CLI version in CI: Pin the CLI version in your pipelines instead of using @latest.

For further assistance or to explore more features, refer to the following sections: