Introducing the Better i18n CLI: Manage Translations from Your Terminal

Until now, managing translation keys on Better i18n meant using the dashboard UI or connecting an MCP server to your AI assistant. Both work great — but what about CI/CD pipelines? Headless environments? AI agents without MCP support? Scripts that need to create 200 keys in one shot?

Today we're shipping the Better i18n CLI — a full-featured command-line tool that gives you complete control over your localization workflow from the terminal. Authenticate once, then create keys, set translations, publish to CDN, and monitor syncs without ever opening a browser.

Why a CLI?

Three forces drove this:

1. AI agents need a fallback. Our MCP server works beautifully with Claude, Cursor, and Windsurf — but not every agent runtime supports MCP. The CLI gives any agent a universal interface: pipe JSON in, get JSON out. No protocol negotiation, no server setup.

2. CI/CD pipelines need automation. Pre-commit hooks that scan for untranslated strings. Post-deploy scripts that publish translations. GitHub Actions that create keys from extracted strings. The CLI makes all of these one-liners.

3. Power users want speed. Sometimes you just want to check what's pending, publish, and move on. No tab switching, no page loads. Terminal stays open, work gets done.

What You Can Do

The CLI covers every operation that was previously dashboard-only or MCP-only:

Authentication

# Browser login (like Cloudflare Wrangler)
better-i18n login

# API key login (for CI/agents)
better-i18n login --api-key bi-your-key

# Check who you are
better-i18n whoami

login opens your default browser, authenticates via your Better i18n account (Google, GitHub, or email), and stores an API key locally in ~/.better-i18n/auth.json. One-time setup.

Manage Keys

# List keys with search and filtering
better-i18n keys list -p acme/dashboard --search "auth" --namespace common

# Create keys (inline)
better-i18n keys create -p acme/dashboard \
  --key "auth.title" --value "Login" \
  --key "auth.subtitle" --value "Welcome back"

# Create keys (bulk via stdin — perfect for agents)
echo '[
  {"n": "auth.title", "v": "Login", "ns": "auth"},
  {"n": "auth.subtitle", "v": "Welcome back", "ns": "auth"},
  {"n": "common.save", "v": "Save"}
]' | better-i18n keys create -p acme/dashboard --json --yes

Set Translations

# Pipe translations from any source (your AI, a script, a TMS export)
echo '[
  {"id": "<uuid>", "t": {"tr": "Giriş yap", "de": "Anmelden", "fr": "Connexion"}},
  {"id": "<uuid>", "t": {"tr": "Hoş geldin", "de": "Willkommen"}}
]' | better-i18n translate -p acme/dashboard --json --yes

Publish to CDN

# Check what's pending
better-i18n publish:status -p acme/dashboard

# Publish
better-i18n publish -p acme/dashboard

Manage Languages

# Add French and German
better-i18n languages add -p acme/dashboard --lang fr --lang de

# Archive a language
better-i18n languages edit -p acme/dashboard --lang ko --new-status archived

Monitor Syncs

# View sync history
better-i18n syncs list -p acme/dashboard

# Wait for a publish to complete
better-i18n syncs get <syncId> --wait

Plus the existing analysis commands that have been part of the CLI since day one: scan, check, sync, doctor, and pull.

Designed for AI Agents

Every command supports two output modes:

• Human mode (default): colored output, spinners, confirmation prompts
• Agent mode (--json --yes): deterministic JSON output, no prompts, stdin for input

This means any AI agent can use the CLI as a drop-in replacement for MCP tools:

# Agent workflow: find missing translations → translate → publish
KEYS=$(better-i18n keys list -p acme/app --missing tr --json)
# ... agent generates translations ...
echo "$TRANSLATIONS" | better-i18n translate -p acme/app --json --yes
better-i18n publish -p acme/app --json --yes

The JSON contract is consistent across all commands:

{"ok": true, "data": { ... }}
{"ok": false, "error": "message", "code": "AUTH_FAILED"}

Unix Philosophy: Pipes Work

Commands are composable. The output of one feeds the input of another:

# Find keys missing Turkish → feed to translate
better-i18n keys list -p acme/app --missing tr --json \
  | your-translation-script \
  | better-i18n translate -p acme/app --json --yes

# Scan code → create missing keys in one pipeline
better-i18n scan --format json \
  | better-i18n keys create -p acme/app --from-scan --json --yes

Authentication Built on better-auth

The CLI's auth layer uses the same better-auth infrastructure as our dashboard. When you run better-i18n login:

1. CLI opens your browser to dash.better-i18n.com/cli-auth
2. You log in with your existing account (Google, GitHub, email)
3. An API key is automatically created and sent back to the CLI
4. Key is stored in ~/.better-i18n/auth.json

No separate credentials. No token rotation headaches. The same API keys work for MCP, CLI, and the REST API.

For CI/CD, set BETTER_I18N_API_KEY as an environment variable — the CLI picks it up automatically.

The Full Command Reference

22 commands total. Every MCP tool has a CLI equivalent.

Getting Started

# Install
npm install -g @better-i18n/cli

# Login
better-i18n login

# You're ready
better-i18n projects

Or use without installing:

npx @better-i18n/cli login
npx @better-i18n/cli keys list -p acme/dashboard

What's Next

• push command — Scan your codebase for t() calls, diff against remote keys, and create missing ones in a single pipeline. The holy grail of i18n automation.
• Autocompletion — Shell completions for bash, zsh, and fish.
• watch mode — Detect new keys as you code and push them automatically.

The CLI is open source as part of @better-i18n/cli on npm. Try it today and let us know what you build with it.

Read the full CLI documentation →