@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 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.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 + 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 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 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).

# 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

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