Skip to content

CLI

Terminal window
npm install -g babli

Interactive login (local development):

Terminal window
babli login

Opens a browser to approve access via a unique request code. The token is stored locally in a babli_k file next to the installed CLI, and reused on subsequent commands. Run babli logout to remove it.

API key (CI/CD):

Terminal window
BABLI_API_KEY=<token> babli push

Set BABLI_API_KEY as an environment variable to skip interactive login. When set, it takes precedence over a stored login token, so no babli login is needed in CI.

Terminal window
babli login
babli init
babli push

Agents must prepare and save key descriptions before translating the selected keys. Once descriptions cover the current source text:

Terminal window
babli translate
babli pull

Or use the all-in-one workflow after preparing descriptions for its entire selected scope:

Terminal window
babli sync-and-translate --json --no-interaction

sync-and-translate waits for translation automatically. It does not accept or need --wait.

Agents must inspect code usages and prepare descriptions for new or changed keys before translating them. Preserve accurate existing descriptions; write missing or outdated ones with the UI role, intended meaning, and placeholder meanings.

Push new keys and source changes first, then export fresh context using the project’s source language in place of en:

Terminal window
babli push --json --no-interaction
babli key export --language en --output keys.json --json --no-interaction

Create descriptions.json using the exported project, language, and key IDs:

{
"version": 1,
"projectId": "<project UUID from export>",
"language": "en",
"items": [
{
"keyId": "<key UUID from export>",
"expectedDescription": null,
"expectedSourceVersionId": "<source version UUID from export>",
"description": "Button that submits the booking and opens the payment step.",
"status": "drafted"
},
{
"keyId": "<another key UUID from export>",
"status": "unresolved",
"reason": "No reliable usage context found."
}
]
}

Copy each key’s description into expectedDescription exactly, including null, and its sourceVersionId into expectedSourceVersionId. Keys with null source text or version need source text before drafting. Unresolved entries are skipped. Changed source versions or unexpected descriptions reject the affected batch; earlier successful batches remain saved. Dry-run checks current state without reserving it, and applying checks again. Check and save before dispatching translation:

Terminal window
babli key update --file descriptions.json --dry-run --json --no-interaction
babli key update --file descriptions.json --json --no-interaction

Resolve conflicts before proceeding. Record unclear keys as unresolved and exclude them from translation until clarified; use translate --key-id <id> for a resolved subset. Do not invent descriptions. After source or usage changes, push first and revisit affected descriptions. sync-and-translate does not pause for this work between push and translation.

This is required agent guidance; the CLI does not automatically enforce description coverage. Estimate, translate, and pull only the prepared scope.

These flags work with all commands:

Flag Description
--json Output results as JSON (stable schema for agents/CI)
--no-interaction Skip all prompts, use safe defaults
--full Show all items without truncation
-V, --version Display CLI version

Launches the interactive dashboard showing your project’s sync status: keys to push, translations to pull, and unanswered questions. Presents a menu to run any workflow directly.

Running babli with no arguments in an interactive terminal does the same; outside a terminal (CI, pipes) it prints help instead.

Terminal window
babli interactive
babli i

Initialize a new Babli project in the current directory. Creates a babli.json config file.

Terminal window
babli init
babli init --host https://custom-host.example.com
Option Default Description
--host <host> https://www.babli.ai Babli server host URL

The wizard will:

  1. Prompt you to select an organization
  2. Ask for a project name
  3. Auto-detect existing translation files
  4. Generate a babli.json config file

Authenticate with Babli. Opens a browser for approval.

Terminal window
babli login

Remove stored authentication credentials.

Terminal window
babli logout

Push local keys and translations to the server.

Terminal window
babli push
babli push --no-interaction
babli push --json --no-interaction
babli push --key "auth:*"
babli push --namespace checkout
babli push --prune --dry-run --json
babli push --prune --no-interaction

In interactive mode, you confirm each step. With --no-interaction, all changes are pushed without prompts.

Option Default Description
--resolve <strategy> — Resolve conflicts non-interactively: local or server
--prune false Archive server keys absent from local translation files, within the selected key and namespace scope
--allow-empty-prune false Permit archiving when no configured local files are found; does not enable pruning by itself
--dry-run false Preview the push and archive plan without writing to the server or prompting
--key <pattern> — Only push keys matching this glob. Repeatable. See Filtering by key and namespace
--namespace <pattern> — Only push keys in namespaces matching this glob. Repeatable

