CLI

Preview

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

Preview · CLI en desarrollo. Comandos y config pueden moverse antes de 1.0 — mira cambios próximos conocidos al final de esta página. Los 9 comandos y sus args están confirmados para V1; el formato de transporte puede evolucionar.

Instalar

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

terminal Tap se publica en V1

1# instalar globalmente una vez — bin "verbumia" más alias corto "vrb"2npm i -g @verbumia/cli 4# o usar sin instalar5npx @verbumia/cli@latest <command> 7# El tap de Homebrew se publica en el lanzamiento V18brew install verbumia/tap/verbumia-cli

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.

interactivo

1verbumia login2? Pega tu API key desde Org Settings → API Keys (entrada enmascarada):3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ Validada vía GET /v1/auth/me — marc@example.com (org: acme).5✓ Guardada en ~/.verbumia/credentials (chmod 600).

CI / no interactivo

1# CI / no interactivo — la env var le gana al archivo pero pierde contra --token2export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>3verbumia push

El orden de precedencia es flag --token → env VERBUMIA_TOKEN → ~/.verbumia/credentials. El archivo de credentials es un JSON con forma {"default":"<token>","<host>":"<token>"} para mantener keys separadas para prod / staging / una instancia self-hosted en la misma máquina.

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// verbumia.config.json — en la raíz del proyecto2// también auto-detectado: 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}

Referencia de campos

Campo	Type	Default / nota
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 }

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.

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
--source-language <code> BCP-47 (default "en")
--format <fmt> json | xliff

Ejemplo

verbumia init --project <uuid>

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

--token <vrb_live_…> pasa la key inline (salta el prompt; útil para scripts)

Ejemplo

verbumia login

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 projects Lista los proyectos a los que la key activa tiene acceso.

Flags

--json salida machine-readable (default es una tabla TTY)

Ejemplo

verbumia projects --json

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

--locale <code> limita a un locale
--namespace <slug> limita a un namespace

Ejemplo

verbumia status --locale fr-CA

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

--locale <code> push solo de este locale
--namespace <slug> push solo de este namespace
--dry-run muestra el plan sin aplicarlo
--on-missing-key <create|skip> qué hacer cuando el archivo local referencia una clave ausente del lado del servidor

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

--locale <code> pull solo de este locale
--namespace <slug> pull solo de este namespace
--format <fmt> json | xliff (sobrescribe config.format para esta corrida)

Ejemplo

verbumia pull --format xliff

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

--locale <code> filtra por locale
--since <iso> solo eventos más recientes que este timestamp ISO-8601
--limit <n> filas máx (default 20)

Ejemplo

verbumia missing --locale ja --limit 50

No hay un comando export separado — pull --format lo cubre. import desde Lokalise / Crowdin / Phrase llega post-V1 cuando aterricen los endpoints backend correspondientes; por ahora, deja un archivo JSON o XLIFF en tu push.source_dir y ejecuta verbumia push.

Integración CI

Ejecuta verbumia status --json en cada PR. Un exit distinto de cero ante drift te da un guard barato del tipo "¿alguien ha shipado una clave sin avisar a i18n?".

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — bloquea el build ante drift remoto2name: 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 }}

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.

V1.1 — config.format se separa en { input, output } para que push y pull puedan usar formatos distintos.
V1.1 — push --on-missing-key pasa a ser un objeto de política (multi-caso) en vez de un enum de 2 valores.
V1.1 — el string de formato "json-flat" se renombra a "flat-json" por consistencia de naming.