CLI Reference

Every Localingos CLI command and flag, with example output for init, extract, sync, push and pull.

localingos init

Before running this command: Create a project and an API key on the Get started page — it does both in one place. You will need them during initialization.

Creates two files in your project root: localingos.config.json (project settings, commit it) and .localingos.json (your API key, gitignore it). Prompts for API key, project ID, source locale, format, source file path, and output directory. This command is interactive and has no flags — in a container or provisioning script, write both files yourself.

$ localingos init
? API Key: ********
? Project ID: a3b7c9d1-4e5f-6a7b-8c9d-0e1f2a3b4c5d
? Source locale: en-US
? Format (json-nested / json-flat / yaml / yaml-rails / properties / csv / po / arb): json-nested
? Source file path: src/i18n/en-US.json
? Output directory: src/i18n
? Output filename pattern: {locale}.json
✓ Created localingos.config.json
✓ Created .localingos.json

localingos extract

Generates an AI prompt for i18n integration. The prompt instructs an AI agent to scan your codebase, extract all user-facing strings, create co-located message definition files, and replace hardcoded text with translation function calls.

$ localingos extract
✓ Prompt written to .localingos-extract-prompt.md
Feed this prompt to your AI coding agent.

localingos sync

Pushes source strings to the Localingos API and pulls back whatever translations are ready for the target locales configured on your project.

Translation is asynchronous. The first sync after adding new keys pushes them and returns nothing to write — they are queued. Run sync (or pull) again shortly to collect the results.

# first run — keys are queued for translation
$ localingos sync
   Push: 1077 created, 0 updated, 0 deleted, 0 unchanged
   ✅ 0 translations received
   ⏳ 1077 keys pending translation
   No new translations. Run "localingos sync" again later.

# shortly after — results are ready
$ localingos sync
   Push: 0 created, 0 updated, 0 deleted, 1077 unchanged
   ✅ 3231 translations received
   ✅ Written: src/i18n/de-DE.json
   ✅ Written: src/i18n/fr-FR.json
   ✅ Written: src/i18n/ja-JP.json

Verify before you commit. pull writes whatever is ready and exits 0, so a file pulled mid-translation can be missing keys with no warning — at runtime that shows up as a silent fallback to your source language. Check key counts per locale, and gate on it in CI.

localingos push

Push source strings only, without pulling translations.

localingos push

localingos pull

Pull translations only, without pushing source strings.

localingos pull

Flags

Flag	Description
`--dry-run`	Preview what would change without writing any files or making API calls. Available on sync and push.
`--prune`	Only meaningful if your repo has a scripts/extract-messages.js that regenerates the source file from co-located message definitions; sync forwards the flag to it. Without that script the flag does nothing. Available on sync.
`-c, --config`	Path to a single config file to use instead of the localingos.config.json + .localingos.json pair. When you pass this, only that file is read — supply the API key inside it or via the environment variable.
`--env`	API environment: prod (default), gamma, or local.