When a filter narrows the push, the output reports how many keys were selected and how many other local changes were withheld; --json includes a filter object with the same counts.

Use push --prune to clean up keys without starting AI translation. It also pushes any other local changes in scope and works when archiving is the only change. Preview with push --prune --dry-run; JSON previews use status dry_run and list candidates in summary.archived_keys. Normal pushes keep server-only keys unless --prune is supplied, including in noninteractive mode.

Pruning compares against all configured local translation files, not application code usage. A key still present in any local language file is kept. Ensure those files represent the intended project scope. Archived keys retain their translations and can be restored with babli key unarchive.

If no configured local files are found, archiving stops with an error, including during dry runs. Check your file paths, or explicitly allow this with --allow-empty-prune. Existing files containing no keys are valid inputs. Archives are applied only after all upload batches succeed, so failed uploads keep the old keys active. Upload batches that already succeeded remain on the server.

Pull translations from server to local files.

Terminal window
babli pull
babli pull --only-existing
babli pull --key hello --key bye
babli pull --key auth:login
babli pull --key "user.profile.*"
babli pull --namespace checkout
Option Default Description
--only-existing false Only pull updates to keys that already exist locally (never adds or removes keys)
--keep-local-only false Keep keys that exist only in local files instead of removing them
--key <pattern> — Only pull keys matching this glob. Repeatable. See Filtering by key and namespace
--namespace <pattern> — Only pull keys in namespaces matching this glob. Repeatable

A full pull makes the server the source of truth for standard translation files. Keys that exist only locally are removed, including never-pushed keys and keys in files with no remaining server keys. Interactive runs show the removals first and ask whether to proceed, noninteractive runs remove them and print the list, and --json reports them in removed_keys. Push local content you want to retain before pulling, or use --keep-local-only. Scoped pulls with --key, --namespace, or --only-existing preserve local-only keys and leave keys outside their scope untouched. Emptied source or namespace files are deleted; fixed locale files are written with empty translation content. Files outside the configured translation patterns are untouched. Custom transforms have separate preservation behavior; see the rename limitation below.

Show file synchronization and remote translation coverage. Exits with code 1 only when the scoped local files and server differ; translation gaps alone keep exit code 0.

Terminal window
babli status
babli status --full
babli status --json
babli status --namespace speech --key "mosquito.*"

--json adds translation_coverage, which distinguishes complete coverage, actionable gaps, and gaps blocked by a missing approved reference. File synchronization and translation coverage are separate: clean local files do not imply that every remote target language has a value.

Trigger AI translation for missing translations. Starts an async job on the server and polls for completion.

Terminal window
babli translate
babli translate --languages cs,de
babli translate --strategy missing
babli translate --dry-run --json
babli translate --estimate --json
babli translate --json --no-interaction --wait
babli translate --namespace speech --max-credits 7.00 --wait --json
babli translate --key-id key_123 --languages cs,de
babli translate --namespace checkout
Option Default Description
--strategy <strategy> missing Generate absent values with missing, or replace explicitly selected keys with replace. not-approved selects values with neither a current AI pass nor human approval.
--primary-language <code> sole source Choose the primary source when a project has more than one.
--reference-mode <mode> either Supporting references accept a current AI pass or human approval (either), or can be restricted to AI (ai) or human (human) reviews.
--languages <codes> all Comma-separated language codes to translate
--only-existing false Only translate keys that exist in your local files
--key <pattern> — Only translate keys matching this glob. Repeatable. See Filtering by key and namespace
--namespace <pattern> — Only translate keys in namespaces matching this glob. Repeatable
--key-id <id> — Translate this remote key directly, bypassing local sync status (repeatable; cannot be combined with --key/--namespace)
--key-ids <ids> — Translate these key ids (comma-separated)
--model <model> production Translation model: production or preview
--dry-run false Print the work-set without spending credits or starting a job
--estimate false Print the real credit cost without spending or starting a job
--max-credits <amount> — Refuse dispatch if the authoritative packed cost exceeds this credit amount (at most two decimal places)
--wait false Block and poll until the job finishes (in non-interactive mode the command otherwise returns the job id immediately)
--timeout <seconds> 300 Maximum wait time when polling the translation job

