---
title: "verbatra studio"
description: "Start Verbatra Studio, the local translation dashboard, to see project state and work the review queue in your browser, with spending off unless you allow it."
type: "reference"
---
# verbatra studio
Start Verbatra Studio, the local translation dashboard, to see project state and work the review queue in your browser, with spending off unless you allow it.
Start Verbatra Studio, a local web dashboard over your project: an overview of coverage, the last run and the run history with its cost , 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`.
## Synopsis [#synopsis]
```bash
verbatra studio [flags]
```
## Examples [#examples]
```bash
# 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
```
## Flags [#flags]
| Flag | Argument | Default | Effect |
| --- | --- | --- | --- |
| `--port` | `` | `5849` | listen on this port; must be an integer from 1 to 65535 |
| `--allow-spend` | none | off, or `VERBATRA_STUDIO_ALLOW_SPEND` | allow Studio to call a translation provider (retranslate a key, translate pending changes) |
| `--expose-agent-tools` | none | off, or `VERBATRA_STUDIO_AGENT_TOOLS` | register Studio's review actions as WebMCP tools so a browser AI agent can operate them |
| `--verbose` | none | off | also print one stderr line per request, with the session token masked |
Also takes the [global flags](https://verbatra.kreitz-webdev.de/docs/cli.md#global-flags) `--cwd` and `--config`.
## Behavior [#behavior]
### The printed URL [#the-printed-url]
Before it starts, `studio` loads the [environment files](https://verbatra.kreitz-webdev.de/docs/cli.md#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=
```
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 [] `: `PORT_IN_USE` when another process holds the port (pass `--port ` 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](https://verbatra.kreitz-webdev.de/docs/review-in-studio.md#translate-pending-changes) describes the toast), and **Run history and cost** rereads when the history file changes, the tab regains focus or a run returns.
### Navigation and links [#navigation-and-links]
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 stderr [#what-it-prints-on-stderr]
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:
```text output
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](https://verbatra.kreitz-webdev.de/docs/cli/output.md#terminal-output).
### Spend and agent tools [#spend-and-agent-tools]
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](https://verbatra.kreitz-webdev.de/docs/cli.md#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](https://verbatra.kreitz-webdev.de/docs/agent-tools-in-studio.md) for the tool catalog and the security model.
### Installation [#installation]
`@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](https://verbatra.kreitz-webdev.de/docs/troubleshooting.md) for the one-time fix. npm and yarn do not have that problem.
## Exit codes [#exit-codes]
| Code | Meaning |
| --- | --- |
| `0` | stopped cleanly by a single interrupt (Ctrl-C or SIGTERM) |
| `1` | stopping failed: closing the server threw during shutdown |
| `2` | could not start: a config error, `@verbatra/studio` not installed, the port in use, or an invalid `--port` (`INVALID_PORT`) |
| `130` | force-stopped by a second interrupt while shutdown was in flight |
See [Exit codes](https://verbatra.kreitz-webdev.de/docs/cli/output.md#exit-codes) for the contract every command follows.
## Related [#related]
- [Review in Studio](https://verbatra.kreitz-webdev.de/docs/review-in-studio.md) walks through the Overview and Translations pages, the review queue and retranslating with `--allow-spend`.
- [See changed files in Studio](https://verbatra.kreitz-webdev.de/docs/changes-in-studio.md) lists the locale files that differ from the last commit and the keys that changed in each.
- [Drive Studio with a browser agent](https://verbatra.kreitz-webdev.de/docs/agent-tools-in-studio.md) covers `--expose-agent-tools` and the WebMCP tool surface.
- [`verbatra check`](https://verbatra.kreitz-webdev.de/docs/cli/check.md) and [`verbatra diff`](https://verbatra.kreitz-webdev.de/docs/cli/diff.md) are the same computations Studio shows live.