CLI

Preview

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

Preview · CLI in sviluppo. Comandi e config possono cambiare prima della 1.0 — vedi cambiamenti in arrivo noti in fondo alla pagina. I 9 comandi e i loro args sono confermati per V1; il wire format può evolvere.

Installa

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

terminal Tap pubblicato al lancio V1

1# installa globalmente una volta — bin "verbumia" più alias corto "vrb"2npm i -g @verbumia/cli 4# o usa senza installare5npx @verbumia/cli@latest <command> 7# Il tap Homebrew è pubblicato al lancio V18brew install verbumia/tap/verbumia-cli

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.

interattivo

1verbumia login2? Incolla la tua API key da Org Settings → API Keys (input mascherato):3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ Validata via GET /v1/auth/me — marc@example.com (org: acme).5✓ Salvata in ~/.verbumia/credentials (chmod 600).

CI / non interattivo

1# CI / non interattivo — la env var batte il file ma perde contro --token2export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>3verbumia push

L'ordine di precedenza è flag --token → env VERBUMIA_TOKEN → ~/.verbumia/credentials. Il file credentials è un JSON nella forma {"default":"<token>","<host>":"<token>"} così puoi tenere key separate per prod / staging / un'istanza self-hosted sulla stessa macchina.

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// verbumia.config.json — nella root del progetto2// auto-rilevato anche: 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}

Riferimento campi

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 }

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.

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

Flags

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

Esempio

verbumia init --project <uuid>

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

--token <vrb_live_…> passa la key inline (salta il prompt; utile per gli script)

Esempio

verbumia login

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 projects Elenca i progetti a cui la key attiva ha accesso.

Flags

--json output machine-readable (default è una tabella TTY)

Esempio

verbumia projects --json

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

Flags

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

Esempio

verbumia status --locale fr-CA

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

--locale <code> push solo di questo locale
--namespace <slug> push solo di questo namespace
--dry-run mostra il piano senza applicarlo
--on-missing-key <create|skip> cosa fare quando il file locale referenzia una chiave assente lato server

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

--locale <code> pull solo di questo locale
--namespace <slug> pull solo di questo namespace
--format <fmt> json | xliff (sovrascrive config.format per questo run)

Esempio

verbumia pull --format xliff

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

--locale <code> filtra per locale
--since <iso> solo eventi più recenti di questo timestamp ISO-8601
--limit <n> righe max (default 20)

Esempio

verbumia missing --locale ja --limit 50

Non c'è un comando export separato — pull --format lo copre. import da Lokalise / Crowdin / Phrase arriva post-V1 quando atterrano gli endpoint backend corrispondenti; per ora, metti un file JSON o XLIFF nella tua push.source_dir e lancia verbumia push.

Integrazione CI

Lancia verbumia status --json a ogni PR. Un exit non-zero sul drift ti dà un guard a basso costo del tipo "qualcuno ha shippato una chiave senza avvisare i18n?".

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — blocca la build sul 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 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.

V1.1 — config.format si separa in { input, output } così push e pull possono usare formati diversi.
V1.1 — push --on-missing-key diventa un oggetto di policy (multi-caso) invece di un enum a 2 valori.
V1.1 — la stringa di formato "json-flat" viene rinominata in "flat-json" per coerenza di naming.

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.