Référence de la CLI

@verbatra/cli fournit le binaire verbatra, une surcouche légère de @verbatra/sdk.

CommandesCopier le lien vers cette section

Ces commandes font le travail :

Installation et invocationCopier le lien vers cette section

Installe @verbatra/cli comme dépendance de développement :

npm install --save-dev @verbatra/cli

Puis lance le binaire via ton gestionnaire de paquets :

npx @verbatra/cli <command>

Il te faut Node.js ^22.22.0 || >=24 (la CLI 0.12.x accepte ^22.18.0 || >=24).

Tu veux essayer une commande avant d'installer ? npx @verbatra/cli <command> (npm) ou pnpm dlx @verbatra/cli <command> (pnpm) fonctionnent tous les deux sans installation locale préalable. Utilise toujours le nom avec scope : le nom verbatra sans scope sur npm n'appartient pas à ce projet.

Options globalesCopier le lien vers cette section

Ces options ont le même sens sur chaque commande qui les accepte, donc les pages de commande ne listent que leurs propres options. La dernière colonne nomme les commandes qui n'acceptent pas une option.

Une commande ou une option inconnue sort avec 2, tout comme un verbatra sans commande : il affiche l'aide sur stderr et, si aucune config n'est trouvée, suggère verbatra init. mcp n'écrit jamais sur stdout, car stdout est son canal de protocole, donc il refuse --json avec USAGE_ERROR. Depuis 0.12.0, un --cwd qui ne nomme aucun répertoire existant sort avec 2 et INVALID_OPTION pour toute commande, avant toute lecture ou écriture.

Fichiers d'environnementCopier le lien vers cette section

translate, watch, doctor, studio et mcp chargent .env.local puis .env depuis le répertoire de travail avant de s'exécuter. Quand la config trouvée par la recherche se trouve dans un répertoire parent, ils chargent ensuite les deux mêmes fichiers depuis ce répertoire ; avec --config, ils ne lisent que le répertoire de travail. Quand un client MCP change ses racines, le serveur MCP charge aussi les deux fichiers depuis la nouvelle racine du projet. doctor --literals fait exception : il ne lit aucune clé d'API, donc il ne charge aucun des deux fichiers. Une variable déjà définie dans ton environnement réel l'emporte toujours, puis les fichiers du répertoire de travail, puis ceux du répertoire de la config, et une valeur dans .env.local l'emporte sur la même variable dans .env. Les clés d'API sont lues uniquement depuis l'environnement, jamais depuis le fichier de config ni une option : voir Fournisseurs. Les commandes en lecture seule (check, diff, report), les commandes de remise (export, import), extract, init, pseudo, types et tmx n'appellent jamais de fournisseur et ne chargent aucun fichier .env.

Entrées du .gitignoreCopier le lien vers cette section

Une vraie exécution de translate, watch, import, tmx import ou pseudo ajoute aussi à un .gitignore existant à la racine du projet les entrées qui lui manquent parmi .env, .env.local, .verbatra-local/ et verbatra.cache.json, et les nomme sur stderr (--json et --quiet suppriment cette ligne). Cela se fait dès que la config est chargée, donc une exécution qui échoue ensuite l'a déjà fait. Un dry run ne touche pas au fichier, et aucune de ces commandes n'en crée ; c'est le rôle de verbatra init. Un .gitignore qui est un lien symbolique sortant du projet reste inchangé, avec un avertissement que --json et --quiet conservent.

Sortie dans le terminalCopier le lien vers cette section

La couleur, le spinner, --quiet et les variables qui les pilotent sont décrits dans Sortie dans le terminal.

Codes de sortieCopier le lien vers cette section

Le contrat des codes de sortie et ses cas particuliers sont sur Codes de sortie et sortie JSON. Chaque page de commande ne liste que les codes que cette commande renvoie.