--dry-run and --estimate are mutually exclusive. Their JSON output includes complete, untruncated namespaced work_items. Human dry-run shows the first 10 items; add --full to show all. Use --estimate as the authoritative cost: process packing is non-linear, so the result cannot be derived reliably from the number of keys or languages. Neither command spends credits or starts a job.

For new local keys, push first so the server can produce an exact estimate. Under missing, a non-empty target draft counts as present. Use --strategy not-approved for values with neither a current AI pass nor human approval. Use --strategy replace --key <key> (or --key-id / --namespace) to request replacements. If wording, reviews, or context changes during generation, the generated text remains a candidate for a reviewer to inspect.

If a waited job times out, it continues on the server and the CLI exits 2 with the existing job id and last observed progress. Run babli job <job_id> --wait; do not rerun translate, because that could dispatch and charge another job.

In JSON, summary.keys and summary.language_pairs describe requested translation coverage. process_counts describes server execution processes, including preview processes absorbed into another result; it is not key progress. billing.billable_processes excludes absorbed processes. credits_charged is deducted when the job is dispatched, even if processing later fails.

All-in-one workflow: push changes, answer context questions, translate, and pull results.

Agents must prepare descriptions for every selected key before running this command. For new keys or changed source text, push separately, prepare and save descriptions, then run the workflow. It does not author descriptions or pause for their preparation.

Terminal window
babli sync-and-translate
babli sync-and-translate --no-interaction
babli sync-and-translate --json --no-interaction
babli sync-and-translate --resolve server
babli sync-and-translate --only-existing
babli sync-and-translate --prune --json --no-interaction
babli sync-and-translate --namespace speech --key "mosquito.*" --languages cs,de --max-credits 7.00
Option Default Description
--resolve <strategy> — Resolve push conflicts non-interactively: local or server
--prune false Archive all server-only keys in scope without asking, including in noninteractive mode
--allow-empty-prune false Permit archiving when no configured local files are found; does not enable pruning by itself
--only-existing false Only translate and pull keys that exist in your local files
--key <pattern> — Scope status, push, translation, questions, server-only-key handling, and pull. Repeatable
--namespace <pattern> — Apply the same workflow scope by namespace. Repeatable
--languages <codes> all Scope translation and translation questions only; pull still retrieves available languages for selected keys
--model <model> production Translation model: production or preview
--max-credits <amount> — Maximum cumulative charge across all translation rounds
--timeout <seconds> 300 Maximum time to wait for each translation job

The workflow:

  1. Push — syncs local keys to the server and handles server-only keys even when there are no uploads. Interactive runs offer keep, select, or archive all; noninteractive runs keep them unless --prune is supplied. Archived counts appear in phases.push.counts.archived_keys.
  2. Questions — up to 3 rounds of answering context questions to improve translation quality
  3. Translate — requests AI translations and polls for completion
  4. Pull — pulls completed translations back to local files. Interactive runs ask what to pull even when the only local gap is server-only keys you kept. Noninteractive runs pull other translations but do not recreate local keys you kept on the server.

If the credit cap rejects translation after a push, the pushed data remains. No translation charge or job is created, and the workflow still pulls already-available scoped values before exiting 2.

Completed translate --wait, job, and sync-and-translate output includes follow_up. Check questions_status (checked, pending, or unavailable) and each question’s full identity, namespace, and relevance (requested_job, earlier, or unscoped). Generation can be complete with unanswered questions. A failed question fetch must be retried; it is not evidence that no questions exist. Sync also checks the selected scope when generation is skipped.

Agents should answer using repository evidence or explicit product decisions, ask the user about unknown facts, and report unresolved items. Review earlier questions for continued relevance. Saving answers does not verify current wording. Returned next_actions point to affected keys for inspection; repeating missing-only sync will skip existing text. Spending requires the remaining authorized --max-credits allowance. Existing approvals are never silently removed. Linguistic review is reported separately as not_requested until explicitly run.

Linguistic review is requested and resolved through the CLI. The web Review tab is read-only. A current AI pass is sufficient approval; human approval is an alternative.

