CLI

Installation

npm install -g babli

Authentication

Interactive login (local development):

babli login

Opens a browser to approve access via a unique request code. The token is stored locally.

API key (CI/CD):

BABLI_API_KEY=<token> babli push

Set BABLI_API_KEY as an environment variable to skip interactive login.

Quick Start

babli login
babli init
babli push
babli translate
babli pull

Or use the all-in-one workflow:

babli sync-and-translate

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

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 interactive
babli i

babli init

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

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

babli login

Authenticate with Babli. Opens a browser for approval.

babli login

babli logout

Remove stored authentication credentials.

babli logout

babli push

Push local keys and translations to the server.

babli push
babli push --no-interaction
babli push --json --no-interaction

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

babli pull

Pull translations from server to local files.

babli pull
babli pull --only-approved

Option	Default	Description
--only-approved	false	Only pull translations that have been approved
--only-existing	false	Only pull updates to keys that already exist locally

babli status

Show sync status between local files and server. Exits with code 1 if there are changes to push or pull.

babli status
babli status --full
babli status --json

babli translate

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

babli translate
babli translate --languages cs,de
babli translate --timeout 600
babli translate --key-id key_123 --languages cs,de

Option	Default	Description
--languages <codes>	all	Comma-separated language codes to translate
--key-id <id>	—	Translate this remote key directly, bypassing local sync status
--timeout <seconds>	300	Maximum wait time for the translation job

If the job times out, it continues on the server. Rerun the command to check progress.

babli sync-and-translate

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

babli sync-and-translate
babli sync-and-translate --no-interaction

The workflow:

1. Push — syncs local keys to the server, prompts to handle server-only 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

babli questions

Show and answer unanswered translation context questions. Answering questions improves translation quality.

babli questions
babli questions --json

babli review

Review and approve translations. Groups translations by quality score.

babli review
babli review --no-interaction
babli review --score-threshold 90

Option	Default	Description
--score-threshold <score>	80	Minimum quality score for auto-approval in non-interactive mode

In interactive mode, you approve high-score and low-score translations separately. In non-interactive mode, translations meeting the threshold are auto-approved.

babli proofread

Run AI proofreading on unapproved translations. Shows token-level suggestions with explanations.

babli proofread
babli proofread --languages cs,de

Option	Description
--languages <codes>	Comma-separated language codes to proofread

Suggestions are saved on the server for review in the dashboard.

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

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

Manage remote project keys.

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 an approved translation; 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.

Option	Description
--to <new-key>	required — new key name

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

babli translation

Manage individual translations.

babli translation upsert --key-id key_123 --language cs --value "Ahoj" --approve
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 -
babli translation approve <translation-id>
babli translation unapprove <translation-id>

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
--approve	Approve the translation

Provide exactly one of --value or --value-file. Upsert preserves the existing approval state of a translation; pass --approve to force it approved.

translation approve / translation unapprove — take the translation id as a positional argument.

babli project

List, create, read, and update projects and the global translation prompt.

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.

Option	Description
--name <name>	Project name
--description <text>	Project description
--description-file <path>	Read description from a file, or - for stdin
--instructions <text>	Global translation instructions (prompt)
--instructions-file <path>	Read instructions from a file, or - for stdin

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

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

export BABLI_API_KEY=$TOKEN

# Check if translations are in sync (exits 1 if not)
babli status --json

# Push new keys, translate, and pull results
babli push --json --no-interaction
babli translate --languages de,fr --timeout 600 --json --no-interaction
babli pull --json

# Auto-approve high-quality translations
babli review --no-interaction --score-threshold 90 --json

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.