CLI

Preview

@verbumia/cli

Uma CLI pequena e scriptável para tudo o que farias a clicar no dashboard: arrancar um projeto, push/pull de traduções, bloquear o CI por drift remoto, espreitar a fila de chaves em falta. Licença MIT, distribuída via npm e Homebrew.

Preview · CLI em desenvolvimento. Comandos e config podem mexer-se antes do 1.0 — vê alterações futuras conhecidas ao fundo desta página. Os 9 comandos e os seus args estão confirmados para V1; o wire format pode evoluir.

Instalar

Requer Node 20 LTS ou mais recente. São instalados dois binários: verbumia e o alias mais curto vrb — permutáveis.

terminal Tap publica no V1

1# instala globalmente uma vez — bin "verbumia" mais alias curto "vrb"2npm i -g @verbumia/cli 4# ou usa sem instalar5npx @verbumia/cli@latest <command> 7# O tap do Homebrew publica no lançamento V18brew install verbumia/tap/verbumia-cli

Autenticar

Obtém uma API key em Org Settings → API Keys → Create no teu dashboard (o secret é mostrado uma vez; copia o vrb_live_<prefix>.<secret> completo). Usa o scope project:read para status / pull / missing / projects, project:write para push.

interativo

1verbumia login2? Cola a tua API key de Org Settings → API Keys (input mascarado):3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ Validada via GET /v1/auth/me — marc@example.com (org: acme).5✓ Guardada em ~/.verbumia/credentials (chmod 600).

CI / não interativo

1# CI / não interativo — a env var ganha ao ficheiro mas perde contra --token2export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>3verbumia push

A ordem de precedência é flag --token → env VERBUMIA_TOKEN → ~/.verbumia/credentials. O ficheiro de credentials é JSON com a forma {"default":"<token>","<host>":"<token>"} para manteres keys separadas para prod / staging / uma instância self-hosted na mesma máquina.

Configura o teu projeto

Corre verbumia init no teu repo para gerar verbumia.config.json na raiz, ou escreve-o à mão. A CLI também deteta automaticamente verbumia.config.{ts,js,toml,yml} se preferires um desses formatos.

verbumia.config.json

1// verbumia.config.json — na raiz do projeto2// também detetado automaticamente: 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}

Referência 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 aceita --config <path> para apontar para um ficheiro de config não default, --token <vrb_live_…> para sobrescrever a auth resolvida e --json para emitir output legível por máquina.

verbumia init Gera verbumia.config.json no diretório atual guiando-te por project_uuid, língua de origem e formato.

Flags

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

Exemplo

verbumia init --project <uuid>

verbumia login Prompt interativo para a API key. A CLI valida a key via GET /v1/auth/me e depois escreve-a em ~/.verbumia/credentials com mode 600.

Flags

--token <vrb_live_…> passa a key inline (salta o prompt; útil para scripts)

Exemplo

verbumia login

verbumia logout Apaga ~/.verbumia/credentials. Não revoga a key do lado servidor — para isso, usa o dashboard.

Flags

Sem flags específicas do comando. Usa as flags globais descritas acima.

Exemplo

verbumia logout

verbumia whoami Imprime a org, o binding de projeto e os scopes concedidos à key ativa. Forma rápida de debugar surpresas de "conta errada".

Flags

Sem flags específicas do comando. Usa as flags globais descritas acima.

Exemplo

verbumia whoami

verbumia projects Lista os projetos a que a key ativa tem acesso.

Flags

--json output legível por máquina (default é uma tabela TTY)

Exemplo

verbumia projects --json

verbumia status Diff só de leitura entre os ficheiros locais e o projeto remoto — adicionados / removidos / alterados por locale e namespace. Sem escritas.

Flags

--locale <code> restringe a um locale
--namespace <slug> restringe a um namespace

Exemplo

verbumia status --locale fr-CA

verbumia push Envia os ficheiros i18n locais para o Verbumia: cria chaves novas, atualiza valores alterados e decide segundo a policy on-missing-key quando uma chave é referenciada mas está ausente.

Flags

--locale <code> push apenas deste locale
--namespace <slug> push apenas deste namespace
--dry-run mostra o plano sem aplicar
--on-missing-key <create|skip> o que fazer quando o ficheiro local referencia uma chave ausente do lado servidor

Exemplo

verbumia push --dry-run

verbumia pull Descarrega as traduções remotas para o pull.dest_dir configurado — atómico por ficheiro. Serve também como caminho de "export": passa --format para converter à saída.

Flags

--locale <code> pull apenas deste locale
--namespace <slug> pull apenas deste namespace
--format <fmt> json | xliff (sobrescreve config.format para este run)

Exemplo

verbumia pull --format xliff

verbumia missing Lista os eventos pendentes de chaves em falta capturados pelo SDK em runtime. Só leitura — útil para triagem a partir do terminal sem abrir o dashboard.

Flags

--locale <code> filtra por locale
--since <iso> apenas eventos mais recentes que este timestamp ISO-8601
--limit <n> linhas max (default 20)

Exemplo

verbumia missing --locale ja --limit 50

Não há um comando export separado — pull --format cobre-o. import a partir de Lokalise / Crowdin / Phrase chega pós-V1 quando aterrarem os endpoints backend correspondentes; por agora, coloca um ficheiro JSON ou XLIFF na tua push.source_dir e corre verbumia push.

Integração CI

Corre verbumia status --json em cada PR. Um exit não-zero por drift dá-te um guard barato do género "alguém shippou uma chave sem avisar a i18n?".

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — bloqueia a build por 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 }}

Breaking changes futuras conhecidas

Fixadas por transparência. Cada uma chega numa release minor com uma janela de deprecation de uma release — corre a última @verbumia/cli e vês o aviso antes da quebra.

V1.1 — config.format divide-se em { input, output } para que push e pull possam usar formatos diferentes.
V1.1 — push --on-missing-key passa a ser um objeto de policy (multi-caso) em vez de um enum de 2 valores.
V1.1 — a string de formato "json-flat" é renomeada para "flat-json" por consistência de naming.

Seguinte

Início rápido

React + i18next

Liga o SDK runtime e captura chaves em falta.

MCP

Configurar o Claude Desktop

Pilota o mesmo projeto a partir do teu agente AI.