Terminal window
babli quality check --job <translation-job-id> --estimate --json
babli quality check --namespace checkout --languages de,fr --source en --max-credits 2.00 --wait --json
babli quality show <run-id> --wait --json
babli quality decide --file decisions.json --json --no-interaction
babli quality check --recheck <result-id> --estimate --json
babli quality retry <run-id> --wait --json

One configured reviewer checks existing default-type translations against the source, descriptions, instructions, glossary, saved answers, and stored usages. Source ambiguity and missing targets are explicit; no generation or approval starts implicitly. Estimate first, submit with an explicit --max-credits cap, and retain the printed --request-id for uncertain retries. Gemini 4 Argon is the only enabled reviewer. --model gemini-4-argon remains accepted; other models are rejected. Historical runs remain readable, but disabled reviewers cannot execute or be retried.

Each batch costs 1 credit (100 units). Review shares translation’s token accounting and two-stage packer. It groups targets by locale, uses the standard 8,000-token key-size heuristic for initial packing, then checks the complete prompt and splits oversized groups. Input accounting includes every message part and the response schema, with 30% headroom. There is no fixed number of keys per batch. Full input, including the prompt and schema, must fit the shared 100,000 estimated tokens. The reviewer performs all six checks but emits only clean-key IDs and detailed findings. Output estimates assume findings for 5% of fresh keys, with full detail reserved for rechecks; this is a planning heuristic, not a measured defect rate. Report output plus reserved reasoning must fit Argon’s 32,768-token allowance, with one quarter reserved for reasoning. Native continuation can resume truncated output once within that total allowance; incomplete coverage is never treated as a pass. Inputs or reports that cannot fit alone are skipped with a reason; partially filled batches cost the full batch price. Estimates report credit_units_per_batch, the total in units of 0.01 credits, and per-batch target counts and token budgets in batch_estimates.

Format failures are reported before paid linguistic review. Track the total workflow budget across commands. Failed execution refunds once; the original user can request one additional execution attempt without a second debit. Valid findings and questions are billable work.

Agents must evaluate findings against evidence. Decision files contain a decisions array; each item needs a stable UUID requestId, resultId, expectedRevision, exact inputHash, findingIds, action, and reason. Actions are apply (also value), dismiss, clarify (also answer), and defer; evidence is an optional list of supporting references. Use one final replacement per translation. Changed wording is unapproved and needs explicit recheck; dismissals never rewrite the reviewer report into a pass. Unknown product facts go to the user, and unresolved linguistic judgments remain visible.

Review clarifications apply to explicit rechecks of that result. Save facts into appropriate existing context when future generation or independent reviews need them. Results distinguish reviewer outcome, agent judgment, freshness, coverage, and approval. Completion with findings exits 0; execution failure, timeout, or rejected decisions exits 2. Approval is a current AI pass or human approval. Pulls include every stored value.

Show and answer unanswered generation, human, and AI-review questions. Generation answers are applied during the next translation of their key and language; review answers record a reply without requiring regeneration.

Terminal window
babli questions
babli questions --json
babli questions --job <job-id> --json
babli questions --key-id <key-id> --languages de --json
babli questions --namespace checkout --json
babli questions --answers-file answers.json --json --no-interaction

--json lists complete questions without prompting. To submit answers, provide a JSON object with an answers array. Each item needs keyId, languageId, questionText (the exact question returned by the listing), and answer. Include the returned questionId to identify the exact question, especially when different origins share the same text. Listings include origin and translationType. Older answer files without questionId are accepted only when the match is unambiguous.

Submission requires a user token from babli login. Project API keys can list questions. Batches are atomic: invalid or unknown entries reject the entire batch. The JSON response includes remaining questions and retranslationRequired. For generation answers, inspect the affected wording and authorize regeneration only when needed. Human and AI-review replies leave cached scores unchanged; answering alone does not increase quality scores.

status, push, pull, translate, and sync-and-translate accept repeatable --key and --namespace flags to scope an operation to a subset of keys. Both accept glob patterns (*, **, ?, [...], {a,b}).

