---
title: "Référence de la CLI"
description: "Toutes les sous-commandes de verbatra et les options globales qu'elles partagent, plus la façon dont la CLI lit ton environnement et charge les fichiers .env."
type: "reference"
---
# Référence de la CLI

Toutes les sous-commandes de verbatra et les options globales qu'elles partagent, plus la façon dont la CLI lit ton environnement et charge les fichiers .env.

`@verbatra/cli` fournit le binaire `verbatra`, une surcouche légère de [`@verbatra/sdk`](https://verbatra.kreitz-webdev.de/fr/docs/sdk.md).

## Commandes [#commandes]

Ces commandes font le travail :

<Cards>
  <Card title="init" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/init.md">Crée une config verbatra et un `.env.example` pour ce projet.</Card>
  <Card title="extract" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/extract.md">Analyse le code de ton application à la recherche des appels de traduction et ajoute les nouvelles clés au fichier de la locale source.</Card>
  <Card title="translate" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/translate.md">Traduit chaque locale cible une fois, puis termine.</Card>
  <Card title="watch" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/watch.md">Retraduit à chaque changement de la source jusqu'à interruption.</Card>
  <Card title="check" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/check.md">Signale les clés manquantes ou obsolètes par locale, en lecture seule.</Card>
  <Card title="diff" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/diff.md">Liste les clés exactes qui seraient ajoutées, retraduites ou orphelines par locale, en lecture seule.</Card>
  <Card title="report" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/report.md">Affiche un rapport en lecture seule : `report provenance` liste les traductions qu'une machine a écrites et celles qu'une personne a relues.</Card>
  <Card title="doctor" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/doctor.md">Valide la configuration du projet et signale tous les problèmes d'un coup, sans appeler de fournisseur.</Card>
  <Card title="pseudo" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/pseudo.md">Génère une pseudo-locale à partir des chaînes source, sans appeler de fournisseur.</Card>
  <Card title="types" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/types.md">Génère les déclarations TypeScript pour les clés de ton catalogue et les arguments de leurs messages, sans appeler de fournisseur.</Card>
  <Card title="export" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/export.md">Exporte les chaînes non traduites pour un traducteur humain, en classeur Excel, en un fichier CSV ou TSV par locale ou en un fichier XLIFF par locale pour un outil de TAO.</Card>
  <Card title="import" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/import.md">Réimporte un classeur rempli ou un fichier délimité dans les fichiers de locale.</Card>
  <Card title="tmx" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/tmx.md">Importe une mémoire de traduction TMX venant d'un autre outil dans la mémoire de ce projet, ou exporte la mémoire de ce projet dans un fichier TMX.</Card>
  <Card title="studio" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/studio.md">Démarre Verbatra Studio, le tableau de bord local de traduction.</Card>
  <Card title="mcp" href="https://verbatra.kreitz-webdev.de/fr/docs/cli/mcp.md">Démarre un serveur MCP en stdio qui expose les outils de verbatra à un client MCP.</Card>
</Cards>

## Installation et invocation [#installation-et-invocation]

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

```bash
npm install --save-dev @verbatra/cli
```

Puis lance le binaire via ton gestionnaire de paquets :

```bash
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 globales [#options-globales]

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.

| Option | Argument | Par défaut | Effet | Refusée par |
| --- | --- | --- | --- | --- |
| `--cwd` | `<path>` | répertoire courant | lance ici la recherche de la config et y résout les chemins que tu passes ; les fichiers de locale sont résolus par rapport au répertoire de la config trouvée ; `init` y écrit ses fichiers | aucune |
| `--config` | `<path>` | en chercher une | charge ce fichier de config au lieu d'en chercher un ; voir l'[ordre de recherche](https://verbatra.kreitz-webdev.de/fr/docs/config-file.md) | `init` |
| `--json` | aucun | désactivé | affiche une [enveloppe](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#sortie-json) lisible par machine sur stdout, une ligne par enregistrement ; les erreurs vont toujours sur stderr | `mcp`, `studio` |
| `-q`, `--quiet` | aucun | désactivé | n'affiche que les résultats, avertissements et erreurs : ni progression, ni suggestions, ni lignes d'information ; fonctionne avant ou après le nom de la commande | aucune |
| `--no-color` | aucun | couleur dans un terminal | ne colore jamais la sortie ; voir [Sortie dans le terminal](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#sortie-dans-le-terminal) | aucune |
| `-h`, `--help` | aucun | désactivé | affiche l'aide du programme ou de la commande et sort avec `0` | aucune |
| `-V`, `--version` | aucun | désactivé | affiche la version de la CLI et sort avec `0` | aucune |

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`](https://verbatra.kreitz-webdev.de/fr/docs/error-codes.md#invalid_option) pour toute commande, avant toute lecture ou écriture.

## Fichiers d'environnement [#fichiers-denvironnement]

`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](https://verbatra.kreitz-webdev.de/fr/docs/providers.md). 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 .gitignore [#entrées-du-gitignore]

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`](https://verbatra.kreitz-webdev.de/fr/docs/cli/init.md). Un `.gitignore` qui est un lien symbolique sortant du projet reste inchangé, avec un avertissement que `--json` et `--quiet` conservent.

## Sortie dans le terminal [#sortie-dans-le-terminal]

La couleur, le spinner, `--quiet` et les variables qui les pilotent sont décrits dans [Sortie dans le terminal](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#sortie-dans-le-terminal).

## Codes de sortie [#codes-de-sortie]

Le contrat des codes de sortie et ses cas particuliers sont sur [Codes de sortie et sortie JSON](https://verbatra.kreitz-webdev.de/fr/docs/cli/output.md#codes-de-sortie). Chaque page de commande ne liste que les codes que cette commande renvoie.