gh - Mirage

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.

from mirage import Workspace
from mirage.commands.cli.builtin.gh import GH
from mirage.core.github.config import GhConfig

ws = Workspace({})
ws.register_cli("gh", GH, GhConfig(token="ghp_...", repo="acme/tools"))

repo is the default repository and branch the current branch, as a checkout would give them to a host gh: branch fills the API’s {branch} placeholder, names the pull request a pr command acts on when given none, and is the head pr create opens from. base_url (baseUrl in TypeScript) 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.

Supported commands

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

Command	Description
`gh auth status`	Check the configured token
`gh auth token`	Token display is unavailable in Mirage
`gh help`	Help about any command
`gh version`	Show the Mirage GitHub CLI implementation version. Aliases: `--version`.
`gh api`	Make an authenticated GitHub API request
`gh issue list`	List issues. Aliases: `ls`.
`gh issue view`	View an issue
`gh issue create`	Create an issue. Aliases: `new`.
`gh issue edit`	Edit an issue
`gh issue close`	Close an issue
`gh issue reopen`	Reopen an issue
`gh issue comment`	Add a comment to an issue
`gh issue delete`	Delete issue
`gh issue lock`	Lock issue conversation
`gh issue pin`	Pin an issue to a repository
`gh issue status`	Show status of relevant issues
`gh issue transfer`	Transfer issue to another repository
`gh issue unlock`	Unlock issue conversation
`gh issue unpin`	Unpin an issue from a repository
`gh pr list`	List pull requests. Aliases: `ls`.
`gh pr view`	View a pull request
`gh pr create`	Create a pull request. Aliases: `new`.
`gh pr edit`	Edit a pull request
`gh pr merge`	Merge a pull request
`gh pr close`	Close a pull request
`gh pr reopen`	Reopen a pull request
`gh pr comment`	Add a comment to a pull request
`gh pr diff`	View changes in a pull request
`gh pr checks`	Show CI checks for a pull request
`gh pr lock`	Lock pull request conversation
`gh pr ready`	Mark a pull request as ready for review
`gh pr revert`	Revert a pull request
`gh pr review`	Add a review to a pull request
`gh pr status`	Show status of relevant pull requests
`gh pr unlock`	Unlock pull request conversation
`gh pr update-branch`	Update a pull request branch with latest changes of the base branch
`gh repo list`	List repositories. Aliases: `ls`.
`gh repo clone`	Clone a repository locally
`gh repo view`	View a repository
`gh repo create`	Create a repository
`gh repo fork`	Create a fork of a repository
`gh repo rename`	Rename a repository
`gh repo edit`	Edit repository settings
`gh repo delete`	Delete a repository
`gh repo archive`	Archive a GitHub repository
`gh repo sync`	Sync destination repository from source repository
`gh repo unarchive`	Unarchive a GitHub repository
`gh repo autolink create`	Create a new autolink reference for a repository. Aliases: `new`.
`gh repo autolink delete`	Delete an autolink reference for a repository
`gh repo autolink list`	Gets all autolink references that are configured for a repository. Aliases: `ls`.
`gh repo autolink view`	View an autolink reference for a repository
`gh repo deploy-key add`	Add a deploy key to a GitHub repository
`gh repo deploy-key delete`	Delete a deploy key from a GitHub repository
`gh repo deploy-key list`	List deploy keys in a GitHub repository. Aliases: `ls`.
`gh repo gitignore list`	List available repository gitignore templates. Aliases: `ls`.
`gh repo gitignore view`	View an available repository `.gitignore` template
`gh repo license list`	List common repository licenses. Aliases: `ls`.
`gh repo license view`	View a specific repository license by license key or SPDX ID
`gh release list`	List releases. Aliases: `ls`.
`gh release view`	View a release
`gh release create`	Create a release
`gh release delete`	Delete a release
`gh release delete-asset`	Delete an asset from a release
`gh release edit`	Edit a release
`gh run list`	List workflow runs. Aliases: `ls`.
`gh run view`	View a workflow run
`gh run rerun`	Rerun a workflow run
`gh run cancel`	Cancel a workflow run
`gh run delete`	Delete a workflow run
`gh workflow list`	List workflows. Aliases: `ls`.
`gh workflow view`	View a workflow
`gh workflow run`	Run a workflow
`gh workflow disable`	Disable a workflow, preventing it from running or showing up when listing workflows
`gh workflow enable`	Enable a workflow, allowing it to be run and show up when listing workflows
`gh search issues`	Search for issues
`gh search prs`	Search for prs
`gh search repos`	Search for repos
`gh search code`	Search for code
`gh search commits`	Search for commits
`gh cache delete`	Delete GitHub Actions caches
`gh cache list`	List GitHub Actions caches. Aliases: `ls`.
`gh gist create`	Create a new GitHub gist with given contents. Aliases: `new`.
`gh gist delete`	Delete a GitHub gist
`gh gist edit`	Edit one of your gists
`gh gist list`	List gists from your user account. Aliases: `ls`.
`gh gist rename`	Rename a file in the given gist ID / URL
`gh gist view`	View the given gist or select from recent gists
`gh gist clone`	Clone a GitHub gist locally
`gh label clone`	Clones labels from a source repository to a destination repository on GitHub
`gh label create`	Create a new label on GitHub, or update an existing one with `--force`
`gh label delete`	Delete a label from a repository
`gh label edit`	Update a label on GitHub
`gh label list`	Display labels in a GitHub repository. Aliases: `ls`.
`gh org list`	List organizations for the authenticated user. Aliases: `ls`.
`gh ruleset check`	View information about GitHub rules that apply to a given branch
`gh ruleset list`	List GitHub rulesets for a repository or organization. Aliases: `ls`.
`gh ruleset view`	View information about a GitHub ruleset
`gh secret delete`	Delete a secret on one of the following levels:. Aliases: `remove`.
`gh secret list`	List secrets on one of the following levels:. Aliases: `ls`.
`gh variable delete`	Delete a variable on one of the following levels:. Aliases: `remove`.
`gh variable get`	Get a variable on one of the following levels:
`gh variable list`	List variables on one of the following levels:. Aliases: `ls`.
`gh variable set`	Set a value for a variable on one of the following levels:

