Introduction

Better i18n CLI is a full-featured command-line tool for managing your localization workflow. Authenticate once, then manage translation keys, set translations, publish to CDN, and audit your i18n health — all from the terminal.

When MCP tools aren't available (CI/CD pipelines, headless environments, AI agents without MCP), the CLI provides the same capabilities with --json output for machine consumption.

Quick Start

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

# Authenticate (opens browser)
better-i18n login

# List your projects
better-i18n projects

# List keys in a project
better-i18n keys list -p acme/dashboard

# Create keys
better-i18n keys create -p acme/dashboard --key "auth.title" --value "Login"

# Publish to CDN
better-i18n publish -p acme/dashboard

Authentication

The CLI uses the same API keys as the MCP server. Three ways to authenticate:

# Option 1: Browser login (recommended for developers)
better-i18n login

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

# Option 3: Environment variable (for CI/CD)
export BETTER_I18N_API_KEY=bi-your-key

Auth resolution priority: --api-key flag → BETTER_I18N_API_KEY env → ~/.better-i18n/auth.json (from login).

View full authentication docs →

Commands

Auth

Command	Description
`login`	Authenticate via browser or API key
`logout`	Remove stored credentials
`whoami`	Show current authenticated user

Translation Management

Command	Description
`projects`	List all projects
`project`	Show project details (languages, namespaces, coverage)
`keys list`	Browse and search translation keys
`keys create`	Create keys (flags or stdin JSON)
`keys delete`	Delete keys by UUID
`translations`	Get translations with full text content
`translate`	Set translations for existing keys

Publishing

Command	Description
`publish`	Publish pending changes to CDN
`publish:status`	Show pending changes before publishing
`syncs list`	View sync/publish job history
`syncs get`	Get sync job details
`syncs cancel`	Cancel a pending sync job

Languages

Command	Description
`languages add`	Add target languages to project
`languages edit`	Change language status (active/draft/archived)

Code Analysis

Command	Description
`doctor`	Full i18n health report (score 0–100)
`scan`	Find hardcoded strings not wrapped in `t()`
`check`	Interactive missing/unused key checker
`sync`	Compare local keys with remote CDN
`pull`	Download translations for offline fallback
`content:types`	Generate TypeScript types from content models

Agent / CI Usage

Every command supports --json for machine-readable output and --yes to skip confirmations. Pipe JSON via stdin for bulk operations:

# Agent creates keys
echo '[{"n":"auth.title","v":"Login"},{"n":"auth.subtitle","v":"Welcome"}]' \
  | better-i18n keys create -p acme/dashboard --json --yes

# Agent sets translations
echo '[{"id":"<uuid>","t":{"tr":"Giriş","de":"Anmelden"}}]' \
  | better-i18n translate -p acme/dashboard --json --yes

# Agent publishes
better-i18n publish -p acme/dashboard --json --yes

JSON output follows a consistent contract:

// Success
{"ok": true, "data": { ... }}

// Error
{"ok": false, "error": "message", "code": "AUTH_FAILED"}

Configuration

The CLI reads project settings from i18n.config.ts (auto-detected). You can override with -p org/project on any command.

// i18n.config.ts
export default {
  project: "acme/dashboard",
  defaultLocale: "en",
};

Credentials are stored in ~/.better-i18n/auth.json after running better-i18n login.

Installation

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

# npx (no install)
npx @better-i18n/cli doctor

# pnpm
pnpm add -g @better-i18n/cli

# bun
bun add -g @better-i18n/cli

Requires Node.js 18+.

On this page