gh - Mirage

Mirage’s built-in gh implementation uses the vocabulary of the official cli/cli project. A repository is a tree, so mirage already reads one as files: the github mount is the read half, and ls, cat and grep are how an agent explores it. gh is the write half, plus the account-level operations a filesystem has no shape for. Licenses: The upstream cli/cli project uses the MIT License; Mirage’s independent implementation uses Apache-2.0.

Install

import { GH } from '@struktoai/mirage-core'
import { GitHubResource, Workspace } from '@struktoai/mirage-node'

const config = { token: process.env.GITHUB_TOKEN!, repo: 'acme/tools' }
const repo = await GitHubResource.create({
  token: config.token,
  owner: 'acme',
  repo: 'tools',
  ref: 'main',
})

const ws = new Workspace({ '/repo': repo })
ws.registerCli('gh', GH, config)

await ws.execute('gh repo view')

In YAML the same install rides the clis: section; see the CLI overview.

Field	Meaning
`token`	the API token, as `GH_TOKEN` carries for real gh
`repo`	the default repository, as `[HOST/]OWNER/REPO`
`branch`	the current branch, for `{branch}` in an endpoint
`baseUrl`	the API base, for GitHub Enterprise Server

repo and branch are what real gh reads off the current directory’s git remote and checkout. A workspace has neither, so the install carries them: repo answers a line that names no repository, and both feed the {owner}/{repo}/{branch} placeholders. Two installs under different head words are two accounts.

Reading is the mount, acting is the CLI

ls /repo/src              # the tree, from the mount
cat /repo/README.md       # a blob, from the mount
grep -r TODO /repo        # the mount again

gh api repos/acme/tools/contents/README.md -X PUT \
  -f message='docs: fix a typo' -f content="$(base64 -w0 new.md)" -f sha=<blob-sha>

A write through gh lands on the same repository the mount reads, but it lands by repository name rather than by any vfs path, so the mount has nothing to aim a per-path invalidation at. The spec declares which resource it serves, and the executor expires that mount’s index after the line, so the next cat or ls refetches instead of serving the pre-write bytes. Nothing is required of the caller.

Verbs

gh api       <ENDPOINT>
gh issue     list | view | create | edit | close | reopen | comment
gh pr        list | view | create | edit | merge | close | comment | diff | checks
gh repo      list | view | create | fork | rename
gh release   list | view | create
gh run       list | view | rerun
gh workflow  list | view | run

Every level answers --help; man gh, man gh issue, and man gh pr create render the same text from the same spec. list also accepts ls, and issue and pull request create also accept new.

Typed workflows

Typed read commands accept -R/--repo [HOST/]OWNER/REPO where applicable. Most also accept --json field1,field2 and -q/--jq EXPRESSION; --jq requires --json, so the selected field set stays explicit and bounded. List commands use -L/--limit and fetch as many REST pages as needed.

gh issue list --state open --label bug --limit 20
gh issue view 42 --json number,title,labels,url --jq '.url'
gh pr checks 17 --json name,bucket,state
gh repo list acme --json nameWithOwner,visibility
gh release list --json tagName,isLatest
gh run list --workflow ci.yml --json databaseId,status,conclusion

Mutations never open an editor or prompt. Supply the values on the line, through a workspace file, or through stdin with -:

gh issue create --title 'Broken build' --body-file /scratch/issue.md --label bug
gh issue edit 42 --add-label confirmed --remove-assignee octocat
gh issue comment 42 --body-file - < /scratch/comment.md
gh issue close 42

gh pr create --title 'Fix build' --head fix-build --base main --body-file /scratch/pr.md
gh pr edit 17 --base release --body 'Updated scope'
gh pr merge 17 --squash --subject 'fix: build'

gh repo create acme/tools-next --private --add-readme
gh release create v1.2.0 --title '1.2.0' --notes-file /scratch/notes.md
gh workflow run ci.yml --ref main -f mode=full
gh run rerun 123456 --failed

Body and notes files are read through the workspace dispatcher, not the host filesystem. That keeps an agent inside mirage while still supporting the official CLI’s file-oriented grammar.

repo

gh repo view                        # the install's repository
gh repo view acme/tools
gh repo view github.com/acme/tools  # the host segment is accepted
gh repo view --json nameWithOwner,defaultBranchRef,url

gh repo list acme --limit 50
gh repo create tools-next --private --description 'Next generation'

gh repo fork acme/tools
gh repo fork acme/tools --fork-name tools-patched

gh repo rename tools-v2 -R acme/tools

