---
title: "CLI-Referenz"
description: "Alle Unterbefehle von verbatra und die globalen Flags, die sie teilen, dazu wie die CLI deine Umgebung liest und .env-Dateien lädt."
type: "reference"
---
# CLI-Referenz

Alle Unterbefehle von verbatra und die globalen Flags, die sie teilen, dazu wie die CLI deine Umgebung liest und .env-Dateien lädt.

`@verbatra/cli` liefert das `verbatra`-Binary, einen dünnen Wrapper über [`@verbatra/sdk`](https://verbatra.kreitz-webdev.de/de/docs/sdk.md).

## Befehle [#befehle]

Diese Befehle erledigen die Arbeit:

<Cards>
  <Card title="init" href="https://verbatra.kreitz-webdev.de/de/docs/cli/init.md">Eine verbatra-Konfiguration und `.env.example` für dieses Projekt anlegen.</Card>
  <Card title="extract" href="https://verbatra.kreitz-webdev.de/de/docs/cli/extract.md">Deinen Anwendungscode nach Übersetzungsaufrufen durchsuchen und die neuen Keys in der Quell-Locale-Datei ergänzen.</Card>
  <Card title="translate" href="https://verbatra.kreitz-webdev.de/de/docs/cli/translate.md">Jedes Ziel-Locale einmal übersetzen, dann beenden.</Card>
  <Card title="watch" href="https://verbatra.kreitz-webdev.de/de/docs/cli/watch.md">Bei jeder Quelländerung neu übersetzen, bis unterbrochen wird.</Card>
  <Card title="check" href="https://verbatra.kreitz-webdev.de/de/docs/cli/check.md">Melden, welche Keys pro Locale fehlen oder veraltet sind, nur lesend.</Card>
  <Card title="diff" href="https://verbatra.kreitz-webdev.de/de/docs/cli/diff.md">Die genauen Keys pro Locale listen, die hinzugefügt oder neu übersetzt würden oder verwaist sind, nur lesend.</Card>
  <Card title="report" href="https://verbatra.kreitz-webdev.de/de/docs/cli/report.md">Einen nur lesenden Bericht ausgeben: `report provenance` listet, welche Übersetzungen eine Maschine geschrieben und welche eine Person geprüft hat.</Card>
  <Card title="doctor" href="https://verbatra.kreitz-webdev.de/de/docs/cli/doctor.md">Die Projekteinrichtung prüfen und alle Probleme auf einmal melden, ohne einen Provider aufzurufen.</Card>
  <Card title="pseudo" href="https://verbatra.kreitz-webdev.de/de/docs/cli/pseudo.md">Aus den Quellstrings eine Pseudo-Locale erzeugen, ohne einen Provider aufzurufen.</Card>
  <Card title="types" href="https://verbatra.kreitz-webdev.de/de/docs/cli/types.md">TypeScript-Deklarationen für deine Katalog-Keys und ihre Nachrichtenargumente erzeugen, ohne einen Provider aufzurufen.</Card>
  <Card title="export" href="https://verbatra.kreitz-webdev.de/de/docs/cli/export.md">Unübersetzte Strings für eine menschliche Übersetzerin exportieren, als Excel-Arbeitsmappe, als je eine CSV- oder TSV-Datei pro Locale oder als je eine XLIFF-Datei pro Locale für ein CAT-Tool.</Card>
  <Card title="import" href="https://verbatra.kreitz-webdev.de/de/docs/cli/import.md">Eine ausgefüllte Arbeitsmappe oder Datei mit Trennzeichen zurück in die Locale-Dateien importieren.</Card>
  <Card title="tmx" href="https://verbatra.kreitz-webdev.de/de/docs/cli/tmx.md">Einen TMX-Übersetzungsspeicher aus einem anderen Tool in den Speicher dieses Projekts importieren oder den Speicher dieses Projekts als TMX-Datei exportieren.</Card>
  <Card title="studio" href="https://verbatra.kreitz-webdev.de/de/docs/cli/studio.md">Verbatra Studio starten, das lokale Übersetzungs-Dashboard.</Card>
  <Card title="mcp" href="https://verbatra.kreitz-webdev.de/de/docs/cli/mcp.md">Einen stdio-MCP-Server starten, der die Tools von verbatra für einen MCP-Client bereitstellt.</Card>
</Cards>

## Installieren und aufrufen [#installieren-und-aufrufen]

Installiere `@verbatra/cli` als Dev-Dependency:

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

Starte das Binary anschließend über deinen Paketmanager:

```bash
npx @verbatra/cli <command>
```

Du brauchst Node.js `^22.22.0 || >=24` (CLI 0.12.x akzeptiert `^22.18.0 || >=24`).

Willst du einen Befehl vor der Installation ausprobieren? `npx @verbatra/cli <command>` (npm) oder `pnpm dlx @verbatra/cli <command>` (pnpm) funktionieren beide ohne vorherige lokale Installation. Nutze immer den Namen mit Scope: der Name `verbatra` ohne Scope gehört auf npm nicht zu diesem Projekt.

## Globale Flags [#globale-flags]

Diese Flags bedeuten bei jedem Befehl, der sie nimmt, dasselbe. Die Befehlsseiten führen deshalb nur ihre eigenen Flags auf. Die letzte Spalte nennt die Befehle, die ein Flag nicht nehmen.

| Flag | Argument | Standard | Wirkung | Nicht bei |
| --- | --- | --- | --- | --- |
| `--cwd` | `<path>` | aktuelles Verzeichnis | startet hier die Konfigurationssuche und löst die Pfade, die du übergibst, dagegen auf; Locale-Dateien werden gegen das Verzeichnis der gefundenen Konfiguration aufgelöst; `init` schreibt seine Dateien dorthin | keinem |
| `--config` | `<path>` | danach suchen | lädt diese Konfigurationsdatei, statt nach einer zu suchen; siehe die [Suchreihenfolge](https://verbatra.kreitz-webdev.de/de/docs/config-file.md) | `init` |
| `--json` | keins | aus | gibt einen maschinenlesbaren [Envelope](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#json-ausgabe) auf stdout aus, eine Zeile pro Datensatz; Fehler gehen weiter nach stderr | `mcp`, `studio` |
| `-q`, `--quiet` | keins | aus | gibt nur Ergebnisse, Warnungen und Fehler aus: keinen Fortschritt, keine Hinweise, keine Infozeilen; wirkt vor oder nach dem Befehlsnamen | keinem |
| `--no-color` | keins | Farbe im Terminal | färbt die Ausgabe nie ein; siehe [Terminalausgabe](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#terminalausgabe) | keinem |
| `-h`, `--help` | keins | aus | gibt die Hilfe des Programms oder des Befehls aus und endet mit `0` | keinem |
| `-V`, `--version` | keins | aus | gibt die Version der CLI aus und endet mit `0` | keinem |

Ein unbekannter Befehl oder ein unbekanntes Flag endet mit `2`, ebenso ein nacktes `verbatra` ohne Befehl: Es gibt die Hilfe auf stderr aus und schlägt `verbatra init` vor, wenn keine Konfiguration gefunden wird. `mcp` schreibt nie auf stdout, weil stdout sein Protokollkanal ist, und lehnt `--json` deshalb mit `USAGE_ERROR` ab. Ab 0.12.0 endet ein `--cwd`, das kein vorhandenes Verzeichnis nennt, bei jedem Befehl mit `2` und [`INVALID_OPTION`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#invalid_option), bevor etwas gelesen oder geschrieben wird.

## Umgebungsdateien [#umgebungsdateien]

`translate`, `watch`, `doctor`, `studio` und `mcp` laden `.env.local` und dann `.env` aus dem Arbeitsverzeichnis, bevor sie laufen. Liegt die Konfiguration, die die Suche gefunden hat, in einem übergeordneten Verzeichnis, laden sie danach dieselben zwei Dateien auch von dort; mit `--config` lesen sie nur das Arbeitsverzeichnis. Wechselt ein MCP-Client seine Roots, lädt der MCP-Server beide Dateien auch aus der neuen Projektwurzel. `doctor --literals` ist die Ausnahme: Dieser Aufruf liest keinen API-Key und lädt deshalb keine der beiden Dateien. Eine bereits in deiner echten Umgebung gesetzte Variable gewinnt immer, danach die Dateien des Arbeitsverzeichnisses, dann die des Konfigurationsverzeichnisses, und ein Wert in `.env.local` gewinnt gegen dieselbe Variable in `.env`. API-Keys werden nur aus der Umgebung gelesen, nie aus der Konfigurationsdatei oder einem Flag: siehe [Provider](https://verbatra.kreitz-webdev.de/de/docs/providers.md). Die nur lesenden Befehle (`check`, `diff`, `report`), die Übergabe-Befehle (`export`, `import`), `extract`, `init`, `pseudo`, `types` und `tmx` rufen nie einen Provider auf und laden keine `.env`-Dateien.

## .gitignore-Einträge [#gitignore-einträge]

Ein echter Lauf von `translate`, `watch`, `import`, `tmx import` oder `pseudo` ergänzt außerdem eine vorhandene `.gitignore` in der Projektwurzel um die fehlenden Einträge aus `.env`, `.env.local`, `.verbatra-local/` und `verbatra.cache.json` und nennt sie auf stderr (`--json` und `--quiet` lassen diese Zeile weg). Das geschieht, sobald die Konfiguration geladen ist, ein Lauf, der danach scheitert, hat es also schon getan. Ein Dry Run lässt die Datei in Ruhe, und keiner dieser Befehle legt eine an; das macht [`verbatra init`](https://verbatra.kreitz-webdev.de/de/docs/cli/init.md). Eine `.gitignore`, die ein symbolischer Link aus dem Projekt hinaus ist, bleibt unverändert, mit einer Warnung, die `--json` und `--quiet` beibehalten.

## Terminalausgabe [#terminalausgabe]

Farbe, Spinner, `--quiet` und die Variablen, die sie steuern, findest du unter [Terminalausgabe](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#terminalausgabe).

## Exit-Codes [#exit-codes]

Der Exit-Code-Vertrag und seine Randfälle stehen auf [Exit-Codes und JSON-Ausgabe](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#exit-codes). Jede Befehlsseite nennt nur die Codes, die dieser Befehl zurückgibt.