CLI

Preview

@verbumia/cli

A small, scriptable CLI for everything you'd otherwise click through the dashboard: bootstrap a project, push and pull translations, gate CI on remote drift, peek at the missing-key queue. MIT-licensed, distributed via npm and Homebrew.

Preview · CLI in development. Commands and config may shift before 1.0 — see known upcoming changes at the bottom of this page. The 9 commands and their args are confirmed for V1; the wire format may evolve.

Install

Requires Node 20 LTS or newer. Two binaries get installed: verbumia and the shorter alias vrb — interchangeable.

terminal Tap publishes at V1

1# install once globally — bin "verbumia" plus shorter alias "vrb"2npm i -g @verbumia/cli 4# or use without installing5npx @verbumia/cli@latest <command> 7# Homebrew tap publishes at the V1 launch8brew install verbumia/tap/verbumia-cli

Authenticate

Get an API key from Org Settings → API Keys → Create in your dashboard (the secret is shown once; copy the full vrb_live_<prefix>.<secret>). Use scope project:read for status / pull / missing / projects, project:write for push.

interactive

1verbumia login2? Paste your API key from Org Settings → API Keys (input is masked):3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ Validated via GET /v1/auth/me — marc@example.com (org: acme).5✓ Saved to ~/.verbumia/credentials (chmod 600).

CI / non-interactive

1# CI / non-interactive — env var beats the file but loses to --token2export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>3verbumia push

Source precedence is --token flag → VERBUMIA_TOKEN env → ~/.verbumia/credentials. The credentials file is JSON with shape {"default":"<token>","<host>":"<token>"} so you can keep separate keys for prod / staging / a self-hosted instance on the same machine.

Configure your project

Run verbumia init in your repo to scaffold verbumia.config.json at the root, or write it by hand. The CLI also auto-detects verbumia.config.{ts,js,toml,yml} if you prefer one of those formats.

verbumia.config.json

1// verbumia.config.json — at the project root2// also auto-detected: verbumia.config.{ts,js,toml,yml}3{4  "project_uuid": "<project_uuid>",5  "source_language": "en",6  "locales": ["en", "fr-CA", "es", "ja"],7  "namespaces": ["common", "checkout"],8  "format": "json-i18next",9  "push": {10    "source_dir": "./src/locales",11    "file_pattern": "{locale}/{namespace}.json",12    "on_missing_namespace": "create"13  },14  "pull": {15    "dest_dir": "./src/locales",16    "file_pattern": "{locale}/{namespace}.json",17    "format": "json-i18next"18  },19  "missing_handler": {20    "endpoint": "https://api.verbumia.ca/v1/missing",21    "enabled_for_envs": ["dev", "staging"]22  }23}

Field reference

Field	Type	Default / note
project_uuid	string	— required
source_language	string	"en"
locales	string[] \| null	null = all
namespaces	string[] \| null	null = all
format	string	"json-i18next" \| "xliff" \| "json-flat"
push.source_dir	string	"./src/locales"
push.file_pattern	string	"{locale}/{namespace}.json"
push.on_missing_namespace	"create" \| "error"	"create"
pull.*	object	mirrors push.* (read path)
missing_handler	object	{ endpoint, enabled_for_envs }

Commands

Every command takes --config <path> to point at a non-default config file, --token <vrb_live_…> to override the resolved auth, and --json to emit machine-readable output.

verbumia init Scaffold verbumia.config.json in the current directory by walking you through project_uuid, source language, and format.

Flags

--project <uuid> pre-fill project_uuid
--source-language <code> BCP-47 (default "en")
--format <fmt> json | xliff

Example

verbumia init --project <uuid>

verbumia login Interactive API-key prompt. The CLI validates the key via GET /v1/auth/me, then writes it to ~/.verbumia/credentials with mode 600.

Flags

--token <vrb_live_…> pass the key inline (skips the prompt; useful for scripts)

Example

verbumia login

verbumia logout Erase ~/.verbumia/credentials. Doesn't revoke the key server-side — for that, use the dashboard.

Flags

No command-specific flags. Use the global flags described above.

Example

verbumia logout

verbumia whoami Print the active key's org, project binding, and granted scopes. Quick way to debug "wrong account" surprises.

Flags

No command-specific flags. Use the global flags described above.

Example

verbumia whoami

verbumia projects List the projects the active key can access.

Flags

--json machine-readable output (default is a TTY table)

Example

verbumia projects --json

verbumia status Read-only diff between local files and the remote project — added / removed / changed per locale and namespace. No writes.

Flags

--locale <code> narrow to one locale
--namespace <slug> narrow to one namespace

Example

verbumia status --locale fr-CA

verbumia push Upload local i18n files to Verbumia: creates new keys, updates changed values, and decides per the on-missing-key policy when a key is referenced but absent.

Flags

--locale <code> push only this locale
--namespace <slug> push only this namespace
--dry-run show the plan without applying
--on-missing-key <create|skip> what to do when the local file references a key absent server-side

Example

verbumia push --dry-run

verbumia pull Download remote translations into the configured pull.dest_dir — atomic per file. Also doubles as your "export" path: pass --format to convert on the way out.

Flags

--locale <code> pull only this locale
--namespace <slug> pull only this namespace
--format <fmt> json | xliff (overrides config.format for this run)

Example

verbumia pull --format xliff

verbumia missing List pending missing-key events captured by the runtime SDK. Read-only — handy for triaging from the terminal without opening the dashboard.

Flags

--locale <code> filter by locale
--since <iso> only events newer than this ISO-8601 timestamp
--limit <n> max rows (default 20)

Example

verbumia missing --locale ja --limit 50

There's no separate export command — pull --format covers it. import from Lokalise / Crowdin / Phrase ships post-V1 once the matching backend endpoints land; for now, drop a JSON or XLIFF file in your push.source_dir and run verbumia push.

CI integration

Run verbumia status --json on every PR. Non-zero exit on drift gives you a cheap "did someone ship a key without telling i18n?" gate.

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — gate the build on remote drift2name: i18n status3on: { pull_request: { branches: [main] } }4jobs:5  status:6    runs-on: ubuntu-latest7    steps:8      - uses: actions/checkout@v49      - uses: actions/setup-node@v410        with: { node-version: 20 }11      - run: npx -y @verbumia/cli status --json12        env:13          VERBUMIA_TOKEN: ${{ secrets.VERBUMIA_TOKEN }}

Known upcoming breaking changes

Pinned for transparency. Each lands in a minor release with a one-release deprecation window — run on the latest @verbumia/cli and you'll see the warning before the break.

V1.1 — config.format splits into { input, output } so push and pull can use different formats.
V1.1 — push --on-missing-key becomes a policy object (multi-case) instead of a 2-value enum.
V1.1 — format string "json-flat" renames to "flat-json" for naming consistency.