CLI Reference

Usage

koto [command] [options]

If no command is provided, koto translate runs by default.

---

Commands

koto init

Interactive setup wizard. Auto-detects your framework, locale file format, and source directory, then generates a koto.config.ts.

npx koto init

Flag	Description
--yes, -y	Accept all defaults without prompting

---

koto translate

Translate all pending strings. Default command when none is specified.

npx koto translate
npx koto translate --locale es,fr
npx koto translate --context legal
npx koto translate --dry-run
npx koto translate --force

Flag	Description
--locale, -l	Translate only specific locales (comma-separated)
--context, -c	Translate only files matching a specific context profile
--dry-run	Preview what would be translated without writing files
--force	Re-translate all keys, ignoring cache and lockfile
--fail-on-error	Exit with code 1 on translation errors or quality failures
--json	Output results in machine-readable JSON

---

koto diff

Show what needs translation. Lists new, changed, and deleted keys across all target locales.

npx koto diff
npx koto diff --json

Flag	Description
--json	Output diff in machine-readable JSON
--locale, -l	Check only specific locales

---

koto types

Generate TypeScript type definitions from your source locale files.

npx koto types
npx koto types --watch

Flag	Description
--watch	Watch source files and regenerate types on change

---

koto validate

Check your configuration and test the provider connection.

npx koto validate

npx koto validate

✔ Config file: koto.config.ts (valid) ✔ Source locale: src/locales/en.json (214 keys) ✔ Target locales: es, fr, de, ja ✔ Provider: openai / gpt-4o-mini (connected) ✔ Context profiles: default, marketing, legal

---

koto badge

Generate an i18n coverage badge from your lockfile, plus coverage artifacts for CI and dashboards.

npx koto badge

npx koto badge

i18n Coverage Report Overall: 92% across 6 locales Add to your README:  Coverage artifacts: ✔ koto-coverage.json ✔ koto-coverage.html

---

koto contribute

Fork an OSS repo, run koto translation for one locale, and open a pull request via GitHub CLI.

npx koto contribute owner/repo --locale fr
npx koto contribute owner/repo --locale ja --dry-run

Flag	Description
--locale, -l	Target locale code for the contribution (required)
--dry-run	Show steps without creating a fork/PR

---

koto cache stats

Display cache analytics: cached translations, hit rate, and disk usage.

npx koto cache stats

npx koto cache stats

Cache statistics Location: node_modules/.cache/koto Translations: 1,247 Hit rate: 94.2% Disk usage: 2.3 MB

---

koto cache clear

Clear the translation cache. Subsequent runs will re-translate all keys.

npx koto cache clear

---

Global options

Flag	Description
--version, -v	Show koto version
--help, -h	Show help text

---

Exit codes

Code	Meaning
0	Success
1	Translation failure, quality gate failure, or invalid config
2	Unknown command or missing required arguments

---

Environment variables

Variable	Description	Required by
OPENAI_API_KEY	OpenAI API key	provider.name: 'openai'
ANTHROPIC_API_KEY	Anthropic API key	provider.name: 'anthropic'
GOOGLE_API_KEY	Google Gemini API key	provider.name: 'google'
KOTO_CONFIG	Custom path to config file	All (optional)

koto loads .env files from your project root automatically.

---

Examples

# Initialize a new project
npx koto init

# Translate everything
npx koto translate

# Translate only Spanish and French
npx koto translate -l es,fr

# Translate only legal context
npx koto translate -c legal

# Preview without writing
npx koto translate --dry-run

# Re-translate everything from scratch
npx koto translate --force

# CI mode: fail on errors
npx koto translate --fail-on-error

# Check what needs translating
npx koto diff

# Generate TypeScript types
npx koto types

# Watch mode for types
npx koto types --watch

# Verify setup
npx koto validate

# Generate coverage badge
npx koto badge

# Contribute translations to an OSS repo
npx koto contribute owner/repo --locale fr