@sonenta/cli

CLI · npm · MIT

A small, scriptable command line for everything you'd otherwise click through the dashboard: import an existing i18next project, push and pull translations, diff CI against the remote, publish a CDN release, and snapshot bundles for an offline-first build. MIT, on npm.

Install

npm only, there is no Homebrew formula for the CLI. Requires Node 18 or newer, and installs the sonenta command.

# install once, globally
npm i -g @sonenta/cli

# or run without installing
npx @sonenta/cli <command>

Authenticate

Every call sends Authorization: ApiKey <prefix>.<secret> with the mcp:* scope. Log in once to store the key in ~/.sonenta/credentials, or set SONENTA_TOKEN in CI.

# interactive: stores the key per host in ~/.sonenta/credentials (0600)
sonenta login --host https://api.sonenta.com
API key: snt_live_••••••••.••••••••••••••••
✓ saved for https://api.sonenta.com

# CI: no prompt, key read from the environment
export SONENTA_TOKEN=snt_live_<prefix>.<secret>
sonenta push

Note

Resolution order, first wins: the SONENTA_TOKEN environment variable, then ~/.sonenta/credentials for the active host. Mint the key under Org Settings → API Keys with the mcp:* scope.

Configure

sonenta init writes a sonenta.config.json in your repo (resolved by walking up from the working directory). Credentials live separately, per user, and are never committed.

// sonenta.config.json, committed to your repo, no secrets here
{
  "host": "https://api.sonenta.com",
  "project_uuid": "<project_uuid>",
  "version_slug": "main"
}

// ~/.sonenta/credentials, mode 0600, per user, never commit
{ "default": "https://api.sonenta.com",
  "hosts": {
    "https://api.sonenta.com": { "api_key": "snt_live_..." }
  } }

Note

version_slug defaults to main. Keep the API key out of sonenta.config.json, it belongs in the credentials file or SONENTA_TOKEN only.

Commands

Grouped by what you're doing, set up auth and config, inspect a project, or sync translations. Every command runs against the MCP surface and respects sonenta.config.json.

Auth & setup

sonenta login

Store an API key for a host.

Flag	Description
--host <url>	API host to authenticate against.
--token <key>	Pass the key non-interactively instead of the prompt.

sonenta login --host https://api.sonenta.com

sonenta logout

Remove stored credentials for a host. No flags.

sonenta logout

sonenta whoami

Show the active host and a masked key. No flags.

sonenta whoami

sonenta init

Scaffold sonenta.config.json for a project.

Flag	Description
--project <uuid>	Project UUID to write into the config (required).
--version <slug>	Version slug to target (defaults to main).
--force	Overwrite an existing config file.

sonenta init --project <uuid> --version main

Inspect

sonenta projects list

List the projects your key can reach. No flags.

sonenta projects list

sonenta keys list

List keys as namespace_slug/key_name.

Flag	Description
--namespace <slug>	Restrict to one namespace.

sonenta keys list --namespace common

sonenta status

Diff your local locales/ against the remote.

Flag	Description
--language <code>	Limit the diff to one language.
--namespace <slug>	Limit the diff to one namespace.
--src <dir>	Source directory (defaults to locales).

sonenta status

sonenta missing

List runtime-detected missing keys.

Flag	Description
--language <code>	Filter by language.
--namespace <slug>	Filter by namespace.
--limit <n>	Cap the number of rows.

sonenta missing --limit 50

Import & sync

sonenta import <files...>

One-shot i18next import, nested or flat; creates keys, upserts translations, idempotent.

Flag	Description
--dry-run	Preview only; sends nothing.
--status <draft|translated>	Incoming status (default translated).
--language <code>	Force the language instead of inferring it from the path.
--namespace <slug>	Force the namespace (required for a bare <lang>.json).
--version <slug>	Target a non-default version.

sonenta import locales/fr/common.json

sonenta push

Push the whole local locales/ tree in one import call.

Flag	Description
--src <dir>	Source directory (defaults to locales).
--dry-run	Preview only; sends nothing.
--status <state>	Incoming status (default translated).

sonenta push --dry-run

sonenta pull

Write remote translations to locales/<lang>/<namespace>.json (flat).

Flag	Description
--language <code>	Limit to one language.
--namespace <slug>	Limit to one namespace.
--dest <dir>	Destination directory (defaults to locales).

sonenta pull --language fr

sonenta export

Export as i18next JSON, flat by default, --nested for trees.

Flag	Description
--nested	Emit nested trees instead of flat keys.
--out <dir>	Write files to a directory instead of stdout.

sonenta export --nested --out ./dump

sonenta releases publish

Trigger a CDN release: the published bundle becomes the production version.

Flag	Description
--version <slug>	Version to publish (defaults to main).
--dry-run	Preview only; publishes nothing.

sonenta releases publish

sonenta snapshot

Fetch the public CDN bundles into a build-time module for offline-first SDK fallback.

Flag	Description
--format <ts|json>	Output format: ts (default) or json.
--out <file>	Write to a file instead of stdout.
--cdn <base>	CDN base (defaults to https://cdn.sonenta.com).

sonenta snapshot --out src/sonenta-bundles.ts

Note

Every command also accepts --host <url> to override the configured API host for a single run.

Next

• Guide · Migrate from i18next: The copyable end-to-end onboarding path.
• Guide · Flat vs nested keys: Keep dotted keys from breaking.
• Guide · Update source values: Change a key's source text after it exists.

Full reference

Every command, with all its flags and examples: see the full CLI reference.