CLI Reference

The Babelon CLI (babelon) is a Rust-based command-line tool for uploading, translating, and downloading localized content. It connects to the Babelon backend using API tokens.

Installation

Download the latest release for your platform from the Babelon releases page, or build from source:

bash

cd babelon-cli
cargo build --release

The binary is at target/release/babelon.

Configuration

The CLI reads configuration from .babelon.toml in the current directory (or a path specified with --config).

Example `.babelon.toml`

toml

supabase_url   = "https://your-project.supabase.co"
client_id      = "bbl_cid_a1b2c3d4e5f6g7h8"
api_token      = "bbl_tok_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
tenant_id      = "your-tenant-uuid"

source_locale  = "en"
target_locales = ["es", "fr", "de", "ja"]

[files]
path       = "locales/{locale}.json"
format     = "json"

Configuration fields

Field	Required	Description
`supabase_url`	Yes	Your Babelon backend URL
`client_id`	Yes	API client ID (`bbl_cid_` prefix). See API Tokens.
`api_token`	Yes	API token (`bbl_tok_` prefix). See API Tokens.
`tenant_id`	Yes	Your organization's tenant UUID
`source_locale`	No	Source language code (default: `en`)
`target_locales`	No	List of target language codes
`files.path`	No	Path template with `{locale}` placeholder (e.g., `locales/{locale}.json`)
`files.pattern`	No	Glob pattern to find translation files (alternative to `path`)
`files.output_dir`	No	Output directory for downloads (alternative to `path`)
`files.format`	No	Default export format: `json`, `yaml`, `nested-json`, `i18next`, `vue-i18n`, `rails`

TIP

You can also set supabase_url, client_id, and api_token via environment variables: SUPABASE_URL, BABELON_CLIENT_ID, BABELON_API_TOKEN.

Global flags

Flag	Short	Description
`--verbose`	`-v`	Enable verbose output
`--config`	`-c`	Path to config file (default: `.babelon.toml`)

Commands

`babelon init`

Initialize a new project by creating a .babelon.toml configuration file.

bash

babelon init \
  --supabase-url https://your-project.supabase.co \
  --client-id bbl_cid_a1b2c3d4e5f6g7h8 \
  --api-token bbl_tok_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 \
  --tenant-id your-tenant-uuid \
  --source-locale en \
  --target-locales es,fr,de

Flag	Description
`--supabase-url`	Backend URL
`--client-id`	API client ID
`--api-token`	API token
`--tenant-id`	Tenant UUID
`--source-locale`	Source language (default: `en`)
`--target-locales`	Comma-separated list of target languages
`--force`	Overwrite an existing `.babelon.toml`

`babelon upload`

Upload translation source files to Babelon. Supports JSON, nested JSON, and YAML.

bash

# Upload a specific file
babelon upload locales/en.json

# Upload with a bundle assignment
babelon upload locales/en.json --bundle checkout

# Dry run (validate without uploading)
babelon upload locales/en.json --dry-run

Flag	Short	Description
`--locale`	`-l`	Source locale (default: from config `source_locale`)
`--bundle`	`-b`	Assign uploaded messages to this bundle
`--dry-run`		Validate only, do not upload
`--force`	`-f`	Update existing messages (by default, duplicates are skipped)
`--skip-validation`		Skip ICU syntax validation

Files can be specified as CLI arguments, discovered from the files.path template, or matched with the files.pattern glob. Nested JSON keys are automatically flattened to dot-notation (e.g., checkout.button.label). Messages with ICU syntax are auto-detected and tagged as format_type: "icu".

`babelon download`

Download translations as files.

bash

# Download all locales as JSON
babelon download --locales all

# Download specific locales as nested JSON
babelon download --locales es,fr --format nested-json

# Download only approved translations
babelon download --locales all --approved-only

# Download a specific bundle
babelon download --locales all --bundle checkout

Flag	Short	Description
`--locales`	`-l`	Comma-separated locale codes, or `all`
`--output`	`-o`	Output directory
`--format`	`-f`	`json`, `yaml`, `nested-json`, `i18next`, `vue-i18n`, `rails`
`--bundle`	`-b`	Restrict to a specific bundle
`--approved-only`		Only include approved translations
`--dry-run`		Show what would be downloaded without writing files

The format is resolved in this order: --format flag, then config files.format, then inferred from the files.path template extension, then defaults to json.

Framework formats

The i18next, vue-i18n, and rails formats convert ICU MessageFormat to each framework's native syntax. This conversion happens locally in the CLI -- the database always stores ICU.

`babelon validate`

Validate translation files locally without uploading them.

bash

# Validate a file
babelon validate locales/en.json

# JSON output for CI integration
babelon validate locales/en.json --format json

Flag	Short	Description
`--icu`		Check ICU syntax (default: `true`)
`--keys`		Check key format (default: `true`)
`--format`	`-f`	Output format: `text` or `json`
`--verbose`		Show all messages, not just errors

The command exits with a non-zero code if validation errors are found, making it suitable for CI pipelines and pre-commit hooks.

`babelon translate`

Trigger AI translation jobs and wait for them to complete.

bash

# Translate to all configured target locales
babelon translate --all

# Translate to specific locales
babelon translate --locale es,fr

# Use a specific AI provider
babelon translate --all --provider claude

# Translate only messages in a bundle
babelon translate --all --bundle checkout

Flag	Description
`--locale`	Target locales (comma-separated)
`--all`	Use all target locales from config
`--provider`	Override AI provider: `claude`, `openai`, or `google_translate`
`--bundle`	Restrict to messages in this bundle

The command creates translation jobs and polls every 2 seconds until all jobs reach a terminal state (done, failed, or cancelled). Results are printed as a summary.

WARNING

Messages that already have an approved translation for a given locale are skipped. To retranslate, reject the existing translation first.

`babelon jobs`

List and monitor translation jobs.

bash

# List recent jobs
babelon jobs

# Filter by status
babelon jobs --status failed

# Watch mode (refreshes every 5 seconds)
babelon jobs --watch

Flag	Description
`--status`	Filter: `pending`, `running`, `done`, `failed`, `cancelled`
`--limit`	Results per page (default: 20)
`--watch`	Live polling mode, refreshes every 5 seconds

`babelon status`

Show project configuration and API statistics.

bash

babelon status

Displays your current configuration (locales, backend URL) and project statistics from the server (message counts, translation coverage, job stats).

Error handling and retries

All API calls (except export) use automatic retry with exponential backoff:

3 attempts maximum
Backoff delays: 500ms, 1s, 2s
Retried errors: Network failures, HTTP 429 (rate limit), 502, 503
Not retried: Client errors (4xx except 429)

File format support

Extension	Parser	Behavior
`.json`	JSON	Nested objects flattened to dot-notation keys
`.yaml` / `.yml`	YAML	Converted to JSON values, then flattened

Both parsers produce flat {key: value} maps. Nested structures like { "checkout": { "title": "..." } } become checkout.title.

CLI Reference ​

Installation ​

Configuration ​

Example .babelon.toml ​

Configuration fields ​

Global flags ​

Commands ​

babelon init ​

babelon upload ​

babelon download ​

babelon validate ​

babelon translate ​

babelon jobs ​

babelon status ​

Error handling and retries ​

File format support ​

CLI Reference

Installation

Configuration

Example `.babelon.toml`

Configuration fields

Global flags

Commands

`babelon init`

`babelon upload`

`babelon download`

`babelon validate`

`babelon translate`

`babelon jobs`

`babelon status`

Error handling and retries

File format support