# 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://earth.andymccall.xyz:7343 --ca ~/.config/oxy/earth-ca.pem

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]…` | Open an issue |

| `oh issue close N [--reason not_planned]`, `oh issue reopen N` | Close or reopen |

| `oh issue comment N -b BODY` | Comment |

| `oh proposal list [--state open\|draft\|landed\|closed\|all]`, `oh proposal view N` | Proposals, 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 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 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 api PATH [-X METHOD] [-d JSON]` | Any API call, JSON out |

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

error.

## Not yet

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