Saltar para o conteúdo
Verbumia
Começar grátis

CLI

v0.2.1 · npm · MIT

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

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

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

terminal 
1# instala globalmente uma vez — bin "verbumia" mais alias curto "vrb"2npm i -g @verbumia/cli 4# ou usa sem instalar5npx @verbumia/cli <command>

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.

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

Auth & setup

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

  • --host <url> API host to authenticate against.
  • --token <key> passa a key inline (salta o prompt; útil para scripts)

Exemplo

verbumia login --host https://api.verbumia.dev
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 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
  • --version <slug> Version slug to target (defaults to main).
  • --force Overwrite an existing config file.

Exemplo

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

Inspect

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

Flags

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

Exemplo

verbumia projects list
verbumia keys list List keys as namespace_slug/key_name.

Flags

  • --namespace <slug> Restrict to one namespace.

Exemplo

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

Flags

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

Exemplo

verbumia status
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

  • --language <code> Filter by language.
  • --namespace <slug> Filter by namespace.
  • --limit <n> linhas max (default 20)

Exemplo

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.

Exemplo

verbumia import locales/fr/common.json
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

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

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

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

Exemplo

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.

Exemplo

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.

Exemplo

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

Exemplo

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

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

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.

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.
Guide
Update source values
Change a key's source text after it exists.