CLI
Installation
Section titled “Installation”npm install -g babliAuthentication
Section titled “Authentication”Interactive login (local development):
babli loginOpens 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):
BABLI_API_KEY=<token> babli pushSet 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.
Quick Start
Section titled “Quick Start”babli loginbabli initbabli pushAgents must prepare and save key descriptions before translating the selected keys. Once descriptions cover the current source text:
babli translatebabli pullOr use the all-in-one workflow after preparing descriptions for its entire selected scope:
babli sync-and-translate --json --no-interactionsync-and-translate waits for translation automatically. It does not accept or need --wait.
Prepare descriptions before translation
Section titled “Prepare descriptions before translation”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:
babli push --json --no-interactionbabli key export --language en --output keys.json --json --no-interactionCreate 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:
babli key update --file descriptions.json --dry-run --json --no-interactionbabli key update --file descriptions.json --json --no-interactionResolve 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.
Global Flags
Section titled “Global Flags”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 |
Commands
Section titled “Commands”babli interactive
Section titled “babli interactive”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.
babli interactivebabli ibabli init
Section titled “babli init”Initialize a new Babli project in the current directory. Creates a babli.json config file.
babli initbabli init --host https://custom-host.example.com| Option | Default | Description |
|---|---|---|
--host <host> |
https://www.babli.ai |
Babli server host URL |
The wizard will:
- Prompt you to select an organization
- Ask for a project name
- Auto-detect existing translation files
- Generate a
babli.jsonconfig file
babli login
Section titled “babli login”Authenticate with Babli. Opens a browser for approval.
babli loginbabli logout
Section titled “babli logout”Remove stored authentication credentials.
babli logoutbabli push
Section titled “babli push”Push local keys and translations to the server.
babli pushbabli push --no-interactionbabli push --json --no-interactionbabli push --key "auth:*"babli push --namespace checkoutbabli push --prune --dry-run --jsonbabli push --prune --no-interactionIn 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.
babli pull
Section titled “babli pull”Pull translations from server to local files.
babli pullbabli pull --only-existingbabli pull --key hello --key byebabli pull --key auth:loginbabli 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.
babli status
Section titled “babli status”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.
babli statusbabli status --fullbabli status --jsonbabli 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.
babli translate
Section titled “babli translate”Trigger AI translation for missing translations. Starts an async job on the server and polls for completion.
babli translatebabli translate --languages cs,debabli translate --strategy missingbabli translate --dry-run --jsonbabli translate --estimate --jsonbabli translate --json --no-interaction --waitbabli translate --namespace speech --max-credits 7.00 --wait --jsonbabli translate --key-id key_123 --languages cs,debabli 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.
babli sync-and-translate
Section titled “babli sync-and-translate”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.
babli sync-and-translatebabli sync-and-translate --no-interactionbabli sync-and-translate --json --no-interactionbabli sync-and-translate --resolve serverbabli sync-and-translate --only-existingbabli sync-and-translate --prune --json --no-interactionbabli 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:
- 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
--pruneis supplied. Archived counts appear inphases.push.counts.archived_keys. - Questions — up to 3 rounds of answering context questions to improve translation quality
- Translate — requests AI translations and polls for completion
- 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.
babli quality
Section titled “babli quality”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.
babli quality check --job <translation-job-id> --estimate --jsonbabli quality check --namespace checkout --languages de,fr --source en --max-credits 2.00 --wait --jsonbabli quality show <run-id> --wait --jsonbabli quality decide --file decisions.json --json --no-interactionbabli quality check --recheck <result-id> --estimate --jsonbabli quality retry <run-id> --wait --jsonOne 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.
babli questions
Section titled “babli questions”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.
babli questionsbabli questions --jsonbabli questions --job <job-id> --jsonbabli questions --key-id <key-id> --languages de --jsonbabli questions --namespace checkout --jsonbabli 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.
Filtering by key and namespace
Section titled “Filtering by key and namespace”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}).
babli pull --key "auth:*" # all keys in the auth namespacebabli pull --key "user.profile.*" # keys under a prefix (default namespace)babli pull --namespace checkout # the whole checkout namespacebabli pull --namespace speech --key "mosquito.*" # key-name glob inside speechbabli push --key "auth:*" --namespace billing # AND: explicit auth namespace and billing (empty)--keymatches the key name. A colon separates an optional namespace glob from the key glob:auth:*means “key glob*in namespace globauth”. 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.--namespacematches the resolved namespace.*and**match all namespaces including the default (empty) one; pass--namespace ""to target only the default namespace.--keyand--namespacecombine 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,--jsoncounts, 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.
Surgical commands
Section titled “Surgical commands”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.
Key locators
Section titled “Key locators”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) |
babli key
Section titled “babli key”Manage remote project keys.
babli key list --query common --include-archivedbabli key get --key common.cancelbabli key add --key home.title --translation en="Welcome" --description "Landing headline"babli key update --key-id key_123 --description "..." --new-namespace marketingbabli key rename --key-id key_123 --to home.headingbabli key archive --key-id key_123babli key unarchive --key-id key_123key 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.
babli translation
Section titled “babli translation”Manage individual translations.
babli translation upsert --key-id key_123 --language cs --value "Ahoj"babli translation upsert --key-id key_123 --language cs --value-file ./cs.txtecho "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.
babli project
Section titled “babli project”List, create, read, and update projects and their translation instructions.
babli project listbabli project list --organization org_123babli project create --name "My App" --organization org_123babli project create --name "Docs" --organization org_123 --type document --languages en,cs,debabli project getbabli project get --project proj_123babli project update --name "My App"babli project update --description-file ./README.mdbabli project update --instructions-file ./babli-instructions.mdecho "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 |
babli organization
Section titled “babli organization”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.
babli organization listbabli organization get --organization ORG_IDbabli organization update --organization ORG_ID --name "Acme"babli organization update --organization ORG_ID --instructions-file ./company-instructions.mdecho "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.
babli glossary
Section titled “babli glossary”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.
babli glossary listbabli glossary list --project PROJECT_ID --include-inheritedbabli glossary list --organization ORG_IDbabli 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 debabli glossary remove TERM_ID --project PROJECT_IDbabli glossary move-to-organization TERM_ID --project PROJECT_IDupsert 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:
babli glossary export --project PROJECT_ID --output ./glossary.jsonbabli glossary import --project PROJECT_ID --file ./glossary.json --dry-runbabli glossary import --project PROJECT_ID --file ./glossary.jsonbabli glossary export --organization ORG_ID --output ./company-glossary.jsonbabli glossary import --organization ORG_ID --file ./company-glossary.jsoncat 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.
JSON output
Section titled “JSON output”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" }}CI/CD Integration
Section titled “CI/CD Integration”Combine --json and --no-interaction for fully automated pipelines:
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 textbabli sync-and-translate --json --no-interaction
# Or cap the exact cost for existing remote keysbabli translate --namespace speech --estimate --jsonbabli translate --namespace speech --max-credits 7.00 --wait --jsonbabli pull --namespace speech --json --no-interaction
# Estimate an AI reviewbabli quality check --estimate --jsonExit Codes
Section titled “Exit Codes”| 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. |