Skip to content
Sonenta
Language
StartStart freeStart free

CLI

v0.48.4 · npm · MIT

@sonenta/cli

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.

terminal 
1# install once, globally2npm i -g @sonenta/cli 4# or run without installing5npx @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.

terminal 
1# interactive, stores the key per host in ~/.sonenta/credentials (0600)2sonenta login --host https://api.sonenta.dev --token snt_live_<prefix>.<secret>3Logged in as user@example.com (Acme Inc) on https://api.sonenta.dev. 5# CI, no prompt, key read from the environment6export SONENTA_TOKEN=snt_live_<prefix>.<secret>7sonenta push

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 
1# committed to your repo, no secrets here2{3  "host": "https://api.sonenta.dev",4  "project_uuid": "<project_uuid>",5  "version_slug": "main"6}
~/.sonenta/credentials 
1# ~/.sonenta/credentials, mode 0600, per user, never commit2{ "default": "https://api.sonenta.dev",3  "hosts": {4    "https://api.sonenta.dev": { "api_key": "snt_live_<prefix>.<secret>" }5  } }

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.

Flags

  • --host <url> API host to authenticate against.
  • --token <key> Pass the key non-interactively instead of the prompt.
  • --email <email> cmd_login_flag_email
  • --default cmd_login_flag_default

Example

sonenta login --host https://api.sonenta.dev --token snt_live_<prefix>.<secret>
sonenta logout Remove stored credentials for a host.

Flags

No flags.

Example

sonenta logout
sonenta whoami Show the active host and a masked key.

Flags

No flags.

Example

sonenta whoami
sonenta init Scaffold sonenta.config.json for a project.

Flags

  • --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.

Example

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

Inspect

sonenta projects list List the projects your key can reach.

Flags

No flags.

Example

sonenta projects list
sonenta keys list List keys as namespace_slug/key_name.

Flags

  • --namespace <slug> Restrict to one namespace.

Example

sonenta keys list --namespace common
sonenta status Diff your local locales/ against the remote.

Flags

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

Example

sonenta status
sonenta missing List runtime-detected missing keys.

Flags

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

Example

sonenta missing --limit 50

Import & sync

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

Flags

  • --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.

Example

sonenta import locales/fr/common.json
sonenta push Push the whole local locales/ tree in one import call.

Flags

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

Example

sonenta push --dry-run
sonenta pull Write remote translations to locales/<lang>/<namespace>.json (flat).

Flags

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

Example

sonenta pull --language fr
sonenta export Export as i18next JSON, flat by default, --nested for trees.

Flags

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

Example

sonenta export --nested --out ./dump
sonenta releases publish Trigger a CDN release; the published bundles are served to your apps from the CDN.

Flags

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

Example

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

Flags

  • --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).

Example

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

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.