@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.dev --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 init also writes an idempotent, marker-delimited Sonenta managed block into CLAUDE.md and AGENTS.md at the repo root, so any coding agent that reads those files knows the project id, source language, namespaces, CDN host, how to edit/publish translations, and how to add the @sonenta/mcp MCP server. Re-running sonenta init --force refreshes the block in place (your own content outside the markers is never touched); when you are logged in it is populated live from GET /v1/me + project info. Pass --no-repo-doc to skip it.

• ~/.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.dev",
  "hosts": {
    "https://api.sonenta.dev":     { "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 + write a managed Sonenta block into CLAUDE.md / AGENTS.md
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, BATCHED (each key keeps all its languages together — source never split from targets); --batch-size
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 + auto-wire .mcp.json + run a preflight
doctor	Preflight the agent setup — MCP wired + reachable, key has mcp:*, project a11y tools respond — with an exact fix for anything off

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

sonenta doctor

sonenta doctor (also run automatically at the end of sonenta agents add) checks, in order: project config, login, the .mcp.json wiring, the host is reachable (no silent 404), the account is active, the key carries the mcp:* scope, and the project's a11y MCP tools respond. Every failure prints the exact next step (e.g. "key lacks mcp:* → create one in Org Settings → API Keys, then sonenta login"), and it exits non-zero so it gates CI. The one thing it can't observe — whether your Claude session has loaded the MCP connection — it reminds you to fix by reloading the session.

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. Each agent preflights its prerequisites at startup — it verifies the @sonenta/mcp server is connected with an mcp:* key before doing any work, and if not, fails fast with the exact fix (sonenta agents add to wire it, reload the session, sonenta doctor to diagnose) instead of probing 404s. The bundled agents are local-first and CRUD-based: they do the work themselves and write it back via plain CRUD tools (0 Sonenta AI credits; changes land as drafts or soft/restorable for review); any server-side AI is 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).
• sonenta-source-health — duplicate-source repairer. Finds keys that share the same source string and fixes them, strictly step by step and only on your acceptance. When the Sonenta dashboard has prepared a merge plan (surfaced via list_source_duplicates → merge_plan), it applies it verbatim: repoints t('redundant') → t('canonical') in your code and trashes the redundant keys (delete_keys_bulk, value-safe & restorable — never edits a source value), then per survivor_outcome marks the residue allowed (set_duplicate_status) or differentiates the survivors (update_key). With no plan it falls back to its own consolidate / disambiguate / allow judgment.
• sonenta-knowledge — knowledge manager. Builds and maintains the project's glossary (glossary_list / glossary_create / glossary_update; translation rules, do-not-translate, forbidden) and context document (project_context_get / project_context_set; domain, audience, tone, product name) from the real source strings (list_keys) + repo docs. Three modes: INIT (bootstrap from scratch), AUDIT (report current state + gaps, read-only), MAINTAIN (detect new terms, inconsistent usage, and context drift, then propose updates). Non-destructive — proposes and confirms before overwriting (the context set replaces the whole doc, so it always merges first).
• sonenta-surface — surface configuration advisor. Audits which translation surfaces a project has (list_surfaces: device desktop/mobile/tablet + custom; a11y aria_label/alt_text/screen_reader/ plain_language), recommends which to enable from the project's key types (list_keys) and accessibility gaps (a11y_report), and applies the config via create_surface / update_surface (enable/disable/rename) / delete_surface. Non-destructive (confirm before create/update, never delete without confirmation; deactivation is soft). It configures surfaces only — for filling the a11y values (alt/aria/plain-language) it hands off to sonenta-a11y, keeping the two complementary.

# 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
sonenta agents add sonenta-source-health
sonenta agents add sonenta-knowledge
sonenta agents add sonenta-surface

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