Vai al contenuto
Verbumia
Inizia gratis

CLI

v0.2.1 · npm · MIT

@verbumia/cli

Una CLI piccola e scriptabile per tutto quello che faresti clic-clic sulla dashboard: inizializzare un progetto, push/pull delle traduzioni, bloccare la CI sul drift remoto, sbirciare la coda delle chiavi mancanti. Licenza MIT, distribuita 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.

Installa

Richiede Node 20 LTS o più recente. Si installano due binari: verbumia e l'alias più corto vrb — intercambiabili.

terminal 
1# installa globalmente una volta — bin "verbumia" più alias corto "vrb"2npm i -g @verbumia/cli 4# o usa senza installare5npx @verbumia/cli <command>

Autenticati

Ottieni una API key da Org Settings → API Keys → Create nella tua dashboard (il secret è mostrato una volta; copia l'intero vrb_live_<prefix>.<secret>). Usa lo scope project:read per status / pull / missing / projects, project:write per 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 il tuo progetto

Lancia verbumia init nel tuo repo per generare verbumia.config.json nella root, oppure scrivilo a mano. La CLI auto-rileva anche verbumia.config.{ts,js,toml,yml} se preferisci uno di quei formati.

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.

Comandi

Ogni comando accetta --config <path> per puntare a un file di config non default, --token <vrb_live_…> per sovrascrivere l'auth risolta e --json per output machine-readable.

Auth & setup

verbumia login Prompt interattivo per la API key. La CLI valida la key via GET /v1/auth/me, poi la scrive in ~/.verbumia/credentials con mode 600.

Flags

  • --host <url> API host to authenticate against.
  • --token <key> passa la key inline (salta il prompt; utile per gli script)

Esempio

verbumia login --host https://api.verbumia.dev
verbumia logout Cancella ~/.verbumia/credentials. Non revoca la key lato server — per quello, usa la dashboard.

Flags

Nessun flag specifico del comando. Usa i flag globali descritti sopra.

Esempio

verbumia logout
verbumia whoami Stampa l'org, il binding di progetto e gli scope concessi alla key attiva. Modo rapido per debuggare sorprese da "account sbagliato".

Flags

Nessun flag specifico del comando. Usa i flag globali descritti sopra.

Esempio

verbumia whoami
verbumia init Genera verbumia.config.json nella directory corrente guidandoti su project_uuid, lingua sorgente e formato.

Flags

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

Esempio

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

Inspect

verbumia projects list Elenca i progetti a cui la key attiva ha accesso.

Flags

Nessun flag specifico del comando. Usa i flag globali descritti sopra.

Esempio

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

Flags

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

Esempio

verbumia keys list --namespace common
verbumia status Diff in sola lettura tra i file locali e il progetto remoto — aggiunti / rimossi / modificati per locale e namespace. Nessuna scrittura.

Flags

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

Esempio

verbumia status
verbumia missing Elenca gli eventi pendenti di chiavi mancanti catturati dall'SDK runtime. Sola lettura — comodo per triare dal terminale senza aprire la dashboard.

Flags

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

Esempio

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.

Esempio

verbumia import locales/fr/common.json
verbumia push Carica i file i18n locali su Verbumia: crea le nuove chiavi, aggiorna i valori modificati e decide secondo la policy on-missing-key quando una chiave è referenziata ma assente.

Flags

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

Esempio

verbumia push --dry-run
verbumia pull Scarica le traduzioni remote nella pull.dest_dir configurata — atomico per file. Funziona anche da path di "export": passa --format per convertire all'uscita.

Flags

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

Esempio

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.

Esempio

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.

Esempio

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

Esempio

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

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

Breaking change in arrivo noti

Pinnati per trasparenza. Ognuno arriva in una release minore con una finestra di deprecation di una release — sta sull'ultima @verbumia/cli e vedrai l'avviso prima della rottura.

Prossimo

Avvio rapido
React + i18next
Collega l'SDK runtime e cattura le chiavi mancanti.
MCP
Configura Claude Desktop
Pilota lo stesso progetto dal tuo agente AI.
Guide
Update source values
Change a key's source text after it exists.