@verbumia/cli

@verbumia/cli

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

Install

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

Quick start

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

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

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

Configuration

Two files are involved:

• verbumia.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.

• ~/.verbumia/credentials — per-user, never committed. JSON file with mode 0600 keyed by host so the same user can hold credentials for multiple Verbumia 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.verbumia.dev",
  "hosts": {
    "https://api.verbumia.dev":     { "api_key": "vrb_live_…", "user_email": "…" },
    "https://api.dev.verbumia.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 verbumia.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 @verbumia/react-i18next
missing	List runtime-detected missing keys

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

Sync workflow

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

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

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

# publish to the CDN; generate a build-time SDK fallback bundle
verbumia releases publish
verbumia snapshot --out src/verbumia-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 verbumia login, the VERBUMIA_TOKEN env var (handy for CI), or ~/.verbumia/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