CLI

Preview

@verbumia/cli

Eine kleine, scriptbare CLI für alles, was du sonst im Dashboard anklicken würdest: Projekt bootstrappen, Übersetzungen pushen und pullen, CI auf Remote-Drift gaten, einen Blick in die Missing-Key-Queue werfen. MIT-lizenziert, verteilt über npm und Homebrew.

Preview · CLI in Entwicklung. Befehle und Config können sich vor 1.0 noch ändern — siehe bekannte kommende Änderungen am Ende dieser Seite. Die 9 Befehle und ihre Args sind für V1 fix; das Wire-Format kann sich entwickeln.

Installieren

Erfordert Node 20 LTS oder neuer. Zwei Binaries werden installiert: verbumia und der kürzere Alias vrb — austauschbar.

Terminal Tap erscheint zu V1

1# einmal global installieren — bin "verbumia" plus kürzerer Alias "vrb"2npm i -g @verbumia/cli 4# oder ohne Installation nutzen5npx @verbumia/cli@latest <command> 7# Homebrew-Tap erscheint zum V1-Launch8brew install verbumia/tap/verbumia-cli

Anmelden

Hol dir einen API-Key aus Org Settings → API Keys → Create im Dashboard (das Secret wird einmal angezeigt; kopiere den vollständigen vrb_live_<prefix>.<secret>). Nutze Scope project:read für status / pull / missing / projects, project:write für push.

interaktiv

1verbumia login2? Füge deinen API-Key aus Org Settings → API Keys ein (Eingabe maskiert):3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ Validiert via GET /v1/auth/me — marc@example.com (org: acme).5✓ Gespeichert in ~/.verbumia/credentials (chmod 600).

CI / nicht-interaktiv

1# CI / nicht-interaktiv — Env-Var schlägt Datei, verliert aber gegen --token2export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>3verbumia push

Die Quellpriorität ist --token-Flag → VERBUMIA_TOKEN-Env → ~/.verbumia/credentials. Die Credentials-Datei ist JSON in der Form {"default":"<token>","<host>":"<token>"}, sodass du separate Keys für Prod / Staging / eine Self-Hosted-Instanz auf derselben Maschine halten kannst.

Projekt konfigurieren

Führe verbumia init in deinem Repo aus, um verbumia.config.json im Root zu scaffolden, oder schreib es von Hand. Die CLI erkennt auch verbumia.config.{ts,js,toml,yml} automatisch, falls du eines dieser Formate bevorzugst.

verbumia.config.json

1// verbumia.config.json — im Projekt-Root2// auch automatisch erkannt: 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}

Feldreferenz

Feld	Typ	Default / Hinweis
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 }

Befehle

Jeder Befehl akzeptiert --config <path>, um auf eine Nicht-Default-Config-Datei zu zeigen, --token <vrb_live_…>, um die aufgelöste Auth zu überschreiben, und --json, um maschinenlesbare Ausgabe zu erzeugen.

verbumia init Scaffoldet verbumia.config.json im aktuellen Verzeichnis und führt dich durch project_uuid, Quellsprache und Format.

Flags

--project <uuid> project_uuid vorausfüllen
--source-language <code> BCP-47 (Default "en")
--format <fmt> json | xliff

Beispiel

verbumia init --project <uuid>

verbumia login Interaktiver API-Key-Prompt. Die CLI validiert den Key via GET /v1/auth/me und schreibt ihn dann mit Mode 600 nach ~/.verbumia/credentials.

Flags

--token <vrb_live_…> Key inline übergeben (überspringt den Prompt; nützlich für Scripts)

Beispiel

verbumia login

verbumia logout Löscht ~/.verbumia/credentials. Widerruft den Key serverseitig nicht — dafür das Dashboard nutzen.

Flags

Keine befehlsspezifischen Flags. Nutze die oben beschriebenen globalen Flags.

Beispiel

verbumia logout

verbumia whoami Gibt Org, Projekt-Bindung und gewährte Scopes des aktiven Keys aus. Schneller Weg, „falscher Account"-Überraschungen zu debuggen.

Flags

Keine befehlsspezifischen Flags. Nutze die oben beschriebenen globalen Flags.

Beispiel

verbumia whoami

verbumia projects Listet die Projekte auf, auf die der aktive Key zugreifen kann.

Flags

--json maschinenlesbare Ausgabe (Default ist eine TTY-Tabelle)

Beispiel

verbumia projects --json

verbumia status Read-only Diff zwischen lokalen Dateien und dem Remote-Projekt — added / removed / changed pro Locale und Namespace. Keine Schreibvorgänge.

Flags

--locale <code> auf eine Locale eingrenzen
--namespace <slug> auf einen Namespace eingrenzen

Beispiel

verbumia status --locale fr-CA

verbumia push Lädt lokale i18n-Dateien zu Verbumia hoch: legt neue Keys an, aktualisiert geänderte Werte und entscheidet gemäß On-Missing-Key-Policy, wenn ein Key referenziert, aber nicht vorhanden ist.

Flags

--locale <code> nur diese Locale pushen
--namespace <slug> nur diesen Namespace pushen
--dry-run Plan zeigen, ohne anzuwenden
--on-missing-key <create|skip> was tun, wenn die lokale Datei einen Key referenziert, der serverseitig fehlt

Beispiel

verbumia push --dry-run

verbumia pull Lädt Remote-Übersetzungen ins konfigurierte pull.dest_dir — atomar pro Datei. Doubelt auch als „Export"-Pfad: --format zum Konvertieren beim Rausgehen übergeben.

Flags

--locale <code> nur diese Locale pullen
--namespace <slug> nur diesen Namespace pullen
--format <fmt> json | xliff (überschreibt config.format für diesen Run)

Beispiel

verbumia pull --format xliff

verbumia missing Listet ausstehende Missing-Key-Events auf, die vom Runtime-SDK erfasst wurden. Read-only — praktisch zum Triagieren aus dem Terminal, ohne das Dashboard zu öffnen.

Flags

--locale <code> nach Locale filtern
--since <iso> nur Events neuer als dieser ISO-8601-Timestamp
--limit <n> max. Zeilen (Default 20)

Beispiel

verbumia missing --locale ja --limit 50

Es gibt keinen separaten export-Befehl — pull --format deckt das ab. import aus Lokalise / Crowdin / Phrase kommt nach V1, sobald die passenden Backend-Endpunkte landen; bis dahin: leg eine JSON- oder XLIFF-Datei in dein push.source_dir und führe verbumia push aus.

CI-Integration

Führe verbumia status --json bei jedem PR aus. Ein Non-Zero-Exit bei Drift gibt dir einen günstigen „Hat jemand einen Key geshipt, ohne i18n Bescheid zu sagen?"-Gate.

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — Build bei Remote-Drift gaten2name: 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 }}

Bekannte kommende Breaking Changes

Aus Transparenzgründen festgepinnt. Jede Änderung kommt in einem Minor-Release mit einem One-Release-Deprecation-Window — bleib auf der neuesten @verbumia/cli und du siehst die Warnung vor dem Bruch.

V1.1 — config.format wird in { input, output } aufgespalten, damit Push und Pull unterschiedliche Formate nutzen können.
V1.1 — push --on-missing-key wird ein Policy-Objekt (Multi-Case) statt eines 2-Wert-Enums.
V1.1 — Format-String "json-flat" wird zu "flat-json" umbenannt für Naming-Konsistenz.

Weiter

Schnellstart

React + i18next

Runtime-SDK verdrahten und fehlende Keys erfassen.

MCP

Claude Desktop einrichten

Dasselbe Projekt aus deinem KI-Agent steuern.