Terminal window
babli pull --key "auth:*" # all keys in the auth namespace
babli pull --key "user.profile.*" # keys under a prefix (default namespace)
babli pull --namespace checkout # the whole checkout namespace
babli pull --namespace speech --key "mosquito.*" # key-name glob inside speech
babli push --key "auth:*" --namespace billing # AND: explicit auth namespace and billing (empty)
  • --key matches the key name. A colon separates an optional namespace glob from the key glob: auth:* means “key glob * in namespace glob auth”. Without --namespace, a colon-less pattern matches only the default (empty) namespace. With --namespace speech, the same pattern matches key names inside that namespace. A bare * or ** always spans all namespaces.
  • --namespace matches the resolved namespace. * and ** match all namespaces including the default (empty) one; pass --namespace "" to target only the default namespace.
  • --key and --namespace combine with AND — a key must match both axes.
  • Matching is case-sensitive. Quote your patterns so the shell doesn’t expand * against local filenames.
  • A pattern that matches no keys is a fail-fast error (it lists the offending pattern). A pattern that matches keys with nothing to push/pull is a clean no-op.
  • When filtering scopes an operation, status, --json counts, and exit codes reflect only the selected subset.

When --key/--namespace is combined with --key-id/--key-ids on translate, the command errors — explicit key ids bypass local sync, so name-based filtering does not apply.

push/pull remain the preferred way to sync in bulk. The commands below make targeted, single-item changes directly on the server — useful for scripts and AI agents. They all support --json and return the stable JSON contract described under JSON output.

Commands that act on a single key accept the key either by id or by name:

Option Description
--key-id <id> Look up the key by its remote id (takes precedence)
--key <name> Look up the key by name
--namespace <namespace> Namespace to disambiguate --key (optional)

Manage remote project keys.

Terminal window
babli key list --query common --include-archived
babli key get --key common.cancel
babli key add --key home.title --translation en="Welcome" --description "Landing headline"
babli key update --key-id key_123 --description "..." --new-namespace marketing
babli key rename --key-id key_123 --to home.heading
babli key archive --key-id key_123
babli key unarchive --key-id key_123

key list

Option Description
--query <text> Filter by key text
--include-archived Include archived keys

key get — accepts a key locator.

Option Description
--include-archived Allow looking up an archived key

key add

Option Default Description
--key <name> required Key name
--namespace <namespace> "" Key namespace
--source <text> "" Source metadata
--description <text> — Key description
--translation <code=value> — Add unreviewed wording; repeatable (e.g. --translation en="Hi" --translation cs="Ahoj")

key update — accepts a key locator.

Option Description
--new-namespace <namespace> Move the key to a new namespace
--source <text> Update source metadata
--description <text> Update description

key rename — accepts a key locator, or an atomic manifest.

Option Description
--to <new-key> New key name for a single-key rename
--file <path> JSON manifest of 1–1,000 renames; - reads stdin
--dry-run Validate the manifest without writing
--allow-unpushed Rename even when local files have changes that are not pushed

File mode renames keys, moves namespaces, and changes source file placement together. Build each item from key export: copy key to expectedKey, namespace to expectedNamespace, and source to expectedSource. Copy keyId and the export projectId as they are. Leave description, sourceText, and sourceVersionId off the manifest. Extra fields are rejected as invalid_rename_file. to is required. Omit toNamespace or toSource to keep the current value; "" clears it.

{
"version": 1,
"projectId": "<project UUID from export>",
"items": [
{
"keyId": "<key UUID from export>",
"expectedKey": "vouchers.title",
"expectedNamespace": "",
"expectedSource": "datatable/vouchers",
"to": "commerce.vouchers.title",
"toNamespace": "",
"toSource": "commerce/vouchers"
}
]
}

The whole manifest is rejected when any item is stale, archived, or would collide, including with an archived key. Swaps and chains are applied in one transaction. A retry counts as unchanged when the key already has the complete requested name, namespace, and source.

With --json, success and failure are separate documents. Success status is dry_run or renamed. A completed retry shows counts.unchanged and items[].status of unchanged; the top-level status stays renamed or dry_run. Each item uses key_id and from / to objects with key, namespace, and source. file_changes is taken from the manifest before the request, and each key_id there is lowercase. On a retry, items[].from is the state already stored, while file_changes[].from still lists the paths from that manifest.

