CLI

Preview

@verbumia/cli

Mała, skryptowalna CLI do wszystkiego, co inaczej klikałbyś w panelu: bootstrap projektu, push i pull tłumaczeń, blokada CI na dryfie remote, podgląd kolejki brakujących kluczy. Licencja MIT, dystrybucja przez npm i Homebrew.

Preview · CLI w rozwoju. Komendy i config mogą się zmienić przed 1.0 — patrz znane nadchodzące zmiany na dole strony. 9 komend i ich argumenty są potwierdzone dla V1; format wire może ewoluować.

Instalacja

Wymaga Node 20 LTS lub nowszego. Instalowane są dwa binarne: verbumia i krótszy alias vrb — wymienne.

terminal Tap publikowany przy V1

1# instalacja raz globalnie — bin "verbumia" plus krótszy alias "vrb"2npm i -g @verbumia/cli 4# albo użyj bez instalacji5npx @verbumia/cli@latest <command> 7# Tap Homebrew publikowany przy starcie V18brew install verbumia/tap/verbumia-cli

Uwierzytelnij

Pobierz klucz API z Org Settings → API Keys → Create w panelu (sekret pokazuje się raz; skopiuj cały vrb_live_<prefix>.<secret>). Użyj scope project:read dla status / pull / missing / projects, project:write dla push.

interaktywnie

1verbumia login2? Wklej swój klucz API z Org Settings → API Keys (input maskowany):3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ Zwalidowany przez GET /v1/auth/me — marc@example.com (org: acme).5✓ Zapisany w ~/.verbumia/credentials (chmod 600).

CI / nieinteraktywnie

1# CI / nieinteraktywnie — env bije plik, ale przegrywa z --token2export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>3verbumia push

Kolejność źródeł to flag --token → env VERBUMIA_TOKEN → ~/.verbumia/credentials. Plik credentials to JSON o kształcie {"default":"<token>","<host>":"<token>"}, więc możesz trzymać oddzielne klucze dla prod / staging / instancji self-hosted na tej samej maszynie.

Konfiguruj projekt

Uruchom verbumia init w repo, by wygenerować verbumia.config.json w roocie, albo napisz go ręcznie. CLI auto-wykrywa też verbumia.config.{ts,js,toml,yml}, jeśli wolisz jeden z tych formatów.

verbumia.config.json

1// verbumia.config.json — w roocie projektu2// auto-wykrywane też: 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}

Referencja pól

Pole	Typ	Domyślnie / uwaga
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 }

Komendy

Każda komenda przyjmuje --config <path> do wskazania niestandardowego pliku config, --token <vrb_live_…> do nadpisania rozwiązanej autoryzacji oraz --json do wyjścia w formacie maszynowym.

verbumia init Scaffolduje verbumia.config.json w bieżącym katalogu, prowadząc cię przez project_uuid, język źródłowy i format.

Flagi

--project <uuid> wstępnie wypełnij project_uuid
--source-language <code> BCP-47 (domyślnie "en")
--format <fmt> json | xliff

Przykład

verbumia init --project <uuid>

verbumia login Interaktywny prompt klucza API. CLI waliduje klucz przez GET /v1/auth/me, potem zapisuje go w ~/.verbumia/credentials z trybem 600.

Flagi

--token <vrb_live_…> podaj klucz inline (pomija prompt; przydatne dla skryptów)

Przykład

verbumia login

verbumia logout Usuwa ~/.verbumia/credentials. Nie unieważnia klucza po stronie serwera — do tego użyj panelu.

Flagi

Brak flag specyficznych dla komendy. Użyj globalnych flag opisanych powyżej.

Przykład

verbumia logout

verbumia whoami Wypisuje organizację aktywnego klucza, powiązanie z projektem i nadane scope'y. Szybki sposób na debug niespodzianek typu „złe konto".

Flagi

Brak flag specyficznych dla komendy. Użyj globalnych flag opisanych powyżej.

Przykład

verbumia whoami

verbumia projects Listuje projekty, do których aktywny klucz ma dostęp.

Flagi

--json wyjście czytelne maszynowo (domyślnie jest tabela TTY)

Przykład

verbumia projects --json

verbumia status Diff tylko do odczytu między plikami lokalnymi a projektem remote — added / removed / changed per locale i namespace. Bez zapisów.

Flagi

--locale <code> zawęź do jednego locale
--namespace <slug> zawęź do jednego namespace

Przykład

verbumia status --locale fr-CA

verbumia push Wgrywa lokalne pliki i18n do Verbumia: tworzy nowe klucze, aktualizuje zmienione wartości i decyduje zgodnie z polityką on-missing-key, gdy klucz jest zreferowany, ale go brak.

Flagi

--locale <code> pushuj tylko ten locale
--namespace <slug> pushuj tylko ten namespace
--dry-run pokaż plan bez aplikowania
--on-missing-key <create|skip> co zrobić, gdy lokalny plik referuje klucz nieobecny po stronie serwera

Przykład

verbumia push --dry-run

verbumia pull Pobiera tłumaczenia remote do skonfigurowanego pull.dest_dir — atomowo per plik. Działa też jako ścieżka „export": podaj --format, by konwertować na wyjściu.

Flagi

--locale <code> pobierz tylko ten locale
--namespace <slug> pobierz tylko ten namespace
--format <fmt> json | xliff (nadpisuje config.format dla tego uruchomienia)

Przykład

verbumia pull --format xliff

verbumia missing Listuje oczekujące zdarzenia brakujących kluczy zarejestrowane przez SDK runtime. Tylko do odczytu — przydatne do triage'u z terminala bez otwierania panelu.

Flagi

--locale <code> filtruj po locale
--since <iso> tylko eventy nowsze niż ten timestamp ISO-8601
--limit <n> maksymalna liczba wierszy (domyślnie 20)

Przykład

verbumia missing --locale ja --limit 50

Nie ma osobnej komendy export — pull --format ją pokrywa. import z Lokalise / Crowdin / Phrase pojawi się po V1, gdy pojawią się odpowiednie endpointy backendu; tymczasem wrzuć plik JSON lub XLIFF do swojego push.source_dir i uruchom verbumia push.

Integracja CI

Uruchamiaj verbumia status --json przy każdym PR. Niezerowe wyjście na dryfie daje ci tani gate „czy ktoś wypchnął klucz bez powiadomienia i18n?".

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — blokuj build na dryfie remote2name: 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 }}

Znane nadchodzące breaking changes

Przypięte dla transparentności. Każda zmiana ląduje w releasie minor z oknem deprecation jednej releasy — bądź na najnowszej @verbumia/cli, a zobaczysz ostrzeżenie przed breakiem.

V1.1 — config.format rozdziela się na { input, output }, by push i pull mogły używać różnych formatów.
V1.1 — push --on-missing-key staje się obiektem polityki (multi-case) zamiast 2-wartościowego enuma.
V1.1 — format "json-flat" zmienia nazwę na "flat-json" dla spójności nazewnictwa.

Dalej

Szybki start

React + i18next

Podłącz SDK runtime i wyłapuj brakujące klucze.

MCP

Skonfiguruj Claude Desktop

Steruj tym samym projektem z agenta AI.