# API

> tbx subcommands, flags, exit codes, and output shapes.

Source: https://taskbox.n.yatsyk.com/docs/cli/api

# API

`tbx` is a binary, not a library — it ships only the `tbx` bin (mapped to
`./bin/tbx.mjs`, which dynamically imports the compiled `dist/cli.js`).

## Subcommands

| Command                     | Summary                                                                                                                          |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `tbx doctor`                | Checks runtime + image. Prints `PrepareResult` JSON; exits non-zero on `E_RUNTIME_UNAVAILABLE` (3) or `E_IMAGE_PULL_FAILED` (4). |
| `tbx prepare`               | Same as `doctor` but with `pullPolicy: if-missing`.                                                                              |
| `tbx media subtitles <url>` | Calls `tools.media.downloadSubtitles`. Returns a `TaskResult` JSON or JSONL stream.                                              |

`-h` / `--help` is honoured at every level.

## `tbx media subtitles` flags

| Flag                                        | Type   | Default | Summary                                                    |
| ------------------------------------------- | ------ | ------- | ---------------------------------------------------------- |
| `--languages a,b`                           | csv    | `en`    | Subtitle languages.                                        |
| `--format vtt\|srt\|ass\|json3`             | string | `vtt`   | Output format.                                             |
| `--auto`                                    | bool   | `true`  | Include auto-generated subtitles.                          |
| `--proxy URL`                               | string | —       | Proxy URL; flips network mode to `"proxy"`.                |
| `--proxy-type http\|https\|socks5\|socks5h` | string | `http`  | Proxy scheme.                                              |
| `--no-proxy`                                | bool   | `false` | Disable proxy even if `--proxy` is set.                    |
| `--output-dir DIR`                          | string | —       | Materialize artifacts to `DIR`.                            |
| `--timeout 120s`                            | string | —       | Accepts `s` / `ms` / `m` suffixes (bare number = seconds). |
| `--max-output-bytes 500MB`                  | string | —       | Accepted in v0.1, currently ignored.                       |
| `--json`                                    | bool   | `true`  | Pretty-print final result on stdout.                       |
| `--jsonl`                                   | bool   | `false` | Stream every `TaskEvent` as JSONL, then the final result.  |

## Exit codes (PRD §16.5)

| Code | Constant        | Triggered by                                                    |
| ---- | --------------- | --------------------------------------------------------------- |
| `0`  | `EXIT_OK`       | success                                                         |
| `1`  | `EXIT_GENERIC`  | unexpected non-`TaskboxError` failure                           |
| `2`  | `EXIT_SCHEMA`   | `E_SCHEMA_INVALID`, missing required argument                   |
| `3`  | `EXIT_RUNTIME`  | `E_RUNTIME_UNAVAILABLE`                                         |
| `4`  | `EXIT_IMAGE`    | `E_IMAGE_PULL_FAILED`                                           |
| `5`  | `EXIT_TIMEOUT`  | `E_TIMEOUT`                                                     |
| `7`  | `EXIT_NETWORK`  | `E_PROXY_INVALID`, `E_PROXY_CONNECT_FAILED`, `E_NETWORK_FAILED` |
| `9`  | `EXIT_ARTIFACT` | `E_ARTIFACT_MISSING`                                            |
| `10` | `EXIT_TOOL`     | `E_TOOL_EXIT_NONZERO`                                           |

## Output

* **Default (`--json`):** stderr gets human-readable progress (`→`, `✗`)
  and stdout gets a single pretty-printed JSON object. On error, stdout
  contains `{ ok: false, error: TaskboxError }` instead of throwing.
* **`--jsonl`:** stdout is a stream of `TaskEvent` JSON objects (one per
  line) followed by the final `TaskResult` on its own line. Stderr still
  carries the human-readable progress strings.

See the generated [JSDoc reference](/docs/cli/jsdoc) for the full surface.