CLI

v0.2.1 · 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.

Breaking · 0.1 → 0.2

The whole CLI now runs on the MCP surface, so it needs an API key with the mcp:* scope — project-scoped keys return 403. Generate one in the dashboard under Org Settings → API Keys and re-issue any key you used with 0.1.

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.com3API key: snt_live_••••••••.••••••••••••••••4✓ saved for https://api.sonenta.com 6# CI — no prompt, key read from the environment7export SONENTA_TOKEN=snt_live_<prefix>.<secret>8sonenta 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.com",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.com",3  "hosts": {4    "https://api.sonenta.com": { "api_key": "snt_live_..." }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.

Example

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

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; subscribed SDKs refresh live.

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.

0.1 → 0.2 breaking changes

Upgrading from 0.1? Two changes need action.

MCP surface + scope. The whole CLI moved from the project REST surface to the MCP surface. Re-issue your API key with the mcp:* scope — project-scoped keys now return 403.
push is one-shot. push now sends your entire locales/ tree in a single import call (it was create-key plus a PUT per translation). It is idempotent and prints created / updated / unchanged.
New commands. import, export, releases publish, snapshot and projects list are new in 0.2.0.