| 1 |
# oh: OxygenHub from the command line |
| 2 |
|
| 3 |
`oh` is to OxygenHub what `gh` is to GitHub. It talks to the hub's JSON API |
| 4 |
(hub spec §12) and prints what it gets back: in colour on a terminal, as |
| 5 |
plain text with `--plain` or `NO_COLOR`, and as the API's own JSON with |
| 6 |
`--json`. |
| 7 |
|
| 8 |
## Which hub, which repository, which token |
| 9 |
|
| 10 |
Inside an Oxygen checkout, `oh` uses the checkout's remote: |
| 11 |
- **Remote:** `origin`, or the only remote, or `--remote NAME`. |
| 12 |
- **Hub and repository:** from the remote's URL (`https://hub/OWNER/NAME`). |
| 13 |
- **Token and CA:** the ones `oxy` pushes with (`remote.NAME.token`, `remote.NAME.ca`). |
| 14 |
|
| 15 |
So in a checkout that pushes to the hub, `oh` needs no setup. |
| 16 |
|
| 17 |
Elsewhere, sign in once and name the repository: |
| 18 |
|
| 19 |
``` |
| 20 |
oh auth login --with-hub https://oxygenhub.io |
| 21 |
oh issue list --repo andymccall/oxygen |
| 22 |
``` |
| 23 |
|
| 24 |
`oh auth login` shows a code and a link: open it, signed in to the hub, and |
| 25 |
approve the code, choosing what `oh` may do (device sign-in). The token |
| 26 |
arrives by itself; `oh` checks it, saves it with the CA in |
| 27 |
`~/.config/oh/config.toml` (owner-only), and makes that hub the default. |
| 28 |
`--token TOKEN` uses a token from Settings → Tokens instead, and |
| 29 |
`--token -` reads one from stdin. `OH_TOKEN` (or `OXY_TOKEN`), `OH_HUB` and |
| 30 |
`OXY_CA` override the saved values. |
| 31 |
|
| 32 |
## Commands |
| 33 |
|
| 34 |
|
| 35 |
|
| 36 |
| `oh auth login`, `oh auth status` | Sign in (approve a code on the web, or give a token); show who you are | |
| 37 |
| `oh repo view` | Name, description, visibility, default bookmark, clone command | |
| 38 |
| `oh issue list [--state open\|closed\|all]` | Issues | |
| 39 |
| `oh issue view N` | An issue with its comments | |
| 40 |
| `oh issue create -t TITLE [-b BODY \| -F FILE] [-l LABEL]… [-p N [--column NAME]]` | Open an issue; `-p` also puts it on the owner's project N | |
| 41 |
| `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 | |
| 42 |
| `oh issue label N --add L --remove L` | Put labels on or take them off | |
| 43 |
| `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) | |
| 44 |
| `oh issue close N [--reason not_planned]`, `oh issue reopen N` | Close or reopen | |
| 45 |
| `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) | |
| 46 |
| `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) | |
| 47 |
| `oh issue comment N -b BODY` | Comment | |
| 48 |
| `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 | |
| 49 |
| `oh proposal create -t TITLE --from BOOKMARK [--into BOOKMARK] [--draft]` | Propose a bookmark's changes | |
| 50 |
| `oh proposal checks N` | Checks on the projected state | |
| 51 |
| `oh proposal land N` | Land it on its target, as the page's Land button does | |
| 52 |
| `oh proposal close N [-m MSG]` | Close it without landing, with an optional comment saying why | |
| 53 |
| `oh proposal reopen N` | Reopen a closed proposal | |
| 54 |
| `oh run list`, `oh run view N` | OxygenFlow runs and their jobs | |
| 55 |
| `oh run start [--bookmark B \| --change HASH] [--watch]` | Run the pipeline without a push | |
| 56 |
| `oh run watch N` | Follow a run; exit 0 if it passes, 1 if not | |
| 57 |
| `oh run log N JOB` | A job's log | |
| 58 |
| `oh run rerun N` | Run a finished run's state again | |
| 59 |
| `oh run cancel N` | Cancel a run still queued or running; its running jobs are stopped | |
| 60 |
| `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) | |
| 61 |
| `oh release list`, `oh release create TAG [-t TITLE] [-n NOTES]` | Releases | |
| 62 |
| `oh release upload TAG FILE…` | Attach assets | |
| 63 |
| `oh release trust TAG` | The release's trust audit; exit 1 on a failure | |
| 64 |
| `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 | |
| 65 |
| `oh drop list [--user NAME]` | Your drops, or someone's public ones | |
| 66 |
| `oh drop view ID [-f FILE]` | A drop's files, by id or address; `-f` prints one file's content alone | |
| 67 |
| `oh drop delete ID` | Delete a drop and its history | |
| 68 |
| `oh api PATH [-X METHOD] [-d JSON]` | Any API call, JSON out | |
| 69 |
|
| 70 |
Exit codes: 0 on success, 1 when a watched run or an audit fails, 2 on an |
| 71 |
error. |
| 72 |
|
| 73 |
## Not yet |
| 74 |
|
| 75 |
- Also still to come: reviews, project columns as commands, runner management (oxygenhub#41), and shell completions. |