> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openheaders.com/llms.txt
> Use this file to discover all available pages before exploring further.

# oh command reference

> Every oh command, option, and exit code — generated from the CLI source.

`oh` is the Open Headers command line: headless scripting and CI
integration against the same daemon the extension and desktop app use.
Every workspace-scoped command takes `--workspace <id>` and defaults to
the daemon's active workspace. The server-side control binary is
[`ohd`](/reference/ohd).

## Built-in commands

| Command                         | What it does                                                          |
| ------------------------------- | --------------------------------------------------------------------- |
| `oh status`                     | Probe the daemon's /mcp surface (running / disabled / bad token)      |
| `oh connect --token <secret>`   | Validate and save the daemon URL + token for later runs               |
| `oh channel [stable\|beta]`     | Show or set the release line version checks follow                    |
| `oh upgrade [--channel <line>]` | Download and install the newest release of this binary                |
| `oh autoupdate [on\|off]`       | Show or set background self-update (binary installs only; default on) |
| `oh changelog`                  | Show this release's notes (embedded at build; works offline)          |
| `oh completion bash\|zsh`       | Print a shell completion script (source it from your profile)         |
| `oh tui`                        | Open the terminal dashboard (early preview)                           |

## Read commands

| Command                     | What it does                                                 |
| --------------------------- | ------------------------------------------------------------ |
| `oh workspace list`         | List workspaces on the daemon host                           |
| `oh rules list`             | List the traffic rules in a workspace                        |
| `oh rules get <uid>`        | Fetch one rule by uid (full definition)                      |
| `oh env list`               | List environments and their variables                        |
| `oh vars list`              | List every variable scope (vault names only, secrets masked) |
| `oh request list`           | List saved API requests                                      |
| `oh request get <uid>`      | Fetch one saved request by uid (full definition)             |
| `oh workflow list`          | List live workflows                                          |
| `oh workflow history [uid]` | Cached workflow run records (capture names, never values)    |
| `oh activity`               | Recent change activity in a workspace (newest first)         |

## Write commands

| Command                         | What it does                                                 |
| ------------------------------- | ------------------------------------------------------------ |
| `oh rules toggle <uid> on\|off` | Set a rule's enabled flag (explicit state — CI-safe)         |
| `oh env switch <name-or-uid>`   | Switch the active environment by uid or name                 |
| `oh vars set <name> <value>`    | Upsert a variable in workspace scope (or a collection scope) |
| `oh workspace switch <id>`      | Make a workspace the active one on the daemon host           |

## Execute commands

Sends and runs are real network egress, gated behind the daemon's
`mcp.allowExecute` opt-in.

| Command                            | What it does                                                        |
| ---------------------------------- | ------------------------------------------------------------------- |
| `oh request send <name-or-uid>`    | Execute a saved request (status/size/timing; `--json` for the body) |
| `oh workflow run <name-or-uid>`    | Run a live workflow once, now (publishes exposed `{{live.*}}` vars) |
| `oh workspace diff [base] <other>` | Diff two workspaces (one id = against the active workspace)         |

## CI runner

| Command                           | What it does                                                                |
| --------------------------------- | --------------------------------------------------------------------------- |
| `oh run collection <name-or-uid>` | Run every request in a collection in tree order (CI exit codes + reporters) |
| `oh run folder <name-or-uid>`     | Run every request in a folder in tree order (CI exit codes + reporters)     |
| `oh run workflow <name-or-uid>`   | Run a workflow with CI exit codes and reporters (human/json/junit)          |

## Options

| Option                     | What it does                                                                             |
| -------------------------- | ---------------------------------------------------------------------------------------- |
| `--daemon <url>`           | Daemon URL (default [http://127.0.0.1:8137](http://127.0.0.1:8137); env OH\_DAEMON\_URL) |
| `--token <secret>`         | Paired daemon token (env OH\_TOKEN; oh connect persists one)                             |
| `--workspace <id>`         | Target workspace (default: the daemon's active workspace)                                |
| `--json`                   | Emit the tool result's JSON payload verbatim                                             |
| `--limit <n>`              | activity only: max entries (default 50)                                                  |
| `--none`                   | env switch only: select "No environment"                                                 |
| `--collection <uid>`       | vars set only: target that collection's variable scope                                   |
| `--secret`                 | vars set only: store the value as a masked secret                                        |
| `--env <name-or-uid>`      | request send / workflow run / run: environment to resolve variables under                |
| `--reporter <format>`      | run only: human (default), json, or junit                                                |
| `--output <file>`          | run only: write the report to a file (summary stays on stderr)                           |
| `--bail`                   | run only: stop at the first failure; the rest report skipped                             |
| `--channel <stable\|beta>` | upgrade only: release line to install from (persists like oh channel)                    |
| `--no-color`               | tui only: disable color output (NO\_COLOR is honored too)                                |
| `--ascii`                  | tui only: ASCII borders and markers instead of unicode                                   |

## Exit codes

| Code | Meaning                            |
| ---- | ---------------------------------- |
| `0`  | ok                                 |
| `1`  | operation failed                   |
| `2`  | usage                              |
| `3`  | daemon unreachable or MCP disabled |
| `4`  | auth/tier denied                   |

## Environment

| Variable        | What it does                                                             |
| --------------- | ------------------------------------------------------------------------ |
| `OH_DAEMON_URL` | Daemon URL (default `http://127.0.0.1:8137`; `oh connect` persists one). |
| `OH_TOKEN`      | Paired daemon token.                                                     |