CLI

Preview

@verbumia/cli

A small, scriptable CLI for everything you'd otherwise click through the dashboard: bootstrap a project, push and pull translations, gate CI on remote drift, peek at the missing-key queue. MIT-licensed, distributed via npm and Homebrew.

Preview · CLI under utvikling. Kommandoer og config kan endres før 1.0 — se kjente kommende endringer nederst på siden. De 9 kommandoene og argumentene deres er bekreftet for V1; wire-formatet kan utvikle seg.

Install

Requires Node 20 LTS or newer. Two binaries get installed: verbumia and the shorter alias vrb — interchangeable.

terminal Tap publiseres ved V1

1# installer én gang globalt — bin "verbumia" pluss kortere alias "vrb"2npm i -g @verbumia/cli 4# eller bruk uten installasjon5npx @verbumia/cli@latest <command> 7# Homebrew-tap publiseres ved V1-lanseringen8brew install verbumia/tap/verbumia-cli

Autentiser

Hent en API-nøkkel fra Org Settings → API Keys → Create i dashbordet (hemmeligheten vises én gang; kopier hele vrb_live_<prefix>.<secret>). Bruk scope project:read for status / pull / missing / projects, project:write for push.

interaktiv

1verbumia login2? Lim inn API-nøkkelen din fra Org Settings → API Keys (input maskeres):3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ Validert via GET /v1/auth/me — marc@example.com (org: acme).5✓ Lagret i ~/.verbumia/credentials (chmod 600).

CI / ikke-interaktiv

1# CI / ikke-interaktiv — env-var slår filen men taper mot --token2export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>3verbumia push

Kildeprioriteten er --token-flagg → VERBUMIA_TOKEN-env → ~/.verbumia/credentials. Credentials-filen er JSON med form {"default":"<token>","<host>":"<token>"} så du kan holde separate nøkler for prod / staging / en self-hosted-instans på samme maskin.

Konfigurer prosjektet

Kjør verbumia init i repoet for å scaffolde verbumia.config.json i roten, eller skriv den for hånd. CLI-en oppdager også verbumia.config.{ts,js,toml,yml} automatisk hvis du foretrekker ett av de formatene.

verbumia.config.json

1// verbumia.config.json — i prosjektroten2// auto-detekteres også: 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}

Feltreferanse

Felt	Type	Default / merknad
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 }

Kommandoer

Hver kommando tar --config <path> for å peke på en ikke-default config-fil, --token <vrb_live_…> for å overstyre den oppløste auth, og --json for maskinlesbar output.

verbumia init Scaffolder verbumia.config.json i gjeldende katalog ved å føre deg gjennom project_uuid, kildespråk og format.

Flagg

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

Eksempel

verbumia init --project <uuid>

verbumia login Interaktiv API-nøkkelprompt. CLI-en validerer nøkkelen via GET /v1/auth/me, så skriver den til ~/.verbumia/credentials med mode 600.

Flagg

--token <vrb_live_…> send nøkkelen inline (hopper over prompten; nyttig for skript)

Eksempel

verbumia login

verbumia logout Sletter ~/.verbumia/credentials. Tilbakekaller ikke nøkkelen serversiden — bruk dashbordet for det.

Flagg

Ingen kommandospesifikke flagg. Bruk de globale flaggene over.

Eksempel

verbumia logout

verbumia whoami Skriver ut den aktive nøkkelens org, prosjektbinding og innvilgede scopes. Rask måte å debugge "feil konto"-overraskelser.

Flagg

Ingen kommandospesifikke flagg. Bruk de globale flaggene over.

Eksempel

verbumia whoami

verbumia projects Lister opp prosjektene den aktive nøkkelen har tilgang til.

Flagg

--json maskinlesbar output (default er en TTY-tabell)

Eksempel

verbumia projects --json

verbumia status Read-only diff mellom lokale filer og remote-prosjektet — added / removed / changed per locale og namespace. Ingen skrivinger.

Flagg

--locale <code> begrens til én locale
--namespace <slug> begrens til ett namespace

Eksempel

verbumia status --locale fr-CA

verbumia push Laster opp lokale i18n-filer til Verbumia: oppretter nye nøkler, oppdaterer endrede verdier og bestemmer ifølge on-missing-key-policyen når en nøkkel refereres men mangler.

Flagg

--locale <code> push bare denne locale
--namespace <slug> push bare dette namespace
--dry-run vis planen uten å anvende
--on-missing-key <create|skip> hva skal skje når den lokale filen refererer en nøkkel som mangler serversiden

Eksempel

verbumia push --dry-run

verbumia pull Laster ned remote-oversettelser til konfigurert pull.dest_dir — atomært per fil. Fungerer også som "export"-sti: send --format for å konvertere på vei ut.

Flagg

--locale <code> pull bare denne locale
--namespace <slug> pull bare dette namespace
--format <fmt> json | xliff (overstyrer config.format for denne kjøringen)

Eksempel

verbumia pull --format xliff

verbumia missing Lister pending missing-key-events fanget av runtime-SDK-en. Read-only — nyttig for triage fra terminalen uten å åpne dashbordet.

Flagg

--locale <code> filtrer per locale
--since <iso> bare events nyere enn denne ISO-8601-timestampen
--limit <n> maks rader (default 20)

Eksempel

verbumia missing --locale ja --limit 50

Det finnes ingen separat export-kommando — pull --format dekker det. import fra Lokalise / Crowdin / Phrase kommer post-V1 når tilsvarende backend-endepunkter lander; inntil da, legg en JSON- eller XLIFF-fil i push.source_dir og kjør verbumia push.

CI-integrasjon

Kjør verbumia status --json på hver PR. Non-zero exit ved drift gir deg en billig "shippet noen en nøkkel uten å si fra til i18n?"-gate.

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — gate build på remote-drift2name: 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 }}

Kjente kommende breaking changes

Pinnet for transparens. Hver lander i en minor release med et one-release deprecation-vindu — kjør på siste @verbumia/cli, så ser du advarselen før bruddet.

V1.1 — config.format deles i { input, output } slik at push og pull kan bruke ulike formater.
V1.1 — push --on-missing-key blir et policy-objekt (multi-case) i stedet for en 2-verdis enum.
V1.1 — format-strengen "json-flat" får nytt navn "flat-json" for naming-konsistens.