@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. Both bundled agents are local-first: the agent generates the content itself and writes it back via CRUD tools (0 Sonenta AI credits, drafts to review); the server-side AI tools are an explicit, estimated, opt-in fallback.

• sonenta-a11y — accessibility auditor. Drives the Sonenta a11y MCP tools (a11y_report, list_a11y_gaps, set_a11y_variant, plus the generate_a11y_variant / translate_a11y_variants fallback) to find WCAG gaps — missing aria-labels, images without alt text, hard-to-read copy, missing or untranslated a11y variants — and fix them. Also scores plain-language difficulty locally (list_cognitive_candidates → set_cognitive_score, 0 credits) and suggests clearer rewrites.
• sonenta-i18n — i18n automation. Audits coverage (coverage_report, list_missing_keys), creates missing keys (create_keys_bulk), translates the untranslated itself honoring the glossary + project context (list_untranslated_keys → propose_translations_bulk), and publishes (publish_cdn).

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

# install an agent into .claude/agents/
sonenta agents add sonenta-a11y
sonenta agents add sonenta-i18n

The agents reach these 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.

sonenta login validates before storing. It checks the key against GET /v1/me and only stores it when the key is valid and the account is active — an invalid key or an inactive account is rejected with a clear message and nothing is written.

Value commands require an active login. agents add, import, push, pull, export, status, releases publish, snapshot, missing, keys list, and projects list verify you're logged in with an active account (via /v1/me) before they act — otherwise you get Not logged in. Run \sonenta login`orAccount inactive …. The local commands login, logout, whoami, init, and agents list` are not gated.

Credentials live in ~/.sonenta/credentials (mode 0600); the legacy ~/.verbumia/credentials is still read as a fallback, and the next write migrates you to ~/.sonenta.

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