--- title: "verbatra studio" description: "Starte Verbatra Studio, das lokale Übersetzungs-Dashboard, sieh den Projektstand und arbeite die Review-Queue im Browser ab; Kosten nur mit deiner Freigabe." type: "reference" --- # verbatra studio Starte Verbatra Studio, das lokale Übersetzungs-Dashboard, sieh den Projektstand und arbeite die Review-Queue im Browser ab; Kosten nur mit deiner Freigabe. Starte Verbatra Studio, ein lokales Web-Dashboard über deinem Projekt: eine Übersicht mit Abdeckung, letztem Lauf und dem Laufverlauf samt Kosten , den Übersetzungsstatus mit Key-Liste, die Review-Warteschlange, das Glossar und deine aufgelösten Einstellungen, live über den Dateien auf der Platte, auch über `.verbatra-local/run-history.jsonl`. Locale-Dateien und ein dateibasiertes Glossar bearbeitest du ohne weiteres Flag; nur kostenpflichtige Provider-Aufrufe sind Opt-in, hinter `--allow-spend`. ## Synopsis [#synopsis] ```bash verbatra studio [flags] ``` ## Beispiele [#beispiele] ```bash # Verbatra Studio auf dem Standardport starten verbatra studio # die Provider-Aktionen einschalten, auf einem bestimmten Port verbatra studio --allow-spend --port 6000 # einen Browser-Agenten die Review-Aktionen bedienen lassen verbatra studio --expose-agent-tools ``` ## Flags [#flags] | Flag | Argument | Standard | Wirkung | | --- | --- | --- | --- | | `--port` | `` | `5849` | auf diesem Port lauschen; muss eine Ganzzahl von 1 bis 65535 sein | | `--allow-spend` | keins | aus, oder `VERBATRA_STUDIO_ALLOW_SPEND` | Studio erlauben, einen Übersetzungs-Provider aufzurufen (einen Key neu übersetzen, ausstehende Änderungen übersetzen) | | `--expose-agent-tools` | keins | aus, oder `VERBATRA_STUDIO_AGENT_TOOLS` | die Review-Aktionen von Studio als WebMCP-Tools registrieren, damit ein KI-Agent im Browser sie bedienen kann | | `--verbose` | keins | aus | zusätzlich eine stderr-Zeile pro Anfrage ausgeben, mit maskiertem Sitzungstoken | Außerdem nimmt `studio` die [globalen Flags](https://verbatra.kreitz-webdev.de/de/docs/cli.md#globale-flags) `--cwd` und `--config`. ## Verhalten [#verhalten] ### Die ausgegebene URL [#die-ausgegebene-url] Vor dem Start lädt `studio` die [Umgebungsdateien](https://verbatra.kreitz-webdev.de/de/docs/cli.md#umgebungsdateien) und löst deine Konfiguration einmal auf; ein Konfigurationsfehler endet mit `2`, bevor irgendein Server startet. Studio bindet sich nur an `127.0.0.1` und gibt, sobald es lauscht, eine Zeile auf stdout aus: ``` Verbatra Studio running at http://127.0.0.1:5849/?token= ``` Öffne genau diese URL. Das Token wird nur als `?token=` beim ersten Seitenaufruf angenommen: Der Server prüft es, setzt ein HttpOnly-Sitzungscookie und leitet auf `/` weiter. Jede spätere Anfrage braucht dieses Cookie. Das Token ist nicht einmalig, behandle die URL also als Geheimnis, solange Studio läuft. Vor dem Binden des Ports wird nichts ausgegeben, ein fehlgeschlagener Start verrät also nie ein Token. Ein fehlgeschlagenes Binden meldet Studio auf stderr als `verbatra: error [] `: `PORT_IN_USE`, wenn ein anderer Prozess den Port hält (gib `--port ` an oder beende diesen Prozess), oder `BIND_FAILED`, wenn der Socket auf einer anderen Adresse als `127.0.0.1` hochkam. Jede Seite aktualisiert sich live, wenn sich eine Locale-Datei, die Lock-Datei, die Herkunftsdatei oder die Limits-Datei ändert ([In Studio prüfen](https://verbatra.kreitz-webdev.de/de/docs/review-in-studio.md#übersetze-ausstehende-änderungen) beschreibt die Benachrichtigung), und **Run history and cost** liest neu, wenn sich die Verlaufsdatei ändert, der Tab den Fokus zurückbekommt oder ein Lauf zurückkehrt. ### Navigation und Links [#navigation-und-links] Overview, Translations, Review, Glossary und Settings sind Links in der Kopfleiste, mit einem Menü unterhalb von 1280px Breite. Die Suche in der Kopfleiste öffnet Translations, gefiltert nach deiner Eingabe, und die Theme-Taste wechselt zwischen System, Hell und Dunkel. Translations und Review halten ihren Zustand in der Adresse, du kannst also darauf verlinken: `#/translations?locale=de&status=missing&key=nav.title&q=text` (`status` darf mehrfach stehen) und `#/review?locale=de`. ### Was es auf stderr ausgibt [#was-es-auf-stderr-ausgibt] Die URL-Zeile ist die einzige Ausgabe auf stdout. Danach sagt stderr, welche Fähigkeiten an sind und wie du die ausgeschalteten einschaltest: ```text output verbatra: spend tools off (pass --allow-spend to retranslate from Studio) verbatra: agent tools off (pass --expose-agent-tools to register them) ``` Mit `--allow-spend` unter dem Provider `none` lautet die erste Zeile `verbatra: spend tools off (provider none)`. In einem interaktiven Terminal kommt `verbatra: press Ctrl-C to stop` dazu, und nach dem Herunterfahren erscheint `verbatra: Studio stopped`. `--verbose` reicht eine Zeile pro Anfrage weiter (etwa `GET / 200`, oder `POST /rpc status.check 200` mit dem Namen der RPC-Methode, nie ihren Parametern); die eigene Startzeile von Studio wird immer verworfen. `--quiet` behält nur die URL-Zeile. Eine Zeile `verbatra: studio error: ...`, die erscheint, wenn eine Stapelaktion im Dashboard an einem unerwarteten Serverfehler scheitert, kommt immer, auch unter `--quiet`. Siehe [Terminalausgabe](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#terminalausgabe). ### Ausgaben und Agent-Tools [#ausgaben-und-agent-tools] Ohne `--allow-spend` liest Studio `VERBATRA_STUDIO_ALLOW_SPEND`; `--expose-agent-tools` greift auf dieselbe Weise auf `VERBATRA_STUDIO_AGENT_TOOLS` zurück. Bei beiden zählt `1`, `true`, `yes` oder `on` (Groß- und Kleinschreibung und umgebende Leerzeichen egal) als an, und das Flag gewinnt immer gegen die Variable. Ohne beides kontaktiert Studio nie einen Provider. Studio lädt vorher die [Umgebungsdateien](https://verbatra.kreitz-webdev.de/de/docs/cli.md#umgebungsdateien), also können beide Variablen in `.env.local` oder `.env` stehen. Ausgaben durch einen Agenten brauchen beide Flags; keines impliziert das andere. Eine Konfiguration mit `provider: { id: "none" }` schaltet Maschinenübersetzung per Richtlinie ab, dann hält Studio Ausgaben auch mit `--allow-spend` zurück, und die Settings-Seite sagt das. Den Tool-Katalog und das Sicherheitsmodell findest du unter [Studio mit einem Browser-Agenten steuern](https://verbatra.kreitz-webdev.de/de/docs/agent-tools-in-studio.md). ### Installation [#installation] `@verbatra/studio` ist ein eigenes Paket, das per dynamischem Import geladen wird, damit der Rest der CLI ohne es funktioniert. Installiere es neben der CLI mit `npm install --save-dev @verbatra/cli @verbatra/studio`. Fehlt es, endet `verbatra studio` mit `2` und dieser Meldung: ``` Verbatra Studio requires @verbatra/studio. Install it alongside the CLI with: npm install --save-dev @verbatra/studio, or run both without installing with: npx -y -p @verbatra/cli -p @verbatra/studio verbatra studio ``` Mit pnpm gelingt diese Installation, endet aber mit `1` und `ERR_PNPM_IGNORED_BUILDS` und hinterlässt eine unbeantwortete `pnpm-workspace.yaml`; die einmalige Lösung steht unter [Fehlerbehebung](https://verbatra.kreitz-webdev.de/de/docs/troubleshooting.md). npm und yarn haben dieses Problem nicht. ## Exit-Codes [#exit-codes] | Code | Bedeutung | | --- | --- | | `0` | sauber durch eine einzelne Unterbrechung beendet (Ctrl-C oder SIGTERM) | | `1` | das Beenden ist fehlgeschlagen: das Schließen des Servers hat beim Herunterfahren einen Fehler geworfen | | `2` | konnte nicht starten: ein Konfigurationsfehler, `@verbatra/studio` nicht installiert, der Port belegt oder ein ungültiges `--port` (`INVALID_PORT`) | | `130` | durch eine zweite Unterbrechung während des Herunterfahrens hart beendet | Den Vertrag, dem jeder Befehl folgt, findest du unter [Exit-Codes](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#exit-codes). ## Siehe auch [#siehe-auch] - [In Studio prüfen](https://verbatra.kreitz-webdev.de/de/docs/review-in-studio.md) führt durch die Seiten Overview und Translations, die Review-Warteschlange und das Neuübersetzen mit `--allow-spend`. - [Geänderte Dateien in Studio sehen](https://verbatra.kreitz-webdev.de/de/docs/changes-in-studio.md) listet die Locale-Dateien, die vom letzten Commit abweichen, und die Keys, die sich in jeder geändert haben. - [Studio mit einem Browser-Agenten steuern](https://verbatra.kreitz-webdev.de/de/docs/agent-tools-in-studio.md) behandelt `--expose-agent-tools` und die WebMCP-Tools. - [`verbatra check`](https://verbatra.kreitz-webdev.de/de/docs/cli/check.md) und [`verbatra diff`](https://verbatra.kreitz-webdev.de/de/docs/cli/diff.md) sind dieselben Berechnungen, die Studio live zeigt.