@sonenta/cli

@sonenta/cli

Command-line interface for Sonenta translation management. Sits next to the API and the React SDK; calls into the public HTTP surface using a Sonenta API key.

Install

npm install -g @sonenta/cli
# or
npx @sonenta/cli --help

Quick start

# 1. Authenticate (the key must carry the `mcp:*` scope — see Auth below)
sonenta login --host https://api.sonenta.com --token vrb_live_<prefix>.<secret>

# 2. Bind the current directory to a project
sonenta init --project 069fc15d-…  --version main

# 3. Import an i18next file in one shot
sonenta import locales/fr/common.json

Configuration

Two files are involved:

• sonenta.config.json — per-project, committed to the repo. Contains the host + project_uuid + version_slug. Any command resolves it by walking up from the current directory.

• ~/.sonenta/credentials — per-user, never committed. JSON file with mode 0600 keyed by host so the same user can hold credentials for multiple Sonenta deployments simultaneously (e.g. cloud + local dev + self-hosted prod). The currently active host is recorded as default.

The credentials file shape:

{
  "default": "https://api.sonenta.com",
  "hosts": {
    "https://api.sonenta.com":     { "api_key": "vrb_live_…", "user_email": "…" },
    "https://api.dev.sonenta.ca": { "api_key": "vrb_live_…" }
  }
}

Commands

All project commands talk to the metered MCP surface (/v1/mcp/projects/{id}/…) and require an API key carrying the mcp:* scope (see Auth).

Command	Purpose
login / logout	Store / remove an API key for a host
whoami	Show the active host + masked key
init	Scaffold sonenta.config.json in the current dir
projects list	List projects the key can reach
keys list	List keys (namespace_slug/key_name)
import <files…>	One-shot import of i18next JSON (nested or flat) — creates keys + upserts translations
push	Push the whole local locales/ tree in one import call
pull	Pull translations into locales/<lang>/<namespace>.json
export	Export translations as i18next JSON (flat, or --nested)
status	Diff local locales/ against the remote project
releases publish	Trigger a CDN release (publish bundles)
snapshot	Emit a build-time initialBundles module for @sonenta/react-i18next
missing	List runtime-detected missing keys
agents list	List the bundled Claude agents available to install
agents add <name>	Write a bundled agent into .claude/agents/<name>.md

Mutating commands accept --dry-run and print a created / updated / unchanged summary.

Installable agents

agents add drops a ready-made Claude agent into the project's .claude/agents/ directory — usable interactively in Claude Code or headless in CI. The flagship agent is sonenta-a11y, an accessibility auditor that drives the Sonenta a11y MCP tools (a11y_report, list_a11y_gaps, a11y_estimate, generate_a11y_variant, translate_a11y_variants, set_a11y_variant) to find WCAG gaps — missing aria-labels, images without alt text, hard-to-read copy, missing or untranslated a11y variants — and propose or apply fixes.

# see what's available (and what's already installed)
sonenta agents list

# install the accessibility agent into .claude/agents/
sonenta agents add sonenta-a11y

The agent reaches the a11y tools through the @sonenta/mcp server, so configure that server with an mcp:* key first. --dir <path> targets another project directory; --force overwrites an existing definition.

Sync workflow

# import an i18next file (language + namespace inferred from the path)
sonenta import locales/fr/common.json
# …or a bare file with an explicit namespace
sonenta import --namespace common fr.json

# preview, then push the whole locales/ tree in ONE call
sonenta push --dry-run
sonenta push

# pull remote translations back to disk; diff before committing
sonenta pull --language fr
sonenta status

# publish to the CDN; generate a build-time SDK fallback bundle
sonenta releases publish
sonenta snapshot --out src/sonenta-bundles.ts

Auth

Every call emits Authorization: ApiKey <prefix>.<secret> (capital A, lowercase k) against the MCP surface, so the API key must carry the mcp:* scope. Generate one in the dashboard at Org Settings → API Keys. The key is supplied by you — via sonenta login, the SONENTA_TOKEN env var (handy for CI), or ~/.sonenta/credentials — and is never hard-coded.

0.2.0 migration (breaking): the whole CLI moved from the project REST surface (/v1/projects/…, project-scoped keys) to the MCP surface (/v1/mcp/projects/…). Re-issue your CLI key with the mcp:* scope — project-scoped keys now return 403.

License

MIT