The default view prints a name: line, a description: line, then -- and the README, with the separator omitted when the repository has none. Use --json for a stable subset of repository fields or gh api for the complete REST object. rename takes the new name as the operand and the repository to rename on -R, which is the reverse of what the shape of the line suggests; that is upstream’s grammar, not a mirage choice. [HOST/]OWNER/REPO is parsed from the right, so the owner and the repository are the last two segments and a leading host is dropped. The host is accepted for compatibility with lines copied from real gh but does not route: every call goes to the install’s baseUrl. A second host means a second install.

api

gh api reaches every endpoint that has no typed verb, which is most of them.

gh api repos/acme/tools
gh api /user
gh api repos/acme/tools/issues -f title='Bug' -f body='Steps...'
gh api -X GET search/code -f q='repo:acme/tools TODO'
gh api repos/acme/tools/issues -F draft=false -F milestone=3
gh api repos/acme/tools/issues -F 'labels[]=bug' -F 'metadata[agent]=worker'
gh api repos/acme/tools/issues --input /scratch/issue.json --silent
gh api repos/acme/tools/issues --input - < /scratch/issue.json
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 repos/acme/tools/contents/NOTES.md -X DELETE -f message=rm -f sha=<blob-sha>
gh api graphql -f query='{viewer{login}}'

gh api 'repos/{owner}/{repo}/releases'
gh api 'repos/{owner}/{repo}/branches/{branch}'

{owner}, {repo} and {branch} expand from the install, the way real gh expands them from the current repository. Any other brace pair is left exactly as typed and reaches the wire, which is gh’s behavior too. Quote the endpoint so the shell does not eat the braces. The rules are gh’s own:

The method is GET with no fields and POST once a field is given, unless -X says otherwise.
A GET carries its fields in the query string; every other method carries them in a JSON body.
-f/--raw-field is always a string. -F/--field reads true, false, null and integers as their JSON types. A typed value beginning with @ reads that workspace file, and @- reads stdin.
Object keys such as config[enabled] and arrays such as labels[] build nested JSON rather than flat keys.
--input FILE sends that JSON document as the body and moves any fields to the query string. --input - reads stdin.
-H/--header adds or replaces request headers.
--paginate follows REST Link headers. Responses stream page by page; --slurp wraps all pages in one array.
--silent suppresses response output without suppressing the request.
A call with no fields sends no body at all, so a bare DELETE is a bare DELETE rather than an empty JSON object with a content type. Some endpoints read those differently.
The leading slash is optional.
A placeholder expands in an endpoint and in a -F value, but not in a -f one, which is the split gh’s own --help describes.
A read (GET, HEAD, OPTIONS) leaves the mount’s cache alone; only a write expires it.

JSON responses are pretty-printed by default. -q/--jq evaluates in-process and renders strings raw, or the rest of the shell can consume stdout:

gh api repos/acme/tools | jq -r .default_branch
gh api repos/acme/tools/issues --jq '.[].title'

Divergences from upstream gh

gh is virtualized, not wrapped. The intentional boundaries are:

Divergence	Reason
Only the command groups listed above are installed	`auth`, `browse`, `codespace`, `extension`, `gist`, and host checkout operations do not act on virtual workspace state
Commands never prompt, open an editor, or launch a browser	agents need deterministic, noninteractive execution
`pr create` requires explicit title, head, base, and body/body-file	there is no host checkout from which to infer or fill them
`repo fork` omits clone/remote flags; release asset upload and workflow log/watch/YAML views are absent	those require host files, checkout state, or streaming surfaces not modeled here
Typed `--json` exposes a stable REST-backed field subset	upstream’s full field sets include GraphQL-only data; use `gh api` for arbitrary REST fields
`gh api --input` accepts JSON, and pagination follows REST `Link` headers only	arbitrary byte bodies and GraphQL cursor pagination are not implemented
`gh api` pretty-prints JSON and has no `--include`/verbose/cache flags	output is optimized for agents and shell composition rather than wire debugging
A `HOST/` repository prefix is accepted but never routes	one install is one account on one host; use another install for another host

Getting Started

AI Agents

Resources

CLIs

Watch

Runtimes

gh

Install

Reading is the mount, acting is the CLI

Verbs

Typed workflows

repo

api

Divergences from upstream gh

​Install

​Reading is the mount, acting is the CLI

​Verbs

​Typed workflows

​repo

​api

​Divergences from upstream gh

Install

Reading is the mount, acting is the CLI

Verbs

Typed workflows

repo

api

Divergences from upstream gh