Issues, pull requests and Actions

gh auth status
gh issue list --state open --label bug --limit 20
gh issue view 42 --json number,title,labels,url --jq '.url'
gh pr view 17 --json files,commits,reviews --jq '.files[].path'
gh pr checks 17 --json name,bucket,state
gh run list --workflow ci.yml --json databaseId,status,conclusion
gh run view 123456 --log-failed
gh workflow view ci.yml --yaml --ref release

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, except jobs on run view; use gh api for additional data.

gh issue create --title 'Broken build' --body-file /work/issue.md --label bug
gh issue comment 42 --body-file - < /work/comment.md
gh issue edit 42 --add-label confirmed --remove-assignee octocat
gh pr create --title 'Fix build' --head fix-build --base main --body-file /work/pr.md
gh pr merge 17 --squash --subject 'Fix build'
gh release create v1.2.0 --title '1.2.0' --notes-file /work/notes.md
gh workflow run ci.yml --ref main -f mode=full
gh run rerun 123456 --failed

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.

Repositories

gh repo view --json nameWithOwner,defaultBranchRef,url
gh repo list acme --limit 50
gh repo clone acme/tools /work/tools -- --branch dev
gh repo create acme/tools-next --private --add-readme
gh repo fork acme/tools --fork-name tools-patched
gh repo rename tools-v2 -R acme/tools
gh repo edit acme/tools --enable-wiki=false --add-topic cli,agents
gh repo edit acme/tools --visibility private --accept-visibility-change-consequences
gh repo delete acme/tools-old --yes

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

gh api /user
gh api 'repos/{owner}/{repo}/issues' -f title='Bug' -f body='Steps to reproduce'
gh api repos/acme/tools/issues -F 'labels[]=bug' -F 'metadata[agent]=worker'
gh api repos/acme/tools/issues --input /work/issue.json --silent
gh api 'repos/acme/tools/issues?per_page=50' --paginate --slurp
gh api repos/acme/tools/pulls/17 -H 'Accept: application/vnd.github.v3.diff'
gh api graphql -f query='{viewer{login}}'

Option or input	Behavior
No fields	GET by default; no request body
`-f` / `--raw-field`	String field; supplying fields selects POST unless `-X` overrides it
`-F` / `--field`	Typed booleans, null and integers; `@FILE` reads a workspace file and `@-` reads stdin
`-X` / `--method`	Explicit method; GET fields become query parameters, other methods use JSON
`key[nested]`, `key[]`	Nested objects and arrays
`--input FILE`	Request body from a file or `-`, sent as raw bytes; additional fields move to the query string
`-H` / `--header`	Add or replace a header
`--paginate`	Follow REST Link headers, joining array pages, or a GraphQL query’s `endCursor`
`--slurp`	Wrap pages in an array; cannot be combined with `--jq`
`-i` / `--include`	Print status and headers for each response, including failures
`--silent`	Suppress the response body; `--include` still prints headers
`-q` / `--jq`	Filter API output in process; unlike typed commands, needs no `--json`

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.

VFS and limits

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.

Boundary	Mirage behavior
Authentication	`auth status` checks the token; `auth token` refuses to print it. No login/logout flow.
Interactive tools	No editor, browser, extension manager, codespace or host-checkout workflow.
Pull-request creation	Requires a title and a body or body file. `--head` defaults to `branch` and `--base` to the repository’s default branch.
Forks	`--clone` is refused; `--remote` without a repository is refused.
Repository operations	No `repo set-default`. `repo sync` acts on a repository on GitHub, never a local checkout.
Release assets and live runs	`release upload`, `release download`, `run watch` and `run download` are absent.
Raw API	REST pagination only; no verbose, cache, hostname, preview or template flags.
Help topics	`environment` and `exit-codes` are supported, alongside command help.
HTTP display	`--include` prints HTTP/1.1 rather than upstream’s HTTP/2.0 display.
jq compatibility	Uses jq rather than gojq: builtin error wording and floating-point edge cases can differ. Numbers above 2^53 can lose precision; NaN, infinities and negative zero follow jq’s values.

The original GitHub CLI uses the MIT license. Mirage’s command implementation is Apache-2.0; the listed subset and differences define its compatibility scope. See compatibility and licenses.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

gh