verbatra studio

Start Verbatra Studio, a local web dashboard over your project: an overview of coverage, the last run and the run history with its cost new, the translation status and key list, the needs-review queue, the glossary and your resolved settings, live over the files on disk, including .verbatra-local/run-history.jsonl. Editing locale files and a file-backed glossary works out of the box; only provider spend is opt-in, behind --allow-spend.

SynopsisCopy Anchor Link

verbatra studio [flags]

ExamplesCopy Anchor Link

# start Verbatra Studio on the default port
verbatra studio

# enable the provider-calling actions, on a specific port
verbatra studio --allow-spend --port 6000

# let a browser agent operate the review actions
verbatra studio --expose-agent-tools

FlagsCopy Anchor Link

Also takes the global flags --cwd and --config.

BehaviorCopy Anchor Link

The printed URLCopy Anchor Link

Before it starts, studio loads the environment files and resolves your config once; a config error exits 2 before any server starts. Studio binds to 127.0.0.1 only and, once it is listening, prints one line to stdout:

Verbatra Studio running at http://127.0.0.1:5849/?token=<token>

Open that exact URL. The token is accepted only as ?token= on the first page load: the server checks it, sets an HttpOnly session cookie and redirects to /. Every later request needs that cookie. The token is not single-use, so treat the URL as a secret while Studio runs. Nothing is printed before the port is bound, so a failed startup never leaks a token.

A failed bind is reported on stderr as verbatra: error [<code>] <message>: PORT_IN_USE when another process holds the port (pass --port <n> or stop that process), or BIND_FAILED when the socket came up on an address other than 127.0.0.1.

Every page refreshes live when a locale, lock, provenance or limits file changes (Review in Studio describes the toast), and Run history and cost rereads when the history file changes, the tab regains focus or a run returns.

Navigation and linksnewCopy Anchor Link

Overview, Translations, Review, Glossary and Settings are links in the header, with a menu drawer below 1280px wide. The header search opens Translations filtered by what you type, and the theme button cycles system, light and dark. Translations and Review keep their state in the address, so you can link to them: #/translations?locale=de&status=missing&key=nav.title&q=text (status may repeat) and #/review?locale=de.

What it prints on stderrCopy Anchor Link

The URL line is the only stdout output. After it, stderr says which capabilities are on and how to turn on the ones that are off:

verbatra: spend tools off (pass --allow-spend to retranslate from Studio)
verbatra: agent tools off (pass --expose-agent-tools to register them)

With --allow-spend under provider none, the first line reads verbatra: spend tools off (provider none). On an interactive terminal it adds verbatra: press Ctrl-C to stop, and it prints verbatra: Studio stopped after shutdown. --verbose forwards one line per request (such as GET / 200, or POST /rpc status.check 200 naming the RPC method, never its parameters); Studio's own startup line is always dropped. --quiet keeps only the URL line. A verbatra: studio error: ... line, printed when a dashboard batch action stops on an unexpected server error, always appears, even under --quiet. See Terminal output.

Spend and agent toolsCopy Anchor Link

Without --allow-spend, Studio reads VERBATRA_STUDIO_ALLOW_SPEND; --expose-agent-tools falls back to VERBATRA_STUDIO_AGENT_TOOLS the same way. For both, 1, true, yes or on (any case, surrounding spaces ignored) counts as on, and the flag always wins over the variable. Without either, Studio never contacts a provider. Studio loads the environment files first, so both variables can live in .env.local or .env.

Spend from an agent needs both flags; neither implies the other. A config with provider: { id: "none" } disables machine translation by policy, so Studio withholds spend even with --allow-spend, and the Settings page says so. See Drive Studio with a browser agent for the tool catalog and the security model.

InstallationCopy Anchor Link

@verbatra/studio is its own package, reached through a dynamic import so the rest of the CLI works without it. Install it next to the CLI with npm install --save-dev @verbatra/cli @verbatra/studio. Without it, verbatra studio exits 2 with:

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

With pnpm, that install succeeds but exits 1 with ERR_PNPM_IGNORED_BUILDS and leaves an unanswered pnpm-workspace.yaml behind; see Troubleshooting for the one-time fix. npm and yarn do not have that problem.

Exit codesCopy Anchor Link

See Exit codes for the contract every command follows.

RelatedCopy Anchor Link

• Review in Studio walks through the Overview and Translations pages, the review queue and retranslating with --allow-spend.
• See changed files in Studio lists the locale files that differ from the last commit and the keys that changed in each.
• Drive Studio with a browser agent covers --expose-agent-tools and the WebMCP tool surface.
• verbatra check and verbatra diff are the same computations Studio shows live.