gho — the githosted CLI

gho is the official command-line client for githosted. Single static binary, OS-native keychain storage, browser OAuth. After one gho auth login, every git clone / fetch / push against api.githosted.dev works without prompting.

Install

macOS / Linux

curl -fsSL https://githosted.sh | sh

The installer fetches the latest release for your OS / arch combo, verifies the SHA-256 against the published checksums.txt, and drops both gho and git-credential-githosted in /usr/local/bin. Override the target with INSTALL_DIR=$HOME/.local/bin or pin a version with --version v0.1.0. A checksum mismatch aborts the install non-zero — the binaries are never written to disk.

Windows

irm https://githosted.sh/install.ps1 | iex

Drops the binaries in %LOCALAPPDATA%\gho\bin and adds that directory to your user PATH. Re-open the shell for the PATH change to take effect.

Verify the install script (paranoid mode ;))

The one-liner above relies on TLS to authenticate githosted.sh. If you’d rather read the script before running it:

# 1. Pull the script.
curl -fsSL -o install.sh https://githosted.sh

# 2. Read it.
less install.sh

# 3. Run it.
sh install.sh

Same shape on Windows for install.ps1:

Invoke-WebRequest -Uri https://githosted.sh/install.ps1 -OutFile install.ps1
notepad install.ps1
.\install.ps1

The script itself then verifies SHA-256 of every binary it downloads against a checksums.txt published with the release — see What gets verified below — so the chain is:

install script ← TLS to githosted.sh authenticates it.
release tarball ← SHA-256 against the release’s checksums.txt.
binaries ← extracted from the verified tarball.

A failure at any layer aborts the install non-zero before anything lands on disk.

gho auth login

A browser window opens, you authorize the device, the token is saved to your OS keychain, and gho writes git’s credential helper config for api.githosted.dev automatically. Subsequent git operations against the host are silent.

git clone https://githosted.dev/myws/myrepo.git
# (no prompt, no token in the URL)

gho auth logout revokes the token server-side, clears the keychain, and unsets the credential helper config — fully clean.

Commands

Command	Notes
`gho auth login` / `logout` / `status`	OAuth login, forget the token, verify it’s still good. Defaults to a loopback-redirect browser flow (RFC 8252 §7.3); falls back to the device flow under SSH or no DISPLAY. Force either with `--device` / `--loopback`.
`gho whoami`	Print the authenticated user.
`gho repos ls` / `gho repos create <name>` / `gho repos delete <repo>`	List, create, and delete repos. Delete is irreversible.
`gho tokens ls` / `gho tokens create <name>` / `gho tokens revoke <id>`	Workspace token management.
`gho ls <repo> [<path>]`	List files at path.
`gho cat <repo> <path>`	Print file contents to stdout.
`gho log <repo>`	Recent commits.
`gho diff <repo> <base> <head>`	Diff between refs.
`gho write <repo> <path> -m <msg>`	Commit a file (content from `--file` or stdin).
`gho rm <repo> <path> -m <msg>`	Commit a deletion.
`gho branches ls <repo>`	List branches with tip SHAs; default branch marked with `*`.
`gho clone <ws/repo>`	`git clone` wrapper using the configured credential helper.
`gho auth git-credential <op>`	Git credential-helper bridge — wired automatically by `gho auth login`.

Run gho <command> --help for full options.

Configuration

Knob	Default	Notes
`--api <URL>` / `GITHOSTED_API_URL`	`https://api.githosted.dev`	Override for self-hosted or dev stacks.
Token storage	OS keychain	Keychain on macOS, Credential Manager on Windows, libsecret on Linux. One entry per API host.
DCR cache	`~/.config/githosted/<host>.json`	First login registers the CLI as a public OAuth client; subsequent logins reuse the cached `client_id`.

What gets verified

Three layers, every install:

Layer	How	Failure mode
`install.sh` / `install.ps1` authenticity	TLS to `githosted.sh`. Paranoid mode cross-checks against `raw.githubusercontent.com`.	curl/Invoke-WebRequest exits non-zero on cert error; the script never runs.
Tarball / zip authenticity	TLS to `github.com` (GitHub cert) on every download inside the install script.	curl/Invoke-WebRequest exits non-zero on cert error; install aborts before extraction.
Tarball / zip integrity	SHA-256 against `checksums.txt` published in the same GitHub release.	`checksum mismatch (expected X, got Y)` → exit 1, binary never written to disk. Missing checksum entry, missing hash tool, and download failures all also abort.

Both install scripts fail-closed on any verification gap rather than silently continuing.

Just the credential helper, no full CLI?

If you only want git clone against githosted to Just Work and don’t need the rest of the CLI surface, install git-credential-githosted on its own — same binary that gho ships, narrower install.

Status

v0 covers the launch-essential CLI surface — auth, repos, tokens, files, log/diff, branches, and git clone integration. A reflection-driven dynamic command tree (gho rpc <Service> <Method>) lands later as a catch-all for new RPCs the hand-written commands haven’t picked up yet.