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 utveckling. Kommandon och config kan ändras före 1.0 — se kända kommande ändringar längst ner på sidan. De 9 kommandona och deras args är bekräftade för V1; wire-formatet kan utvecklas.

Install

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

terminal Tap publiceras vid V1

1# installera en gång globalt — bin "verbumia" plus kortare alias "vrb"2npm i -g @verbumia/cli 4# eller använd utan installation5npx @verbumia/cli@latest <command> 7# Homebrew tap publiceras vid V1-lanseringen8brew install verbumia/tap/verbumia-cli

Autentisera

Hämta en API-nyckel från Org Settings → API Keys → Create i dashboarden (hemligheten visas en gång; kopiera hela vrb_live_<prefix>.<secret>). Använd scope project:read för status / pull / missing / projects, project:write för push.

interaktiv

1verbumia login2? Klistra in din API-nyckel från Org Settings → API Keys (input maskeras):3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ Validerad via GET /v1/auth/me — marc@example.com (org: acme).5✓ Sparad i ~/.verbumia/credentials (chmod 600).

CI / icke-interaktiv

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

Källprioriteten är --token-flagga → VERBUMIA_TOKEN-env → ~/.verbumia/credentials. Credentials-filen är JSON med form {"default":"<token>","<host>":"<token>"} så du kan ha separata nycklar för prod / staging / en self-hosted-instans på samma maskin.

Konfigurera projektet

Kör verbumia init i repot för att scaffolda verbumia.config.json i roten, eller skriv den för hand. CLI:n upptäcker även verbumia.config.{ts,js,toml,yml} automatiskt om du föredrar något av de formaten.

verbumia.config.json

1// verbumia.config.json — i projektroten2// auto-detekteras också: 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}

Fältreferens

Fält	Typ	Default / not
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 }

Kommandon

Varje kommando tar --config <path> för att peka på en icke-default config-fil, --token <vrb_live_…> för att överskrida den upplösta auth, och --json för maskinläsbar output.

verbumia init Scaffoldar verbumia.config.json i nuvarande katalog genom att gå igenom project_uuid, källspråk och format.

Flaggor

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

Exempel

verbumia init --project <uuid>

verbumia login Interaktiv API-nyckelprompt. CLI:n validerar nyckeln via GET /v1/auth/me, skriver sedan den till ~/.verbumia/credentials med mode 600.

Flaggor

--token <vrb_live_…> skicka nyckeln inline (hoppar över prompten; bra för skript)

Exempel

verbumia login

verbumia logout Raderar ~/.verbumia/credentials. Återkallar inte nyckeln serversidan — använd dashboarden för det.

Flaggor

Inga kommandospecifika flaggor. Använd de globala flaggorna ovan.

Exempel

verbumia logout

verbumia whoami Skriver ut den aktiva nyckelns org, projektbindning och beviljade scopes. Snabbt sätt att debugga "fel konto"-överraskningar.

Flaggor

Inga kommandospecifika flaggor. Använd de globala flaggorna ovan.

Exempel

verbumia whoami

verbumia projects Listar projekten som den aktiva nyckeln kan komma åt.

Flaggor

--json maskinläsbar output (default är en TTY-tabell)

Exempel

verbumia projects --json

verbumia status Read-only diff mellan lokala filer och fjärrprojektet — added / removed / changed per locale och namespace. Inga skrivningar.

Flaggor

--locale <code> begränsa till en locale
--namespace <slug> begränsa till ett namespace

Exempel

verbumia status --locale fr-CA

verbumia push Laddar upp lokala i18n-filer till Verbumia: skapar nya nycklar, uppdaterar ändrade värden och avgör enligt on-missing-key-policyn när en nyckel refereras men saknas.

Flaggor

--locale <code> pusha bara denna locale
--namespace <slug> pusha bara detta namespace
--dry-run visa planen utan att tillämpa
--on-missing-key <create|skip> vad som ska göras när den lokala filen refererar en nyckel som saknas serversidan

Exempel

verbumia push --dry-run

verbumia pull Laddar ner fjärröversättningar till den konfigurerade pull.dest_dir — atomärt per fil. Fungerar också som din "export"-väg: skicka --format för att konvertera på vägen ut.

Flaggor

--locale <code> pulla bara denna locale
--namespace <slug> pulla bara detta namespace
--format <fmt> json | xliff (överskrider config.format för denna körning)

Exempel

verbumia pull --format xliff

verbumia missing Listar pending missing-key-events fångade av runtime-SDK:n. Read-only — användbart för triage från terminalen utan att öppna dashboarden.

Flaggor

--locale <code> filtrera per locale
--since <iso> bara events nyare än denna ISO-8601-timestamp
--limit <n> max rader (default 20)

Exempel

verbumia missing --locale ja --limit 50

Det finns inget separat export-kommando — pull --format täcker det. import från Lokalise / Crowdin / Phrase kommer post-V1 när matchande backend-endpoints landar; tills dess, lägg en JSON- eller XLIFF-fil i din push.source_dir och kör verbumia push.

CI-integration

Kör verbumia status --json på varje PR. Non-zero exit vid drift ger dig en billig "shippade någon en nyckel utan att säga till i18n?"-gate.

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — gate:a 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 }}

Kända kommande breaking changes

Pinnade för transparens. Varje landar i en minor release med ett one-release deprecation-fönster — kör på senaste @verbumia/cli så ser du varningen innan brytet.

V1.1 — config.format delas i { input, output } så att push och pull kan använda olika format.
V1.1 — push --on-missing-key blir ett policy-objekt (multi-case) istället för en 2-värdes-enum.
V1.1 — format-strängen "json-flat" döps om till "flat-json" för naming-konsekvens.