CLI Reference

Command-line reference for the Localhero.ai CLI. Commands, flags, and usage.

Usage

Run the CLI using npx. No installation required.

npx @localheroai/cli <command>

View on npm · View on GitHub

Commands

init

Set up your project configuration. Creates localhero.json and optionally sets up GitHub Actions.

npx @localheroai/cli init

See Project Setup for a detailed walkthrough.

login

Authenticate with your API key. Saves to .localhero_key and adds it to .gitignore.

npx @localheroai/cli login

Usually not needed since init handles authentication.

translate

Generate translations for keys missing translations. Updates your local translation files with the results.

npx @localheroai/cli translate

--verbose Show detailed output

--commit Automatically commit changes

--changed-only Only translate keys changed in current branch

push

Upload translation files to Localhero.ai. Syncs your local keys and translations to the dashboard.

npx @localheroai/cli push

--verbose Show detailed output

--yes Skip confirmation prompt

--force Push all keys, not just changes

pull

Download translations from Localhero.ai to your local files. Use after editing translations in the dashboard.

npx @localheroai/cli pull

--verbose Show detailed output

--changed-only Only pull keys changed in current branch

clone

Download all translation files from Localhero.ai. Useful for build pipelines where translation files aren't in version control.

npx @localheroai/cli clone

--verbose Show detailed output

--force Overwrite existing files

ci

Optimized command for CI/CD environments. Automatically detects context and runs appropriate operations.

npx @localheroai/cli ci

See GitHub Actions for setup details.

--verbose Show detailed output

Configuration File

The localhero.json file contains your project configuration. Created automatically by the init command.

{
  "schemaVersion": "1.0",
  "projectId": "prj_abc123",
  "sourceLocale": "en",
  "outputLocales": ["fr", "de", "es"],
  "translationFiles": {
    "paths": ["config/locales/"],
    "pattern": "**/*.{json,yml,yaml}",
    "ignore": ["**/test/**"]
  },
  "lastSyncedAt": null
}

projectId Your unique project identifier from Localhero.ai

sourceLocale The language you write your app in (must match filename exactly)

outputLocales Array of target languages (must match filenames exactly)

translationFiles.paths Directories containing translation files

translationFiles.pattern Glob pattern for file matching

translationFiles.ignore Patterns to exclude from translation

The --changed-only flag compares against the main branch by default.

Locale codes must match your filenames exactly

config/locales/en.yml → "sourceLocale": "en"

locales/en-US/common.json → "sourceLocale": "en-US"

locale/pt_BR.po → "outputLocales": ["pt_BR"]

Environment Variables

For CI/CD environments where the .localhero_key file isn't available.

LOCALHERO_API_KEY

Your API authentication key. Takes precedence over .localhero_key file.

export LOCALHERO_API_KEY="your-key-here"

LOCALHERO_API_HOST

Custom API endpoint URL. Only needed for self-hosted installations.

Need help? Drop us a line at hi@localhero.ai