CLI

Preview

@verbumia/cli

Une petite CLI scriptable pour tout ce que vous feriez sinon en cliquant dans le dashboard : initialiser un projet, push/pull les traductions, bloquer la CI sur la dérive remote, jeter un œil à la file des manquantes. Licence MIT, distribuée via npm et Homebrew.

Preview · CLI en développement. Les commandes et la config peuvent évoluer avant 1.0 — voir les changements à venir au bas de cette page. Les 9 commandes et leurs args sont confirmés pour V1 ; le format wire peut bouger.

Installer

Requiert Node 20 LTS ou plus récent. Deux binaires sont installés : verbumia et l'alias plus court vrb — interchangeables.

terminal Tap publié au lancement V1

1# installer une fois globalement — bin "verbumia" + alias court "vrb"2npm i -g @verbumia/cli 4# ou utiliser sans installation5npx @verbumia/cli@latest <command> 7# Le tap Homebrew est publié au lancement V18brew install verbumia/tap/verbumia-cli

S'authentifier

Obtenez une clé API depuis Org Settings → API Keys → Create dans votre dashboard (le secret est affiché une fois ; copiez l'intégralité de vrb_live_<prefix>.<secret>). Utilisez le scope project:read pour status / pull / missing / projects, project:write pour push.

interactif

1verbumia login2? Collez votre clé API depuis Org Settings → API Keys (saisie masquée) :3vrb_live_••••••••••••••••.•••••••••••••••••••••4✓ Validée via GET /v1/auth/me — marc@example.com (org : acme).5✓ Sauvegardée dans ~/.verbumia/credentials (chmod 600).

CI / non-interactif

1# CI / non-interactif — la variable d'env bat le fichier mais perd contre --token2export VERBUMIA_TOKEN=vrb_live_<prefix>.<secret>3verbumia push

L'ordre de précédence est flag --token → env VERBUMIA_TOKEN → ~/.verbumia/credentials. Le fichier credentials est un JSON de forme {"default":"<token>","<host>":"<token>"} pour garder des clés séparées prod / staging / instance self-hostée sur la même machine.

Configurer votre projet

Lancez verbumia init dans votre repo pour générer verbumia.config.json à la racine, ou écrivez-le à la main. La CLI auto-détecte aussi verbumia.config.{ts,js,toml,yml} si vous préférez un de ces formats.

verbumia.config.json

1// verbumia.config.json — à la racine du projet2// auto-détecté aussi : 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}

Référence des champs

Champ	Type	Défaut / note
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 }

Commandes

Chaque commande accepte --config <path> pour pointer vers un fichier de config alternatif, --token <vrb_live_…> pour override l'auth résolue, et --json pour sortir en format machine.

verbumia init Scaffolde verbumia.config.json dans le répertoire courant en vous guidant sur project_uuid, langue source, et format.

Flags

--project <uuid> pré-remplit project_uuid
--source-language <code> BCP-47 (défaut « en »)
--format <fmt> json | xliff

Exemple

verbumia init --project <uuid>

verbumia login Prompt interactif pour la clé API. La CLI valide la clé via GET /v1/auth/me, puis l'écrit dans ~/.verbumia/credentials en mode 600.

Flags

--token <vrb_live_…> passe la clé en ligne (skip le prompt ; utile pour les scripts)

Exemple

verbumia login

verbumia logout Efface ~/.verbumia/credentials. Ne révoque pas la clé côté serveur — pour ça, utilisez le dashboard.

Flags

Pas de flag spécifique. Utilisez les flags globaux décrits ci-dessus.

Exemple

verbumia logout

verbumia whoami Affiche l'org, le binding projet, et les scopes accordés à la clé active. Pratique pour debugger les surprises « mauvais compte ».

Flags

Pas de flag spécifique. Utilisez les flags globaux décrits ci-dessus.

Exemple

verbumia whoami

verbumia projects Liste les projets accessibles à la clé active.

Flags

--json sortie machine-readable (défaut : table TTY)

Exemple

verbumia projects --json

verbumia status Diff read-only entre les fichiers locaux et le projet remote — ajoutés / supprimés / modifiés par locale et namespace. Aucune écriture.

Flags

--locale <code> limite à une locale
--namespace <slug> limite à un namespace

Exemple

verbumia status --locale fr-CA

verbumia push Upload les fichiers i18n locaux vers Verbumia : crée les nouvelles clés, met à jour les valeurs modifiées, et décide selon la policy on-missing-key quand une clé est référencée mais absente.

Flags

--locale <code> push seulement cette locale
--namespace <slug> push seulement ce namespace
--dry-run affiche le plan sans appliquer
--on-missing-key <create|skip> quoi faire quand le fichier local référence une clé absente côté serveur

Exemple

verbumia push --dry-run

verbumia pull Télécharge les traductions remote dans le pull.dest_dir configuré — atomique par fichier. Sert aussi de path « export » : passez --format pour convertir au passage.

Flags

--locale <code> pull seulement cette locale
--namespace <slug> pull seulement ce namespace
--format <fmt> json | xliff (override config.format pour ce run)

Exemple

verbumia pull --format xliff

verbumia missing Liste les events de clés manquantes capturés par le SDK runtime. Read-only — pratique pour trier depuis le terminal sans ouvrir le dashboard.

Flags

--locale <code> filtre par locale
--since <iso> seulement les events plus récents que ce timestamp ISO-8601
--limit <n> lignes max (défaut 20)

Exemple

verbumia missing --locale ja --limit 50

Pas de commande export séparée — pull --format couvre. L'import depuis Lokalise / Crowdin / Phrase arrive post-V1 quand les endpoints backend correspondants seront livrés ; en attendant, déposez un fichier JSON ou XLIFF dans votre push.source_dir et lancez verbumia push.

Intégration CI

Lancez verbumia status --json sur chaque PR. Un exit non-zero sur la dérive vous donne un garde-fou pas cher du type « quelqu'un a-t-il shipé une clé sans prévenir l'i18n ? ».

.github/workflows/i18n.yml

1# .github/workflows/i18n.yml — bloquer le build sur la dérive 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 }}

Changements cassants à venir

Épinglés pour la transparence. Chacun arrive dans une release mineure avec une fenêtre de deprecation d'une release — restez sur la dernière @verbumia/cli et vous verrez l'avertissement avant la casse.

V1.1 — config.format se sépare en { input, output } pour que push et pull puissent utiliser des formats différents.
V1.1 — push --on-missing-key devient un objet de politique (multi-cas) au lieu d'un enum à 2 valeurs.
V1.1 — le format "json-flat" est renommé "flat-json" pour la cohérence du nommage.

Ensuite

Démarrage rapide

React + i18next

Brancher le SDK runtime et capturer les clés manquantes.

MCP

Configurer Claude Desktop

Piloter le même projet depuis votre agent IA.