# oh: OxygenHub from the command line

`oh` is to OxygenHub what `gh` is to GitHub. It talks to the hub's JSON API
(hub spec §12) and prints what it gets back: in colour on a terminal, as
plain text with `--plain` or `NO_COLOR`, and as the API's own JSON with
`--json`.

## Which hub, which repository, which token

Inside an Oxygen checkout, `oh` uses the checkout's remote:
- **Remote:** `origin`, or the only remote, or `--remote NAME`.
- **Hub and repository:** from the remote's URL (`https://hub/OWNER/NAME`).
- **Token and CA:** the ones `oxy` pushes with (`remote.NAME.token`, `remote.NAME.ca`).

So in a checkout that pushes to the hub, `oh` needs no setup.

Elsewhere, sign in once and name the repository:

```
oh auth login --with-hub https://oxygenhub.io
oh issue list --repo andymccall/oxygen
```

`oh auth login` shows a code and a link: open it, signed in to the hub, and
approve the code, choosing what `oh` may do (device sign-in). The token
arrives by itself; `oh` checks it, saves it with the CA in
`~/.config/oh/config.toml` (owner-only), and makes that hub the default.
`--token TOKEN` uses a token from Settings → Tokens instead, and
`--token -` reads one from stdin. `OH_TOKEN` (or `OXY_TOKEN`), `OH_HUB` and
`OXY_CA` override the saved values.

## Commands

