Skip to main content
Work with GitHub repositories, issues, pull requests, releases and Actions, or call REST and GraphQL directly. Mirage implements the supported subset below of the GitHub CLI (gh), with workspace files and configured account credentials.

Setup

Use GitHub setup for token permissions. No GitHub mount or local checkout is required.
repo and branch act like a local checkout: repo is the default repository, and branch is the current branch. branch fills {branch} in API paths, picks the pull request a pr command acts on when given none, and is the head pr create opens from. baseUrl selects an API host. An Enterprise REST base ending in /api/v3 uses /api/graphql for GraphQL; other bases use /graphql beneath that base. For YAML and multiple accounts, see registration.

SKILL.md

The SKILL.md an agent reads with gh installed.
Available commandsThese commands are registered with this shell; --help after a command or subcommand shows its usage.gh

Supported commands

Run gh <command> --help for the supported flags and operands. This list is generated from Mirage’s registered command tree.

Usage

Issues, pull requests and Actions

Use -R/--repo [HOST/]OWNER/REPO where supported to override the configured repository. Typed --jq requires --json. List commands paginate up to -L/--limit. Typed --json fields follow upstream’s for each command; use gh api for additional data.
Commands are noninteractive: supply titles, bodies, branches and confirmation flags explicitly. Body/notes files and --input files use the workspace VFS; - selects stdin. Workflow YAML is read at the selected ref. Run logs are available only after completion; --log-failed selects failed steps, -j/--job one job, whose run it names, and -a/--attempt one attempt.

Repositories

repo clone uses Mirage’s Git implementation and needs a writable destination mount. The token travels in the HTTP authorization header, not in the command line, output or .git/config, and only to the configured GitHub origin: https://github.com for GitHub’s own API (base_url unset or https://api.github.com), else the scheme, host and port base_url names. Git clones any other URL on the line without it. Fork clones do not add an upstream remote. repo rename takes the new name as its operand; -R selects the repository to rename. repo edit changes only the named settings, and bare boolean settings can be disabled with =false. Deletion needs both a repository name and --yes. Repository URLs and [HOST/]OWNER/REPO are accepted, but the host must match the configured API host; use a separate install for another host.

REST and GraphQL API

Quote endpoints containing {owner}, {repo} or {branch}. These expand from config in endpoints and -F values, but not -f values. Other brace pairs remain unchanged. A leading endpoint slash is optional. Unfiltered output preserves the server’s response bytes. Typed --json output is compact JSON followed by a newline. --jq prints strings raw, null as an empty line, and objects/arrays as compact JSON. A jq error exits 1 and can leave earlier output on stdout. Connection failures and HTTP 500 responses are not retried.

Behavior

A GitHub VFS can expose the same remote repository as files, independently of the CLI. The configured repo and branch supply context that a host gh would infer from a checkout. CLI service writes invalidate mounted caches; read API methods leave them intact. The listed subset and differences define Mirage’s compatibility scope.

License

Adapted code from go-gh, Go, gojq, Cobra and pflag keeps its license in licenses/third_party/. See compatibility and licenses.