CLI

v0.2.1 · npm · MIT

@verbumia/cli

Un CLI pequeño y scriptable para todo lo que harías clicando en el dashboard: inicializar un proyecto, push/pull de traducciones, bloquear la CI ante drift remoto, ojear la cola de claves faltantes. Licencia MIT, distribuido vía npm y Homebrew.

Breaking · 0.1 → 0.2

The whole CLI now runs on the MCP surface, so it needs an API key with the mcp:* scope — project-scoped keys return 403. Generate one in the dashboard under Org Settings → API Keys and re-issue any key you used with 0.1.

Instalar

Requiere Node 20 LTS o más reciente. Se instalan dos binarios: verbumia y el alias más corto vrb — intercambiables.

terminal

1# instalar globalmente una vez — bin "verbumia" más alias corto "vrb"2npm i -g @verbumia/cli 4# o usar sin instalar5npx @verbumia/cli <command>

Autenticarse

Obtén una API key desde Org Settings → API Keys → Create en tu dashboard (el secret se muestra una vez; copia el vrb_live_<prefix>.<secret> completo). Usa el scope project:read para status / pull / missing / projects, project:write para push.

terminal

1# interactive — stores the key per host in ~/.verbumia/credentials (0600)2verbumia login --host https://api.verbumia.dev3API key: vrb_live_••••••••.••••••••••••••••4✓ saved for https://api.verbumia.dev 6# CI — no prompt, key read from the environment7export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>8verbumia push

Resolution order, first wins: the VERBUMIA_TOKEN environment variable, then ~/.verbumia/credentials for the active host. Mint the key under Org Settings → API Keys with the mcp:* scope.

Configura tu proyecto

Ejecuta verbumia init en tu repo para crear verbumia.config.json en la raíz, o escríbelo a mano. El CLI también auto-detecta verbumia.config.{ts,js,toml,yml} si prefieres uno de esos formatos.

verbumia.config.json

1# committed to your repo — no secrets here2{3  "host": "https://api.verbumia.dev",4  "project_uuid": "<project_uuid>",5  "version_slug": "main"6}

~/.verbumia/credentials

1# ~/.verbumia/credentials — mode 0600, per user, never commit2{ "default": "https://api.verbumia.dev",3  "hosts": {4    "https://api.verbumia.dev": { "api_key": "vrb_live_..." }5  } }

version_slug defaults to main. Keep the API key out of verbumia.config.json — it belongs in the credentials file or VERBUMIA_TOKEN only.

Comandos

Cada comando acepta --config <path> para apuntar a un archivo de config no-default, --token <vrb_live_…> para sobrescribir la auth resuelta y --json para emitir salida legible por máquina.

Auth & setup

verbumia login Prompt interactivo para la API key. El CLI valida la key vía GET /v1/auth/me y luego la escribe en ~/.verbumia/credentials con modo 600.

Flags

--host <url> API host to authenticate against.
--token <key> pasa la key inline (salta el prompt; útil para scripts)

Ejemplo

verbumia login --host https://api.verbumia.dev

verbumia logout Borra ~/.verbumia/credentials. No revoca la key del lado del servidor — para eso, usa el dashboard.

Flags

Sin flags específicos del comando. Usa los flags globales descritos arriba.

Ejemplo

verbumia logout

verbumia whoami Imprime la org, el binding de proyecto y los scopes concedidos a la key activa. Forma rápida de debuggear sorpresas de "cuenta equivocada".

Flags

Sin flags específicos del comando. Usa los flags globales descritos arriba.

Ejemplo

verbumia whoami

verbumia init Genera verbumia.config.json en el directorio actual guiándote por project_uuid, idioma fuente y formato.

Flags

--project <uuid> pre-rellena project_uuid
--version <slug> Version slug to target (defaults to main).
--force Overwrite an existing config file.

Ejemplo

verbumia init --project <uuid> --version main

Inspect

verbumia projects list Lista los proyectos a los que la key activa tiene acceso.

Flags

Sin flags específicos del comando. Usa los flags globales descritos arriba.

Ejemplo

verbumia projects list

verbumia keys list List keys as namespace_slug/key_name.

Flags

--namespace <slug> Restrict to one namespace.

Ejemplo

verbumia keys list --namespace common

verbumia status Diff de solo lectura entre los archivos locales y el proyecto remoto — añadidos / eliminados / modificados por locale y namespace. Sin escrituras.

Flags

--language <code> Limit the diff to one language.
--namespace <slug> Limit the diff to one namespace.
--src <dir> Source directory (defaults to locales).

Ejemplo

verbumia status

verbumia missing Lista los eventos pendientes de claves faltantes capturados por el SDK en runtime. Solo lectura — útil para triar desde la terminal sin abrir el dashboard.

Flags

--language <code> Filter by language.
--namespace <slug> Filter by namespace.
--limit <n> filas máx (default 20)

Ejemplo

verbumia missing --limit 50

Import & sync

verbumia import <files...> One-shot i18next import — nested or flat; creates keys, upserts translations, idempotent.

Flags

--dry-run Preview only; sends nothing.
--status <draft|translated> Incoming status (default translated).
--language <code> Force the language instead of inferring it from the path.
--namespace <slug> Force the namespace (required for a bare <lang>.json).
--version <slug> Target a non-default version.

Ejemplo

verbumia import locales/fr/common.json

verbumia push Sube los archivos i18n locales a Verbumia: crea claves nuevas, actualiza valores cambiados y decide según la política on-missing-key cuando una clave es referenciada pero está ausente.

Flags

--src <dir> Source directory (defaults to locales).
--dry-run Preview only; sends nothing.
--status <state> Incoming status (default translated).

Ejemplo

verbumia push --dry-run

verbumia pull Descarga las traducciones remotas en el pull.dest_dir configurado — atómico por archivo. También sirve como path de "export": pasa --format para convertir al salir.

Flags

--language <code> Limit to one language.
--namespace <slug> Limit to one namespace.
--dest <dir> Destination directory (defaults to locales).

Ejemplo

verbumia pull --language fr

verbumia export Export as i18next JSON — flat by default, --nested for trees.

Flags

--nested Emit nested trees instead of flat keys.
--out <dir> Write files to a directory instead of stdout.

Ejemplo

verbumia export --nested --out ./dump

verbumia releases publish Trigger a CDN release; subscribed SDKs refresh live.

Flags

--version <slug> Version to publish (defaults to main).
--dry-run Preview only; publishes nothing.

Ejemplo

verbumia releases publish

verbumia snapshot Fetch the public CDN bundles into a build-time module for offline-first SDK fallback.

Flags

--format <ts|json> Output format: ts (default) or json.
--out <file> Write to a file instead of stdout.
--cdn <base> CDN base (defaults to https://cdn.verbumia.ca).

Ejemplo

verbumia snapshot --out src/verbumia-bundles.ts

Every command also accepts --host <url> to override the configured API host for a single run.

Cambios incompatibles próximos conocidos

Fijados por transparencia. Cada uno llega en una release menor con una ventana de deprecation de una release — corre la última @verbumia/cli y verás el aviso antes de la rotura.

MCP surface + scope. The whole CLI moved from the project REST surface to the MCP surface. Re-issue your API key with the mcp:* scope — project-scoped keys now return 403.
push is one-shot. push now sends your entire locales/ tree in a single import call (it was create-key plus a PUT per translation). It is idempotent and prints created / updated / unchanged.
New commands. import, export, releases publish, snapshot and projects list are new in 0.2.0.