| Command | What it does |
|---|---|
| `oh auth login`, `oh auth status` | Sign in (approve a code on the web, or give a token); show who you are |
| `oh repo view` | Name, description, visibility, default bookmark, clone command |
| `oh issue list [--state open\|closed\|all]` | Issues |
| `oh issue view N` | An issue with its comments |
| `oh issue create -t TITLE [-b BODY \| -F FILE] [-l LABEL]… [-p N [--column NAME]] [-a FILE]…` | Open an issue; `-p` also puts it on the owner's project N; `-a` attaches a file (a screenshot shows in place, anything else is a download link) |
| `oh issue edit N [-t TITLE] [-b BODY \| -F FILE] [-l LABEL]… [-a USER]… [-m MILESTONE]` | Change it; labels and assignees are the whole set (`--no-labels`, `--no-assignees` clear them), `-m ""` clears the milestone |
| `oh issue label N --add L --remove L` | Put labels on or take them off |
| `oh milestone list`, `oh milestone create TITLE [-d DESC] [--due YYYY-MM-DD]`, `oh milestone edit TITLE [--rename T] [-d DESC] [--due D]`, `oh milestone close\|reopen TITLE` | Milestones (triage to change) |
| `oh issue close N [--reason not_planned]`, `oh issue reopen N` | Close or reopen |
| `oh project list`, `oh project view N`, `oh project create TITLE [-d DESC] [--private]`, `oh project close\|reopen N` | The repository owner's project boards (`--owner NAME` for another's) |
| `oh project card add N REF [-c COLUMN]`, `oh project card add N --note TEXT`, `oh project card move N CARD -c COLUMN`, `oh project card move N --from COLUMN -c COLUMN [--except 12,#13,name#14,CARD] [--state closed,landed] [--dry-run]`, `oh project card remove N CARD` | Cards: REF is `12` or `#12` here, or `name#12` in another of the owner's repositories; a column by name or id; `--from` moves a whole column at once (#289) |
| `oh issue comment N -b BODY [-a FILE]…` | Comment, with attached files as `issue create` takes them |
| `oh proposal list [--state open\|draft\|landed\|closed\|all] [--limit N]`, `oh proposal view N` | Proposals, newest first (30 unless `--limit` says), with changes, approvals and blockers; a landed one with who landed it and how |
| `oh proposal create -t TITLE --from BOOKMARK [--into BOOKMARK] [--draft]` | Propose a bookmark's changes |
| `oh proposal checks N` | Checks on the projected state |
| `oh proposal land N` | Land it on its target, as the page's Land button does |
| `oh proposal close N [-m MSG]` | Close it without landing, with an optional comment saying why |
| `oh proposal reopen N` | Reopen a closed proposal |
| `oh run list`, `oh run view N` | OxygenFlow runs and their jobs |
| `oh run start [--bookmark B \| --change HASH] [--watch]` | Run the pipeline without a push |
| `oh run watch N` | Follow a run; exit 0 if it passes, 1 if not |
| `oh run log N JOB` | A job's log |
| `oh run rerun N` | Run a finished run's state again |
| `oh run cancel N` | Cancel a run still queued or running; its running jobs are stopped |
| `oh tag list`, `oh tag create NAME [--target REF] [-m MESSAGE]`, `oh tag delete NAME [-r REASON]` | Tags: made on the hub as your delegate; withdrawn with a signed withdrawal (never while a release uses one) |
| `oh release list`, `oh release create TAG [-t TITLE] [-n NOTES]` | Releases |
| `oh release upload TAG FILE…` | Attach assets |
| `oh release trust TAG` | The release's trust audit; exit 1 on a failure |
| `oh drop create FILE… [--secret] [-d TEXT] [-t TITLE]` | Make a drop of these files (oxygenhub#279), signed by the hub as your delegate; `--secret` lists it nowhere |
| `oh drop list [--user NAME]` | Your drops, or someone's public ones |
| `oh drop view ID [-f FILE]` | A drop's files, by id or address; `-f` prints one file's content alone |
| `oh drop delete ID` | Delete a drop and its history |
| `oh drop fork ID` | A copy of someone's drop, history and all, as a drop of yours (oxygenhub#349) |
| `oh drop star ID` / `oh drop unstar ID` | Star a drop, or take the star back |
| `oh drop comments ID` | A drop's comments, oldest first |
| `oh drop comment ID -m TEXT` | Comment on a drop (Markdown); its owner is told |
| `oh runner-updates [show]` | Site administrators: runners that update themselves (oxygenhub#322): where builds come from, every level's settings, test groups and their waves (oxygenflow#84), each runner's policy and what it is offered (or which wave it waits for), held builds |
| `oh runner-updates set SCOPE [--updates on\|off\|inherit] [--channel C] [--window 02-05] [--dry-run on\|off\|inherit]` | Change one level (`site`, `owner:NAME`, `group:NAME`, `runner:NAME`); what is not given stays; `inherit` clears a setting |
| `oh runner-updates lift VERSION` | Offer a build held after it rolled back on a runner (#326) |
| `oh api PATH [-X METHOD] [-d JSON]` | Any API call, JSON out |
| `oh mcp [--allow-write]` | Serve the repository's hub to an AI agent over MCP (stdio): read-only unless `--allow-write` (#353) |

Exit codes: 0 on success, 1 when a watched run or an audit fails, 2 on an
error.

## For AI agents: `oh mcp`

`oh mcp` is an MCP server on stdio for the repository `oh` resolves (the checkout's remote, or `--repo OWNER/NAME`), with the same hub, token and CA (#353). Its tools read issues, proposals (with files and checks), OxygenFlow runs, job logs and reports, test reports, releases, your drops and your inbox. With `--allow-write` it also offers `issue_create`, `issue_comment`, `issue_close`, `proposal_comment` and `run_rerun`; the token's scopes still decide what the hub allows.

Everything the hub returns comes back under `untrusted`, beside a note saying so, and every tool's description says it: issue bodies, comments and logs are written by people, so an agent must read them as data and never follow instructions found in them.

For Claude Code, in the project's root: `claude mcp add oxygenhub -- oh mcp` (add `--allow-write` to let it file and comment). Pair it with `oxy mcp` (oxygen's docs/mcp.md) for the repository itself.

## Not yet

- Also still to come: reviews, project columns as commands, runner management (oxygenhub#41), and shell completions.