{
"version": 1,
"command": "key_rename",
"status": "renamed",
"project_id": "<project UUID>",
"dry_run": false,
"counts": { "total": 1, "renamed": 1, "would_rename": 0, "unchanged": 0 },
"items": [
{
"index": 0,
"key_id": "<key UUID>",
"status": "renamed",
"from": {
"key": "vouchers.title",
"namespace": "",
"source": "datatable/vouchers"
},
"to": {
"key": "commerce.vouchers.title",
"namespace": "",
"source": "commerce/vouchers"
}
}
],
"file_changes": [
{
"index": 0,
"key_id": "<key UUID>",
"from": ["<paths for the expected placement>"],
"to": ["<paths for the requested placement>"]
}
]
}

A failure uses the error envelope. Conflicts are at error.details.conflicts.

{
"version": 1,
"status": "error",
"error": {
"message": "Conflict",
"code": "rename_conflict",
"http_status": 409,
"details": { "conflicts": [] }
}
}

Follow one order: push, rename, pull. Push first so every local key and translation is on the server; the command refuses to run while babli status reports unpushed changes, unless you pass --allow-unpushed. Update local references, apply the manifest, then pull. Do not push between the rename and the pull: sync matches keys by namespace and name, so a push would recreate the old names as new keys. Pull writes the new names and source placements, removes the old names as local-only keys, and deletes a source or namespace file when every key in it moved, including when all its keys were renamed. The JSON success document lists the pull in next_actions. Single-key --to remains separate from --file.

Before applying a manifest, the CLI previews the resulting standard-file output. Parent/child key collisions in nested output (such as title and title.short) and destination paths differing only by case or Unicode normalization are rejected as invalid_rename_output. Use different key names or nested: false for nested collisions, and distinct destination paths for file collisions. The path restriction applies on all platforms. Pull also validates its output before writing files.

Custom transforms are not covered by this output validation or old-key cleanup. A pull through a transform can retain the old names after a rename. Update the transformed content manually to remove those names, then check babli status before pushing.

key archive / key unarchive — accept a key locator; no extra options.

Manage individual translations.

Terminal window
babli translation upsert --key-id key_123 --language cs --value "Ahoj"
babli translation upsert --key-id key_123 --language cs --value-file ./cs.txt
echo "Ahoj" | babli translation upsert --key-id key_123 --language cs --value-file -

translation upsert — accepts a key locator.

Option Description
--language <code> required — language code
--value <text> Translation value
--value-file <path> Read the value from a file, or - for stdin

Provide exactly one of --value or --value-file. Unchanged wording retains its review evidence. Changed wording needs a current AI pass or human approval.

List, create, read, and update projects and their translation instructions.

Terminal window
babli project list
babli project list --organization org_123
babli project create --name "My App" --organization org_123
babli project create --name "Docs" --organization org_123 --type document --languages en,cs,de
babli project get
babli project get --project proj_123
babli project update --name "My App"
babli project update --description-file ./README.md
babli project update --instructions-file ./babli-instructions.md
echo "Translate formally." | babli project update --instructions-file -

project list — lists projects grouped by organization. Works without a babli.json.

Option Description
--organization <id> Filter to a single organization

project create — creates a project. Works without a babli.json.

Option Default Description
--name <name> required Project name
--organization <id> required Organization id
--type <type> key Project type: key or document
--description <text> — Project description
--languages <codes> — Comma-separated language codes; the first is the source

project get — reads project metadata.

Option Description
--project <id> Project id (defaults to the babli.json project; works without a babli.json when set)

project update — pass at least one field. Both get and update accept --project <id> and work without a babli.json when it is supplied. project get --include-inherited includes the organization name and instructions; project instructions take precedence where they conflict.

Option Description
--project <id> Project id (defaults to babli.json)
--name <name> Project name
--description <text> Project description
--description-file <path> Read description from a file, or - for stdin
--instructions <text> Project translation instructions
--instructions-file <path> Read instructions from a file, or - for stdin

Read organizations and update their name and shared translation instructions. Organization commands require a user access token from babli login; project API keys cannot manage organizations. Renaming requires organization owner permissions. Editing instructions and organization glossary terms requires organization editor or owner permissions.

Terminal window
babli organization list
babli organization get --organization ORG_ID
babli organization update --organization ORG_ID --name "Acme"
babli organization update --organization ORG_ID --instructions-file ./company-instructions.md
echo "Keep product names unchanged." | babli organization update --organization ORG_ID --instructions-file -

