# CLI flags

> Every scribiz flag with its values and defaults, grouped by what it does.

Page: https://scribiz.com/docs/cli/flags

Flags go anywhere after the command. Both `--flag value` and `--flag=value` work. A lone `--` ends the flags, and whatever follows is treated as an input, even if it looks like a command. An unknown flag is a usage error with exit code 2. `scribiz --help` and `scribiz <command> --help` print the same list.

An empty argument is a usage error too (exit code 2, `Missing input`). It is never read as the current folder, so `scribiz "$URL"` with `$URL` unset does not run every file in the folder. Write `.` for the current folder.

## Output

| Flag | Value | Default | What it does |
| --- | --- | --- | --- |
| `-f`, `--format` | `srt`, `vtt`, `txt`, `md`, `context`, `json` | `srt`; `context` for `scribiz context` | The output format. See [Output formats](https://scribiz.com/docs/cli/formats.md). |
| `-o`, `--output` | A file or a folder | Standard output for one input | Where to write. `-` is standard output. A path with an extension is a file. A path with none, one that ends in `/`, or an existing folder is a folder. With several inputs it must be a folder. A name Scribiz picks itself never replaces a file that exists (`talk-2.srt`). A path you name is yours to replace. |
| `--offset` | Seconds, `MM:SS`, `HH:MM:SS.mmm` or `1h2m3s` | `0` | Shift every subtitle time. Use it to match a timeline that starts at `01:00:00`. It can be negative, and a time never goes below zero. It applies to SRT and VTT. |
| `--speakers`, `--no-speakers` | none | Automatic | Label who is speaking. Automatic means on for TXT, MD and Context when two or more voices were found, and off for SRT and VTT. For a run, it also decides whether to separate speakers (see [Speakers](#speakers)). |

## What to read

| Flag | Value | Default | What it does |
| --- | --- | --- | --- |
| `-m`, `--mode` | `auto`, `captions`, `audio`, `visual`, `full` | `auto` | What to run. `listen`, `watch` and `both` are aliases for `audio`, `visual` and `full`. See [Overview](https://scribiz.com/docs/overview.md#modes). |
| `--visual` | none | off | Also describe what is on screen. It turns `auto`, `audio` and `full` into `full`, and `visual` stays `visual`. It cannot be combined with `--mode captions`. |
| `-l`, `--language` | A BCP-47 code such as `en`, or a list such as `en,ru` | Detected | A hint for the spoken language. Repeat the flag or separate codes with commas. |
| `--proofread` | `terms`, `full` or `auto`, as `--proofread=terms` | `terms` | How much to correct. A bare `--proofread` means `full`. `--no-proofread` turns it off. `terms` applies the glossary fixes from the summary step. `full` checks every line. With `--vocabulary`, the default becomes `full`. |
| `--vocabulary` | Comma-separated terms | none | Names, brands and jargon to spell correctly. Used by proofreading. |
| `--detail` | `transcript`, `brief`, `full` | `full` | How much to write besides the transcript. `transcript` skips the summary step. `brief` writes the summary and chapters. `full` writes everything. |
| `--quality` | `standard`, `high` | `standard` | `high` reads the picture with the stronger model. It costs more. |
| `--max-cost` | US dollars | none | Stop before spending if the estimate is above this. Exits with `COST_LIMIT` and code 1. |
| `--max-duration` | Seconds or `HH:MM:SS` | none | Refuse a video longer than this. |
| `--no-cache` | none | off | Do not read or write the local cache. |
| `--force` | none | off | Recompute everything, but still save the result to the cache. |

### Speakers

`--speakers` asks speech to text to separate the voices. `--no-speakers` does not. With neither, speakers are on whenever Scribiz listens to the audio, because it costs the same, and a transcript from a platform's captions has none. Asking for speakers on a video that has captions makes Scribiz listen instead of using the captions, so it costs more.

## Sources

| Flag | Value | Default | What it does |
| --- | --- | --- | --- |
| `--cookies-from-browser` | A browser name such as `chrome`, `safari` or `firefox` | none | Use that browser's login for a site that needs one, through `yt-dlp`. Only that browser is tried. |
| `--cookies` | A path to a cookies file | none | Use a Netscape-format cookies file instead. |

If `cookiesBrowser` is set in your [config](https://scribiz.com/docs/cli/config.md), it is used for links that need a login, such as Instagram, and for nothing else. Cookies stay on your machine. See [Sources and limits](https://scribiz.com/docs/sources-and-limits.md#instagram-and-cookies).

## For programs

| Flag | Value | Default | What it does |
| --- | --- | --- | --- |
| `--json` | none | off | Print newline-delimited JSON messages on standard output and nothing else. Implies `--no-input`. See [The JSON protocol](https://scribiz.com/docs/cli/json-protocol.md). |
| `--out-file` | A path | none | With `--json`, write the Context there and print a `result` line that carries the path. Without it, one input's result up to 256 KB is printed inline. A batch (a folder or several inputs) is always written to files, with `--out-file` naming a folder. Without `--json` it is an error: use `-o`. |
| `--media-prep` | `ffmpeg`, `stdio`, `stdio,ffmpeg` | `ffmpeg` | Who prepares audio and video. `stdio` asks the host application over the protocol and needs `--json`. `stdio,ffmpeg` falls back to `ffmpeg` when the host answers `UNSUPPORTED`. |
| `--json-schema` | none | none | Print the JSON Schema of the Context, the events and the messages, and exit. |
| `--no-config` | none | off | Ignore `~/.scribiz/config.json`. Environment variables still apply. |
| `--no-input` | none | off | Never prompt. A missing credential is an error with exit code 3. |

Secrets never travel as flags: set `SCRIBIZ_API_KEY` or `GEMINI_API_KEY` in the environment, or save a credential with `scribiz login` or `scribiz setup`, so it does not show up in `ps`. See [Config and env](https://scribiz.com/docs/cli/config.md).

## For `login`, `doctor` and `mcp`

| Flag | Used by | What it does |
| --- | --- | --- |
| `--key` | `login` | Paste a Scribiz key made in the dashboard instead of confirming a code in the browser. It asks for the key, or reads one line from standard input. For CI, SSH and servers. |
| `--no-browser` | `login` | Print the sign-in link and do not open it. |
| `--client` | `login` | The client id sent to the device flow. It must be `scribiz-cli` (default), `scribiz-mac` or `scribiz-mcp`. Any other value fails with `Invalid client ID` (exit 5). You do not need it. |
| `--jit` | `doctor` | Run only the speed self-test for a compiled binary. Under the npm package, which runs on Node, it prints that it does not apply and exits 0. |
| `--allow-files` | `mcp` | Allow tools to read local files. |
| `--root` | `mcp` | A folder files may be read from. Repeat it for more. It needs `--allow-files`. The default is the current folder, but not `/`, your home folder or a folder above it: a client that starts the server in one of those must pass `--root`. |
| `--allow-private-network` | `mcp` | Allow links to your own machine and to private networks (`localhost`, `192.168.x.x`, `*.local`, a cloud metadata address), and pages that only the generic reader of `yt-dlp` handles. Both are refused by default, because the model that calls the server may have read a page that told it to fetch one. |

## Everywhere

| Flag | What it does |
| --- | --- |
| `-q`, `--quiet` | No progress on standard error. |
| `--verbose` | Print the engine's log lines on standard error. This turns off the live progress line. |
| `--no-color` | No color. `NO_COLOR` in the environment does the same. |
| `-h`, `--help` | Show help for the command. |
| `-v`, `--version` | Print the version. |

---

Checked against the Scribiz build on 2026-10-05.