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
oxypushes 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]] | Open an issue; -p also puts it on the owner's project N |
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 | 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 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 runner-updates [show] | Site administrators: runners that update themselves (oxygenhub#322): where builds come from, every level's settings, test groups, each runner's policy and what it is offered, 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 |
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, project columns as commands, runner management (oxygenhub#41), and shell completions.