Organization instructions apply to all projects. Organizations currently have no description field. Project descriptions provide project context. For metadata updates, omitted fields stay unchanged and empty strings clear instructions or descriptions. Direct text and file input for the same field are mutually exclusive; only one field can read stdin.

Manage project or organization glossary terms. The default scope is the project in babli.json. Pass --project <id> to select another project or --organization <id> for company terms; the selectors are mutually exclusive. Explicit selectors work without a babli.json.

Terminal window
babli glossary list
babli glossary list --project PROJECT_ID --include-inherited
babli glossary list --organization ORG_ID
babli glossary get TERM_ID --project PROJECT_ID
babli glossary upsert --project PROJECT_ID --term "Workspace" --source-language en --translation cs="Pracovní prostor" --translation de="Arbeitsbereich"
babli glossary upsert --organization ORG_ID --term "Babli" --source-language en --description "Brand name; do not translate."
babli glossary update TERM_ID --project PROJECT_ID --description "A container for projects."
babli glossary update TERM_ID --project PROJECT_ID --term "Team workspace"
babli glossary update TERM_ID --project PROJECT_ID --translation cs="Pracovní prostředí"
babli glossary update TERM_ID --project PROJECT_ID --remove-translation de
babli glossary remove TERM_ID --project PROJECT_ID
babli glossary move-to-organization TERM_ID --project PROJECT_ID

upsert identifies a term by its scope, exact term text, and source language. Whitespace in stored identities is preserved when editing, exporting, and importing terms. Repeated --translation code=value flags merge by target language and preserve omitted languages. Notes are also preserved when omitted. Use --description "" to clear a note, or update --remove-translation <code> to delete a target translation. update can rename a term or change its source language; a duplicate identity is rejected.

list --include-inherited also shows company terms, labeling every entry with its owning scope. Company terms apply across projects. For matching term text, source language, and target language, project translations take precedence. Editing an inherited term requires organization scope and organization permissions. Moving a project term to its organization requires both project write and organization management permissions, and fails if the organization already has that term in the same source language.

Export and import use the same portable JSON format:

Terminal window
babli glossary export --project PROJECT_ID --output ./glossary.json
babli glossary import --project PROJECT_ID --file ./glossary.json --dry-run
babli glossary import --project PROJECT_ID --file ./glossary.json
babli glossary export --organization ORG_ID --output ./company-glossary.json
babli glossary import --organization ORG_ID --file ./company-glossary.json
cat glossary.json | babli glossary import --file -
babli glossary list --include-inherited --json --no-interaction
{
"version": 1,
"terms": [
{
"term": "Workspace",
"sourceLanguageCode": "en",
"description": "A container for projects.",
"translations": { "cs": "Pracovní prostor", "de": "Arbeitsbereich" }
}
]
}

Exports contain only terms owned by the selected scope and omit database IDs, so the file can be imported into another scope. Imports validate the entire file, reject duplicate term/source pairs, and merge all terms in one transaction. Unrelated terms and omitted target languages remain unchanged. A file supports up to 10,000 terms. --dry-run validates the file and write permissions without changing data.

With --json, every command prints a single JSON object with a stable schema. Success responses share this shape:

{
"version": 1,
"command": "key_archive",
"status": "archived",
"key": { "id": "key_123", "key": "home.title", "deleted": "2026-06-12T13:45:10.223Z" }
}

Errors print an error envelope and exit with code 2:

{
"version": 1,
"status": "error",
"error": { "message": "Key not found" }
}

Combine --json and --no-interaction for fully automated pipelines:

Terminal window
export BABLI_API_KEY=$TOKEN
# Check local file synchronization (exits 1 only for file-sync differences)
babli status --json
# Run only after descriptions cover every selected key and current source text
babli sync-and-translate --json --no-interaction
# Or cap the exact cost for existing remote keys
babli translate --namespace speech --estimate --json
babli translate --namespace speech --max-credits 7.00 --wait --json
babli pull --namespace speech --json --no-interaction
# Estimate an AI review
babli quality check --estimate --json
Code Meaning
0 Success
1 status command only: local and server are out of sync
2 Any error — invalid arguments, missing config, not logged in, request failed, etc.