A better GitHub CLI that extends the official gh CLI.
- What It Does
- How It Works
- Features
- Install
- Configuration
- Profile Management
- Commands
- PR Workflow
- Templates
- Output Format
- Playbooks
- Development Checks
- Repository Structure
- Contributing
- Security
- Support
- License
ghg is not a replacement for gh. It is a companion that fills the gaps in the official GitHub CLI where GitHub has chosen not to ship features that power users need daily.
The output is not a wrapper. It is a superset.
ghg layers its commands on top of the GitHub REST API and local Git operations. Each command is self-contained — it resolves configuration, validates inputs, makes the minimal necessary API calls, and returns results in human-readable form or structured JSON.
The architecture is flat and explicit:
| Layer | Responsibility |
|---|---|
cli |
Commander program setup, global error boundary, ASCII banner |
commands |
Self-registering subcommand modules with argument parsing |
services |
Business logic — validation, orchestration, output formatting |
api |
GitHub REST API client with auth, retry, and error mapping |
core |
Config resolution, Git helpers, file I/O, logging, errors |
types |
Shared TypeScript interfaces and normalization helpers |
tui |
Full-screen terminal UI runtime, layout engine, renderer, and interactive command operations |
Every command reads from src/core/config.ts, which resolves values in this order: environment variables, active profile credentials, fallback defaults. All HTTP calls go through src/api/client.ts — no direct fetch anywhere else.
- Label Management — list, pull, push, and prune repository labels with built-in templates
- Notifications — list, read, and dismiss GitHub notifications from the terminal
- Activity & Mentions — composite views of assigned issues, review requests, and @mentions
- PR Lifecycle — cleanup merged branches, push back to forks, manage stacked PR chains
- Authentication — login with token validation, logout, view auth status and scopes, list and switch profiles
- Bulk Repository Governance — inspect, govern, label, retire, and report across repo sets
- Repository Insights — view traffic data, contributors, commit activity, code frequency, referrers, and participation metrics
- Code Review — comment on lines, list threads, resolve threads, suggest changes, and apply suggestions
- Workflow Management — list, inspect, dispatch, enable, disable, validate, and preview GitHub Actions workflows
- Cache Management — list, delete, inspect, and download GitHub Actions cache metadata
- Gist Management — list, view, create, edit, delete, and clone gists
- Workflow Run Management — list, inspect, cancel, rerun, delete, watch, download, and debug workflow runs
- Proxy Passthrough — pass any unrecognized command directly to the
ghCLI - Structured JSON Output — every command supports machine-parseable JSON via
--json - Terminal Themes — built-in dark, light, and auto color themes via
--theme - Full Terminal UI — browse and run the full
ghgworkflow surface fromghg tui - Release Management — manage releases and assets alongside changelog, version, signature, notes, and draft automation
- Milestone Management — track sprint progress with create, list, close, and progress commands
- Project Boards — render an ASCII kanban board for any GitHub Project v2
- Project Management — create, edit, close, delete, link, and populate Projects v2
- Ruleset Management — validate and manage repository or organization rulesets
- Cross-Repository Status — aggregate assigned/authored work, reviews, and mentions
- API Passthrough — authenticated REST requests with pagination and jq filtering
- Merge Queues — inspect queue health and history, then enqueue or dequeue pull requests
- Issue Management — create, triage, update, transfer, and organize issues and sub-issues
- Security & Compliance — audit enterprise and organization activity, scan repositories for leaked secrets, triage Dependabot and secret scanning alerts, and run compliance checks across repository hygiene, branch protection, and rulesets
- GitHub Discussions — list, view, create, comment on, close, and manage discussion categories entirely from the terminal
- Variables & Environments — list, set, and delete repository, environment, and organization variables; create environments and manage protection rules
- Secrets — list, set, and delete encrypted repository, environment, and organization secrets with libsodium public-key encryption
- Organization & Team Management — list organization members, invite and remove users, manage teams and team membership, invite collaborators and grant team access to repositories
- GitHub Pages & Wiki — configure and deploy branch-based Pages sites, inspect build status, and manage wiki pages from the terminal
- Branch & Tag Protection — protect and unprotect branches, manage tag protection rules
- Webhook Management — list, create, edit, delete, test webhooks and inspect deliveries
- Fork Management — sync, compare, list, and create repository forks
- Deployment Tracking — list, view, create deployments and manage deployment statuses
- Actions Log Streaming — live stream workflow run logs with filtering and tail support
- Issue Types — list available issue types per repository
- Dependency Graph — list, inspect, and review repository dependencies via SBOM
- Advisory Database — query GitHub Advisory Database by ecosystem and severity
- CodeQL Alerts — list, view, and dismiss code scanning alerts
- Workspaces — define named workspaces and run commands across multiple repositories
- Multi-Repo Operations — syncall, statusall, branch stale detection, and sweep
- Actions Cost Analytics — usage, cost, top-spenders, and export for billing visibility
- Code Search & Navigation — search code, find definitions and references, view files at refs, and blame with PR context
- Template Discovery — list and preview issue and PR templates
- Label Bulk & Sync — create labels from JSON/YAML files, sync labels between repositories
- Package & Container Registry — list, view, version, delete, and restore GHCR and package versions
- Self-Hosted Runners — list, view, check status, remove, and inspect labels for org and repo runners
- Security Advisory Lifecycle — create, publish, close, and request CVEs for repo-scoped advisories
- Extension Management — install, upgrade, remove, and scaffold locally installed CLI extensions
- Codespace Management — list, view, create, start, stop, and delete GitHub Codespaces
- Browser Integration — open repos, issues, PRs, actions, and settings in the browser
- Artifact Attestations — list and verify SLSA/Sigstore provenance for artifacts
- SSH Key Management — list, add, and delete user SSH keys
- GPG Key Management — list, add, and delete user GPG keys
- Command Aliases — create, list, delete, and import persistent command shortcuts
- Shell Completion — generate completion scripts for bash, zsh, fish, and PowerShell
- Preview Utilities — preview interactive prompt types from the terminal
- License Discovery — list available open-source licenses and view license templates
- Copilot CLI Integration — detect and run GitHub Copilot CLI from ghg
- Agent Task Management — create, list, and view GitHub agent tasks
- Agent Skill Management — install, list, preview, publish, search, and update agent skills
npm install -g @airscript/ghitgudPublished package is available at:
- npm: https://www.npmjs.com/package/@airscript/ghitgud
- GitHub Releases: https://github.com/airscripts/ghitgud/releases
For local development:
pnpm install # Install dependencies.
pnpm build # Build single CJS bundle with Vite.
pnpm start # Run the CLI locally.The package installs both
ghitgudandghgcommands. This documentation uses the compactghgform.
Authenticate with a GitHub personal access token:
ghg auth login --token <your-token>Check your authentication status and token scopes:
ghg auth status
ghg auth tokenSwitch between profiles for multi-account workflows:
ghg auth list
ghg auth switch workCredentials are stored in ~/.config/ghitgud/credentials.json.
Use a classic personal access token (PAT). Fine-grained PATs are repository-scoped and will fail with 403 errors on user-scoped endpoints such as notifications, activity, and mentions.
Create a token at: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
These scopes are needed for core functionality:
| Scope | Why |
|---|---|
repo |
Full repository access (issues, PRs, code, wiki) |
read:org |
List org members, teams, audit logs |
read:user |
Activity feed, profile detection |
notifications |
List, read, and dismiss notifications |
Some commands require additional scopes. Add these only if you use the corresponding features:
| Scope | Commands |
|---|---|
admin:org |
org invite, org remove, team create, team add/remove |
read:project |
project board |
delete_repo |
repos retire (archives and deletes) |
admin:public_key |
Included in some token defaults; not directly used by ghg |
When running in CI pipelines or other non-interactive contexts, set the CI environment variable:
CI=true ghg team list --org myorgIn non-interactive mode, commands that normally prompt for missing required arguments (such as org name, team name, username) will throw an error instead of opening an interactive prompt. This ensures commands fail fast with clear messages in automation.
You can also use --json mode, which implies non-interactive behavior:
ghg team list --org myorg --jsonFor commands that need a repository, ghg resolves the target from the --repo flag or the current git remote. If neither is available, the command throws an error.
Wiki commands (ghg wiki list, ghg wiki view, ghg wiki create, ghg wiki edit, ghg wiki delete) require the repository's wiki to be initialized first. If the wiki has never been used, you will see:
ERROR The wiki does not exist or has not been initialized for this repository.
To initialize a wiki, visit https://github.com/<owner>/<repo>/wiki and click "Create the first page", or push a Home.md file to the wiki Git endpoint:
git clone https://github.com/<owner>/<repo>.wiki.git /tmp/wiki-init
cd /tmp/wiki-init
echo "# Home" > Home.md
git add Home.md && git commit -m "Initialize wiki"
git pushghg supports multi-account workflows through named profiles under ghg auth.
# Login with a token and profile name.
ghg auth login --token ghp_xxx --profile work
# List all profiles.
ghg auth list
# Switch the active profile.
ghg auth switch work
# Auto-detect profile from current repository.
ghg auth detectWhen a profile is active, all API calls use that profile's token. The detect command reads the current repository's remote URL and matches it against profile associations.
ghg tui
ghg notifications list
ghg notifications read <id>
ghg notifications done <id>tuilaunches the full-screen terminal UI.listlists unread notifications.readmarks a notification as read.donemarks a notification as done.
ghg activity
ghg mentionsactivityshows assigned issues, review requests, and mentions.mentionsshows recent @mentions of you.
ghg labels list
ghg labels pull
ghg labels push
ghg labels prunelistlists all repository labels.pullpulls labels from the repository to local config.pushpushes local labels to the repository.prunedeletes all labels from the repository.
ghg repos inspect --org airscripts
ghg repos govern --org airscripts --ruleset ./ruleset.json
ghg repos label --org airscripts -t conventional
ghg repos retire --org airscripts --months 12
ghg repos report --org airscripts --since 30dinspectchecks for README, LICENSE, SECURITY.md, and CODEOWNERS.governapplies repository rulesets across the selected repositories.labelsyncs label templates or metadata across many repositories.retirefinds and optionally archives inactive repositories.reportsummarizes repository health and velocity.
ghg insights traffic --repo owner/repo
ghg insights contributors --repo owner/repo
ghg insights commits --repo owner/repo
ghg insights frequency --repo owner/repo
ghg insights popularity --repo owner/repo
ghg insights participation --repo owner/repotrafficshows repository traffic data.contributorsshows top contributors.commitsshows commit activity.frequencyshows code frequency.popularityshows referrers and popular paths.participationshows participation stats.
ghg review comment <pr> --file src/main.ts --line 10 --body "Consider a constant here."
ghg review threads <pr>
ghg review resolve <thread-id> <pr>
ghg review suggest <pr> --file src/main.ts --line 10 --replace "const x = 1;"
ghg review apply <pr> --pushcommentcreates a line review comment.threadslists review threads for a pull request.resolvemarks a review thread as resolved.suggestcreates a single-line suggestion.applyapplies review suggestions locally.
ghg cache inspect <key> --repo owner/repo
ghg cache download <key> --repo owner/repo --output-dir ./cache-debug
ghg cache list --key node --limit 20 --repo owner/repo
ghg cache delete <key> --all --yes --repo owner/repoinspectinspects GitHub Actions cache metadata.downloaddownloads cache-related debug artifacts.listlists cache metadata with optional key filtering.deleteremoves one exact cache or all prefix matches.
ghg run debug <run-id> --repo owner/repo --output-dir ./run-debug
ghg run watch 12345678 --repo owner/repo
ghg run watch --follow --tail --filter "test"debugfetches logs, artifacts, and annotations for a workflow run.watchstreams logs for a workflow run with optional tail, filter, and follow modes.
ghg workflow validate [path]
ghg workflow preview [path]
ghg workflow list [--all] --repo owner/repo
ghg workflow view <name|id> --repo owner/repo
ghg workflow run <name|id> --ref main --field env=test --repo owner/repo
ghg workflow enable <name|id> --repo owner/repo
ghg workflow disable <name|id> --repo owner/repovalidatevalidates GitHub Actions workflow files.previewpreviews workflow structure.list,view,run,enable, anddisablemanage repository workflows.
ghg gist list [--public] [--limit 30]
ghg gist view <id> [--raw] [--file <name>]
ghg gist create <files...> [--description <text>] [--public]
ghg gist edit <id> [--add <file>] [--remove <name>]
ghg gist delete <id> --yes
ghg gist clone <id> [--dir <dir>]ghg auth login --token <token>
ghg auth login --token <token> --profile <name>
ghg auth logout
ghg auth status
ghg auth token [--raw]
ghg auth list
ghg auth switch <name>
ghg auth detectloginauthenticates with a GitHub token, validates it, and stores credentials.logoutremoves stored credentials from the active profile.statusshows the authenticated user, token scopes, and active profile.tokenprints the current token (masked by default,--rawfor full).listlists all configured profiles.switchactivates a profile after validating its token.detectauto-detects the profile for the current repository.
ghg proxy <args>proxypasses any arguments through to the officialghCLI.
ghg tui
ghg ping
ghg versiontuilaunches the full-screen terminal UI.pingchecks if the CLI is working.versionshows the current version number.
ghg milestone create --title "v2.10.0" --due 2026-06-30
ghg milestone list --status open
ghg milestone close "v2.10.0"
ghg milestone progress "v2.10.0"createcreates a repository milestone with a due date.listlists open or closed milestones.closecloses a milestone by title.progressshows milestone completion percentage.
ghg project board <id> --owner <owner>
ghg project list --owner <owner>
ghg project create --title "Roadmap" --owner <owner>
ghg project item-add <id> --issue 42 --repo owner/repo
ghg project field-list <id> --owner <owner>
ghg project link <id> --repo owner/repoboardrenders an ASCII kanban board for a GitHub Project v2.- Lifecycle commands manage project metadata, items, fields, and repository links.
ghg ruleset list --repo owner/repo
ghg ruleset create --file ruleset.yml --org my-org
ghg ruleset check main --repo owner/repo
ghg status --org my-org --exclude owner/archive
ghg api /user/repos --paginate --jq 'map(.full_name)'
ghg queue status --repo owner/repo --branch main
ghg queue add 42 --repo owner/repo
ghg queue history --repo owner/repo --limit 20- Ruleset commands support repository and organization targets; branch checks are repository-specific.
- Status aggregates assigned issues, authored issues/PRs, review requests, and mentions.
- API passthrough supports standard REST methods, string fields, array pagination, jq, and silent mode.
- Queue commands use the repository default branch unless
--branchis supplied.
ghg issue create --title "Bug report" --label bug --type Bug
ghg issue list --state open --limit 10
ghg issue view 42
ghg issue edit 42 --title "Updated title"
ghg issue close 42
ghg issue reopen 42
ghg issue comment 42 --body "Investigation complete."
ghg issue lock 42
ghg issue pin 42
ghg issue transfer 42 --repo owner/target
ghg issue status
ghg issue subtasks <issue>
ghg issue subtasks <issue> --create --title "Sub-task"
ghg issue subtasks <issue> --link <sub-issue>
ghg issue parent <child> --parent <parent>create,list,view, andeditcover the basic issue lifecycle.close,reopen,comment,lock,unlock,pin, andunpinmanage issue state and discussion.deletepermanently removes an issue after confirmation.transfermoves an issue to another repository.statussummarizes assigned, created, and mentioned open issues.subtaskslists sub-issues for a parent issue.subtasks --createcreates and links a new sub-issue.subtasks --linklinks an existing issue as a sub-issue.parentlinks an existing issue to a parent issue.
ghg issue type list --repo owner/repotype listlists available issue types for the repository.
ghg audit --org <org>
ghg audit --enterprise <slug> --actor <actor> --action <action>
ghg compliance check --org <org>
ghg dependabot list --org <org> --severity critical
ghg dependabot dismiss <alert> --repo owner/repo --reason fix_started --yes
ghg leaks scan --limit 50
ghg leaks alerts --org <org> --state openauditqueries organization or enterprise audit logs.compliance checkscores repository compliance posture.dependabot listinspects Dependabot alerts.dependabot dismissdismisses a Dependabot alert.leaks scanruns a local scan for leaked secrets.leaks alertslists secret scanning alerts.
ghg discussion list
ghg discussion list --category "Q&A"
ghg discussion view <number>
ghg discussion create --title "Hello" --category "General" --body "Text"
ghg discussion comment <number> --body "Nice post!"
ghg discussion close <number>
ghg discussion categorieslistlists discussions, optionally by category.viewviews a discussion and its comments.createcreates a new discussion.commentadds a comment to a discussion.closecloses a discussion.categorieslists available discussion categories.
ghg variable list
ghg variable list --env <name>
ghg variable list --org <org>
ghg variable set --name <key> --value <val>
ghg variable set --name <key> --value <val> --env <name>
ghg variable set --name <key> --value <val> --org <org>
ghg variable delete --name <key>listlists repository, environment, or organization variables.setcreates or updates a variable.deleteremoves a variable.
ghg environment list
ghg environment create --name <name> [--wait-timer <seconds>]
ghg environment protection list --env <name>
ghg environment protection add --env <name> --type <type> --value <json>
ghg environment protection remove --env <name> --rule-id <id>listlists configured environments.createcreates an environment with an optional wait timer.protection listlists protection rules for an environment.protection addadds a protection rule.protection removeremoves a protection rule.
ghg secret list
ghg secret list --env <name>
ghg secret list --org <org>
ghg secret set --name <key> --value <val>
ghg secret set --name <key> --value <val> --env <name>
ghg secret set --name <key> --value <val> --org <org>
ghg secret delete --name <key>listlists repository, environment, or organization secrets.setcreates or updates an encrypted secret.deleteremoves a secret.
ghg pages status
ghg pages deploy --source main
ghg pages deploy --source main --path /docs
ghg pages deploy --source main --build-type workflow
ghg pages unpublish --yesstatusshows the Pages configuration and latest build.deploycreates or updates a branch source and requests a build. Use--build-typeto selectlegacy(default) orworkflow(GitHub Actions).unpublishremoves the Pages site after confirmation.
ghg wiki list
ghg wiki view Home
ghg wiki edit "Getting Started" --file ./getting-started.md
ghg wiki create FAQ --file ./faq.md
ghg wiki delete OldPagelistlists wiki pages and their source formats.viewprints a page's source.editreplaces, commits, and publishes an existing page.createcommits and publishes a new page.deleteremoves a wiki page permanently.
ghg branch protect main --required-reviews 2 --dismiss-stale --repo owner/repo
ghg branch unprotect main --repo owner/repo
ghg branch protection --repo owner/repo
ghg branch tag-protect "v*"
ghg branch tag-unprotect "v*"
ghg branch stale --days 30 --merged
ghg branch sweep --pattern "feature/*" --dryprotectsets branch protection with optional required checks, reviews, and stale review dismissal.unprotectremoves branch protection.protectionlists all branch and tag protection rules.tag-protectcreates a tag protection rule.tag-unprotectremoves a tag protection rule.stalelists local branches older than N days, optionally filtered to merged branches.sweepbulk deletes local branches matching a pattern, with dry-run support.
ghg deps list --repo owner/repo
ghg deps direct --repo owner/repo
ghg deps review --base main --head feature --repo owner/repolistshows the dependency graph (SBOM) for a repository.directshows direct dependencies only.reviewcompares dependencies between two refs.
ghg advisory list
ghg advisory list --ecosystem npm --severity high
ghg advisory list --repo owner/repo --state published
ghg advisory view GHSA-xxxx-xxxx-xxxx
ghg advisory view GHSA-xxxx --repo owner/repo
ghg advisory create --repo owner/repo --summary "Vulnerability" --description "Details" --severity high
ghg advisory publish GHSA-xxxx --repo owner/repo
ghg advisory close GHSA-xxxx --repo owner/repo
ghg advisory cve-request GHSA-xxxx --repo owner/repolistqueries advisories globally or scoped to a repo, filterable by ecosystem, severity, and state.viewshows detailed advisory information.createcreates a draft repository security advisory.publishpublishes a draft advisory.closecloses an advisory.cve-requestrequests a CVE for a published advisory.
ghg codeql list --repo owner/repo --state open --severity high
ghg codeql view 1 --repo owner/repo
ghg codeql dismiss 1 --reason "false positive" --repo owner/repolistlists CodeQL code scanning alerts with state and severity filters.viewshows detailed alert information.dismissdismisses an alert with a reason (false positive, won't fix, used in tests).
ghg workspace define --name my-team --repos owner/repo1 owner/repo2
ghg workspace list
ghg workspace run --name my-team --command "issue list"
ghg repo syncall
ghg repo statusalldefinecreates or updates a named workspace with a list of repositories.listshows all defined workspaces.runexecutes a command across all repositories in a workspace.syncallpulls latest changes for all local git repositories.statusallshows dirty/clean/ahead/behind status for all local repositories.
ghg actions usage --repo owner/repo
ghg actions cost --org myorg
ghg actions top-spenders --repo owner/repo --limit 5
ghg actions export --repo owner/repo --format csvusageshows Actions minutes and estimated cost per workflow.costshows cost summary for a repository or organization.top-spendersranks workflows by billable minutes.exportoutputs usage data as JSON or CSV.
ghg code search <query> --repo owner/repo --language typescript
ghg code definitions <symbol> --repo owner/repo
ghg code references <symbol> --repo owner/repo
ghg code file <path> --repo owner/repo --ref main
ghg code blame <path> --repo owner/reposearchsearches code across repositories.definitionsfinds symbol definitions.referencesfinds symbol references.fileviews a file at a specific ref.blameshows commit history with PR context.
ghg template list --repo owner/repo
ghg template show bug_report.yml --repo owner/repolistdiscovers issue and PR templates in a repository.showrenders a specific template with frontmatter metadata.
ghg labels bulk --file labels.json --repo owner/repo
ghg labels sync --source owner/source --repo owner/targetbulkcreates labels from a JSON or YAML file.syncsyncs labels from a source repository to a target.
ghg package list --repo owner/repo --type npm
ghg package view <name> --repo owner/repo --type npm
ghg package versions <name> --repo owner/repo --type npm
ghg package delete <name> --version-id 123 --repo owner/repo --type npm --yes
ghg package restore <name> --version-id 123 --repo owner/repo --type npmlistlists packages for a repository, organization, or user.viewshows package details.versionslists package versions.deletedeletes a package version.restorerestores a deleted package version.
ghg runner list --repo owner/repo
ghg runner list --org myorg --label linux
ghg runner view 1 --repo owner/repo
ghg runner status 1 --repo owner/repo
ghg runner remove 1 --repo owner/repo --yes
ghg runner labels 1 --repo owner/repolistlists self-hosted runners for a repo or org.viewshows runner details.statusshows health and busy status.removeremoves a runner after confirmation.labelslists labels attached to a runner.
ghg advisory list --repo owner/repo --state published
ghg advisory view GHSA-xxxx --repo owner/repo
ghg advisory create --repo owner/repo --summary "Vulnerability" --description "Details" --severity high
ghg advisory publish GHSA-xxxx --repo owner/repo
ghg advisory close GHSA-xxxx --repo owner/repo
ghg advisory cve-request GHSA-xxxx --repo owner/repolistlists security advisories, optionally filtered by state and scoped to a repo.viewviews advisory details.createcreates a draft repository security advisory.publishpublishes a draft advisory.closecloses an advisory.cve-requestrequests a CVE for a published advisory.
ghg extension list
ghg extension install owner/ghg-my-extension
ghg extension remove ghg-my-extension --yes
ghg extension upgrade ghg-my-extension
ghg extension create ghg-my-extension
ghg extension exec ghg-my-extension -- --flag arg1listlists installed extensions.installclones a git repo as an extension.removedeletes an installed extension.upgradepulls latest for an installed extension.createscaffolds a new extension project.execruns an installed extension, passing arguments through to its entry point.
ghg codespace list
ghg codespace view <id>
ghg codespace create --repo owner/repo --ref main
ghg codespace start <id>
ghg codespace stop <id>
ghg codespace delete <id> --yeslistlists your codespaces.viewshows codespace details.createcreates a codespace for a repository.startstarts a stopped codespace.stopstops a running codespace.deletedeletes a codespace after confirmation.
ghg browse repo --repo owner/repo
ghg browse repo --repo owner/repo --path src/index.ts --line 42
ghg browse issues --repo owner/repo
ghg browse pulls --repo owner/repo
ghg browse actions --repo owner/repo
ghg browse settings --repo owner/repo
ghg browse releases --repo owner/repo
ghg browse pr 42 --repo owner/reporepoopens the repository or a specific file/line in the browser.issuesopens the issues page.pullsopens the pull requests page.actionsopens the actions page.settingsopens the settings page.releasesopens the releases page.propens a pull request or issue by number.
ghg attestation list sha256:abc123... --repo owner/repo
ghg attestation verify sha256:abc123... --repo owner/repolistlists attestations for an artifact digest.verifyverifies artifact provenance for a digest.
ghg ssh-key list
ghg ssh-key add --title "My Laptop" --key "ssh-rsa AAA..."
ghg ssh-key add --title "My Laptop" --file ~/.ssh/id_rsa.pub
ghg ssh-key delete 42 --yeslistlists your SSH keys.addadds an SSH key from a string or file.deletedeletes an SSH key after confirmation.
ghg gpg-key list
ghg gpg-key add --key "-----BEGIN PGP PUBLIC KEY BLOCK-----..."
ghg gpg-key add --file /path/to/public.key
ghg gpg-key delete 42 --yeslistlists your GPG keys.addadds a GPG key from a string or file.deletedeletes a GPG key after confirmation.
ghg webhook list --repo owner/repo
ghg webhook list --org myorg
ghg webhook create --url https://example.com --events push --repo owner/repo
ghg webhook edit 1 --events push,pull_request --repo owner/repo
ghg webhook delete 1 --yes --repo owner/repo
ghg webhook test 1 --repo owner/repo
ghg webhook delivery list 1 --repo owner/repo
ghg webhook delivery view 1 --webhook 1 --repo owner/repo
ghg webhook delivery redeliver 1 --webhook 1 --repo owner/repolistlists repository or organization webhooks.createcreates a webhook with URL, events, optional secret and content type.editupdates a webhook URL or events.deleteremoves a webhook after confirmation.testtriggers a test ping delivery.delivery listlists recent deliveries for a webhook.delivery viewshows request and response details for a delivery.delivery redeliverredelivers a webhook delivery.
ghg fork sync --repo owner/repo
ghg fork compare --repo owner/repo
ghg fork list --repo owner/repo
ghg fork create owner/reposyncfast-forwards a fork from its upstream.compareshows ahead/behind status against upstream.listlists forks of a repository.createcreates a fork of a repository.
ghg deployment list --repo owner/repo --environment production
ghg deployment view 1 --repo owner/repo
ghg deployment create --ref main --environment production --repo owner/repo
ghg deployment status 1 --repo owner/repo
ghg deployment status-create 1 --state success --repo owner/repolistlists deployments with optional environment filter.viewshows deployment details.createcreates a deployment for a ref and environment.statuslists statuses for a deployment.status-createcreates a deployment status with state, description, and target URL.
ghg org members --org airscripts
ghg org invite --org airscripts --user octocat --role admin
ghg org remove --org airscripts --user octocatmemberslists all organization members with their roles.inviteadds or updates a user's organization membership.removeremoves a user from the organization.
ghg team list --org airscripts
ghg team create --org airscripts --name ops --description "Platform team"
ghg team add --org airscripts --team ops --user octocat --role maintainer
ghg team remove --org airscripts --team ops --user octocatlistshows all teams in an organization.createcreates a new team.addadds a member to a team.removeremoves a member from a team.
ghg repo create demo --private
ghg repo list --owner airscripts --owner-type org
ghg repo view airscripts/ghitgud
ghg repo clone airscripts/ghitgud --depth 1
ghg repo edit airscripts/ghitgud --description "A better GitHub CLI"
ghg repo archive airscripts/old-project
ghg repo star airscripts/ghitgud
ghg repo unstar airscripts/ghitgud
ghg repo fork airscripts/ghitgud --clone
ghg repo sync --branch main
ghg repo delete airscripts/demo --yes
ghg repo invite --user octocat --role push
ghg repo grant --team ops --role admininviteinvites a collaborator to a repository.grantgrants team access to a repository.
ghg pr create --title "Add feature" --draft
ghg pr list --state open --limit 10
ghg pr view 42
ghg pr edit 42 --body "Updated description"
ghg pr checks 42
ghg pr diff 42
ghg pr checkout 42
ghg pr comment 42 --body "Ready to merge."
ghg pr ready 42
ghg pr merge 42 --squash --delete-branch
ghg pr statuscreate,list,view, andeditcover pull request CRUD.close,reopen,ready, andmergemanage lifecycle state.checkout,diff, andcheckssupport local review and CI inspection.comment,lock, andunlockmanage the PR conversation.statusshows authored PRs and review requests across repositories.
ghg pr cleanupcleanupdeletes merged branches locally and remotely.
ghg pr push <pr-number>pushpushes local changes to a contributor's fork.
ghg pr stack create --base main
ghg pr stack list
ghg pr stack update
ghg pr stack push --title "feat: {branch}" --draftstack createcreates a stack from the current branch.stack listshows the current stack status.stack updateupdates an existing stack after parent PR merges.stack pushpushes a stack and creates or updates PRs.
ghg pr nextnextchecks out the next PR in the chain.
Built-in label presets are available with the --template / -t flag:
| Template | Description |
|---|---|
base |
Minimal set: bug and feature |
conventional |
Conventional Commits labels |
github |
GitHub default labels |
ghg labels pull -t conventional
ghg labels push -t conventionalBy default, all commands produce human-readable terminal output. For machine-parseable results, use the --json flag.
ghg notifications list --json
ghg repos inspect --org airscripts --jsonYou can also control the color theme with --theme:
ghg ping --theme dark
ghg ping --theme light
ghg ping --theme autoFor debugging, use --debug to write a trace log to a temporary file:
ghg notifications list --debugWhen --json is used, success responses are written to stdout and errors to stderr as structured JSON.
Success:
{
"success": true,
"metadata": [...]
}Error:
{
"success": false,
"error": "No repository specified. Use --repo owner/repo or run inside a git repository with a GitHub remote."
}Run the canonical local checks:
pnpm typecheck # Type check without emitting.
pnpm lint # ESLint flat config.
pnpm format # Prettier format.
pnpm test # Single test run (no watch).To verify formatting without rewriting files:
pnpm typecheck
pnpm lint
pnpm format:check
pnpm testOptional commit-time hooks are available if you want them locally:
pnpm prepare # Install husky hooks.The pre-commit setup mirrors the lightweight formatting and lint passes. Full test runs remain part of normal local verification and CI.
src/
cli/
index.ts # Entry point — Commander program setup.
ascii.ts # Figlet banner for help output.
commands/
api.ts # Authenticated REST API passthrough.
activity.ts # ghg activity.
audit.ts # ghg audit.
cache.ts # ghg cache <list|delete|inspect|download>.
gist.ts # ghg gist lifecycle and clone commands.
compliance.ts # ghg compliance <check>.
config.ts # ghg config <get|set>.
dependabot.ts # ghg dependabot <list|dismiss>.
discussion.ts # ghg discussion <list|view|create|comment|close|categories>.
insights.ts # ghg insights <traffic|contributors|commits|frequency|popularity|participation>.
issue.ts # ghg issue lifecycle, status, subtasks, and parent commands.
labels.ts # ghg labels <list|pull|push|prune>.
leaks.ts # ghg leaks <scan|alerts>.
org.ts # ghg org <members|invite|remove>.
team.ts # ghg team <list|create|add|remove>.
repo.ts # Repository CRUD and access management.
mentions.ts # ghg mentions.
milestone.ts # ghg milestone <create|list|close|progress>.
notifications.ts # ghg notifications <list|read|done>.
ping.ts # ghg ping.
pr.ts # ghg pr lifecycle, checkout, checks, cleanup, and stacks.
auth.ts # ghg auth <login|logout|status|token|list|switch|detect>.
project.ts # ghg project <board>.
queue.ts # Merge queue inspection and mutations.
ruleset.ts # Repository and organization ruleset CRUD.
status.ts # Cross-repository work status.
proxy.ts # ghg proxy <passthrough>.
repos.ts # ghg repos <inspect|govern|label|retire|report>.
review.ts # ghg review <comment|threads|resolve|suggest|apply>.
run.ts # ghg run <debug|watch>.
secrets.ts # ghg secret <list|set|delete>.
variable.ts # ghg variable <list|set|delete>.
environment.ts # ghg environment <list|create|protection>.
pages.ts # ghg pages <status|deploy|unpublish>.
branch.ts # ghg branch <protect|unprotect|protection|tag-protect|tag-unprotect|stale|sweep>.
deployment.ts # ghg deployment lifecycle commands.
fork.ts # ghg fork <sync|compare|list|create>.
webhook.ts # ghg webhook lifecycle and delivery commands.
workflow.ts # Workflow lifecycle, validation, and preview commands.
deps.ts # ghg deps <list|direct|review>.
advisory.ts # ghg advisory <list|view|create|publish|close|cve-request>.
codeql.ts # ghg codeql <list|view|dismiss>.
workspace.ts # ghg workspace <define|list|run>.
actions.ts # ghg actions <usage|cost|top-spenders|export>.
react.ts # ghg react <list|add|remove>.
comment.ts # ghg comment <list|reply|delete>.
deployment.ts # ghg deployment lifecycle commands.
branch.ts # ghg branch <protect|unprotect|protection|tag-protect|tag-unprotect|stale|sweep>.
fork.ts # ghg fork <sync|compare|list|create>.
webhook.ts # ghg webhook lifecycle and delivery commands.
code.ts # ghg code <search|definitions|references|file|blame>.
template.ts # ghg template <list|show>.
package.ts # ghg package <list|view|versions|delete|restore>.
runner.ts # ghg runner <list|view|status|remove|labels>.
extension.ts # ghg extension <list|install|remove|upgrade|create>.
codespace.ts # ghg codespace <list|view|create|start|stop|delete>.
browse.ts # ghg browse <repo|issues|pulls|actions|settings|releases|pr>.
attestation.ts # ghg attestation <list|verify>.
ssh-key.ts # ghg ssh-key <list|add|delete>.
gpg-key.ts # ghg gpg-key <list|add|delete>.
alias.ts # ghg alias <set|list|delete|import>.
completion.ts # ghg completion <generate|list>.
preview.ts # ghg preview prompter.
licenses.ts # ghg licenses <list|view>.
copilot.ts # ghg copilot [args...].
agent-task.ts # ghg agent-task <create|list|view>.
skill.ts # ghg skill <install|list|preview|publish|search|update>.
services/
labels.ts # Label business logic.
config.ts # Config business logic.
auth.ts # Auth business logic.
pr.ts # PR lifecycle business logic.
stack.ts # Stacked PR chain management.
notifications.ts # Notifications business logic.
insights.ts # Repository insights business logic.
org.ts # Organization membership business logic.
team.ts # Team management business logic.
invites.ts # Repository invite and team grant business logic.
review.ts # Code review business logic.
cache.ts # Cache management and inspection business logic.
gist.ts # Gist lifecycle and clone business logic.
issue.ts # Issue lifecycle, status, subtask, and parent business logic.
alias.ts # Command alias CRUD and resolution business logic.
completion.ts # Shell completion generation business logic.
preview.ts # Interactive prompt preview business logic.
licenses.ts # License catalog discovery business logic.
copilot.ts # Copilot CLI detection and delegation business logic.
agent-task.ts # Agent task management business logic.
skill.ts # Agent skill install, list, search, and update business logic.
milestone.ts # Milestone business logic.
notifications.ts # Notifications business logic.
run.ts # Workflow run debugging and log streaming business logic.
branch.ts # Branch and tag protection business logic.
project.ts # Project lifecycle and board business logic.
queue.ts # Merge queue orchestration.
ruleset.ts # Ruleset validation and CRUD.
status.ts # Cross-repository status aggregation.
workflow.ts # Workflow validation and preview business logic.
secrets.ts # Repository, environment, and organization secrets business logic.
variables.ts # Repository, environment, and organization variables business logic.
environments.ts # Environment and protection rules business logic.
pages.ts # GitHub Pages configuration and deployment logic.
wiki.ts # Wiki clone, read, commit, and publish logic.
deps.ts # Dependency graph and review business logic.
advisory.ts # Advisory database and lifecycle business logic.
codeql.ts # CodeQL alert management business logic.
workspace.ts # Workspace definition and multi-repo command execution.
sync.ts # Multi-repo sync and status business logic.
stale.ts # Stale branch detection and sweep business logic.
cost.ts # Actions cost and usage analytics business logic.
code.ts # Code search and navigation business logic.
template.ts # Template discovery business logic.
package.ts # Package and container registry business logic.
runner.ts # Self-hosted runner management business logic.
extension.ts # Extension install/remove/upgrade/create business logic.
codespace.ts # Codespace management business logic.
browse.ts # Browser URL construction and open logic.
attestation.ts # Attestation and provenance verification business logic.
ssh-key.ts # SSH key management business logic.
gpg-key.ts # GPG key management business logic.
repos/
govern.ts # Repository rulesets.
index.ts # Repos services index.
inspect.ts # Repository governance checks.
label.ts # Bulk label sync.
report.ts # Repository health reports.
retire.ts # Inactive repository archival.
api/
client.ts # Base HTTP client.
gists.ts # GitHub Gists API methods.
commits.ts # Commits API.
contents.ts # Contents API.
insights.ts # Insights API.
issues.ts # Issues API.
milestones.ts # Milestones API.
projects.ts # Projects API.
queue.ts # Merge queue GraphQL API.
labels.ts # GitHub Labels API methods.
notifications.ts # GitHub Notifications API methods.
pr.ts # GitHub PR API methods.
pulls.ts # Pulls API.
repos.ts # Repositories API.
rulesets.ts # Rulesets API.
orgs.ts # Organization membership API.
teams.ts # Team management API.
invites.ts # Repository invite and team grant API.
leaks.ts # Secret scanning alerts API.
secrets.ts # Repository, environment, and organization secrets API.
variables.ts # Repository, environment, and organization variables API.
environments.ts # Environment and protection rules API.
protection.ts # Branch and tag protection API.
deployments.ts # Deployments API.
forks.ts # Forks API.
webhooks.ts # Webhooks API.
pages.ts # GitHub Pages API.
dependencies.ts # Dependency graph and SBOM API.
advisories.ts # GitHub Advisory Database API.
codeql.ts # CodeQL code scanning alerts API.
billing.ts # Actions billing and usage API.
actions.ts # Actions runs API.
code.ts # Code search and navigation API.
templates.ts # Issue and PR template discovery API.
packages.ts # Package and container registry API.
runners.ts # Self-hosted runner API.
codespaces.ts # Codespaces API.
attestations.ts # Artifact attestation API.
ssh-keys.ts # SSH key management API.
gpg-keys.ts # GPG key management API.
licenses.ts # License catalog discovery API.
agent-task.ts # Agent task management API.
skill.ts # Agent skill search and publish API.
core/
command.ts # Shared command runner.
repo.ts # Repository target resolution from git remotes.
config.ts # Config resolver — env vars, profiles, credentials file.
constants.ts # Shared constants, error messages, config keys.
dates.ts # Date formatting helpers.
errors.ts # Custom error class hierarchy.
git.ts # Git operations (branch detection, remote tracking).
wiki-git.ts # Authenticated temporary wiki Git operations.
io.ts # Generic file helpers.
logger.ts # Consola instance with debug logging support.
output.ts # Terminal rendering (tables, sections, lists, key-values).
output-state.ts # Global output state (JSON and debug mode tracking).
progress.ts # Bulk progress bars.
prompt.ts # Interactive prompts.
spinner.ts # Async loading spinners.
theme.ts # Color theme management.
parse.ts # Input parsing helpers.
workspace.ts # Workspace config file management.
types/
index.ts # Shared type definitions.
notifications.ts # Notification-specific types.
templates/
base.json # Minimal label template.
conventional.json # Conventional-commits label template.
github.json # GitHub default label template.
tests/
unit/ # Unit tests mirroring src/ structure.
- New commands go in
src/commands/. Each exports{ register }— a function that takes the Commanderprogramand wires up subcommands. - New service logic goes in
src/services/. Services hold business logic and I/O. - New API endpoints go in
src/api/. API modules use the sharedclient.ts— never callfetchdirectly. - All constants live in
src/core/constants.ts. No magic strings or numbers elsewhere. - All custom errors live in
src/core/errors.ts. No barenew Error()for domain errors. @/import aliases are used throughout. Resolved by Vite at build time and bytsconfig.jsonpaths for type checking.
Playbooks are shell scripts that run ghg against the live GitHub API to verify the CLI works end to end. Each playbook covers one command family, tests positive and negative cases, and reverts all mutations on exit.
export GHG_TOKEN=ghp_...
export REPO=airscripts/chore # Default repo for repo-scoped commands.
export ORG=airchive # Default org for org-scoped commands.Change REPO and ORG in playbooks/env.sh or override them with environment variables.
- Node.js >= 24 and pnpm >= 10 for building from source.
- GitHub CLI (
gh) is required for some playbooks that create or clean up test resources (issues, teams, environments, wiki initialization). Install it from https://cli.github.com and rungh auth login. - Python 3 is required by some playbook teardown helpers for parsing JSON output.
- Git is required for wiki operations (
ghg wiki create,ghg wiki edit,ghg wiki delete).
The wiki playbooks require the repository's wiki to be initialized. If the wiki has never been used, visit https://github.com/<owner>/<repo>/wiki and create the first page, or push a Home.md to the wiki Git endpoint (see Wiki Initialization under Configuration).
Some playbooks require additional context that cannot be created automatically:
| Variable | Playbooks | What to Set |
|---|---|---|
REVIEW_PR |
review.sh |
An open pull request number on the test repo |
PROJECT_ID |
project.sh |
A GitHub Project v2 number (requires read:project token scope) |
RUN_ID |
run.sh |
An existing workflow run ID on the test repo |
INVITE_USER |
org.sh |
A GitHub username to invite (defaults to github-actions[bot]) |
If these variables are not set, the corresponding test steps are skipped automatically.
bash playbooks/pages.sh
bash playbooks/wiki.sh
bash playbooks/config.shbash playbooks/all.shSKIP="run.sh,project.sh"skips specific playbooks.PARALLEL=1runs playbooks concurrently (teardown order is not guaranteed).
ping.sh—ghg pingconfig.sh—ghg config set/get/unsetauth.sh—ghg auth login/logout/status/token/list/switch/detectactivity.sh—ghg activitymentions.sh—ghg mentionscache.sh—ghg cache list/delete/inspect/downloadgist.sh—ghg gist list/view/create/edit/delete/cloneapi.sh— authenticated REST requests, jq, and paginationstatus.sh— cross-repository and organization statusruleset.sh— ruleset validation, reads, and guarded mutationsqueue.sh— merge queue status, history, and guarded mutationsinsights.sh—ghg insights traffic/contributors/commits/frequency/popularity/participationnotifications.sh—ghg notifications list/read/donedependabot.sh—ghg dependabot list/dismissleaks.sh—ghg leaks alertsaudit.sh—ghg auditcompliance.sh—ghg compliance checkworkflow.sh— workflow lifecycle, validation, and previewlabels.sh—ghg labels list/pull/push/prune/bulk/syncpages.sh—ghg pages status/deploy/unpublishwiki.sh—ghg wiki list/view/edit/create/deleteenvironment.sh—ghg environment list/createvariable.sh—ghg variable list/set/deletesecret.sh—ghg secret list/set/deletemilestone.sh—ghg milestone create/list/close/progressdiscussion.sh—ghg discussion list/view/create/comment/close/categoriesorg.sh—ghg org members/invite/removeteam.sh—ghg team list/create/add/removeissue.sh—ghg issuelifecycle, status, subtasks, parent, and type operationsreview.sh—ghg review comment/threads/resolve/suggest/applyrepos.sh—ghg repos inspect/govern/label/retire/report/clonerepo.sh— repository CRUD plus collaborator and team accessrelease.sh—ghg release changelog/bump/verify/notes/draftpr.sh—ghg prlifecycle, checkout, checks, cleanup, push, and stack operationsproject.sh— Project v2 list and boardrun.sh—ghg run debug/watchbranch.sh—ghg branchprotection lifecyclewebhook.sh—ghg webhooklifecyclefork.sh—ghg forklifecycledeployment.sh—ghg deploymentlifecycledeps.sh—ghg depslifecycleadvisory.sh—ghg advisorylifecyclecodeql.sh—ghg codeqllifecycleworkspace.sh—ghg workspacelifecycleactions.sh—ghg actionslifecyclecode.sh—ghg codesearch and navigationtemplate.sh—ghg templatediscoverypackage.sh—ghg packagelifecyclerunner.sh—ghg runnermanagementextension.sh—ghg extensionlifecyclecodespace.sh—ghg codespacemanagementbrowse.sh—ghg browseURL generationattestation.sh—ghg attestationprovenancessh-key.sh—ghg ssh-keymanagementgpg-key.sh—ghg gpg-keymanagement
- Every playbook sources
playbooks/env.shfor configuration and assertion helpers. - Each playbook defines
setup()andteardown()withtrap teardown EXITto guarantee cleanup. - Test resources are prefixed with
ghg-test-orghg_for easy identification. - Non-reversible resources (environments, open PRs) are moved to a closed terminal state with a
[noop]title. - The
config.shplaybook never modifies thetokenkey — it uses a dedicatedghg_playbook_test_key. - Set
REVIEW_PR,PROJECT_ID, orRUN_IDto enable playbooks that require specific resource IDs.
Contributions and suggestions about how to improve this project are welcome! Please follow our contribution guidelines.
See SECURITY.md for reporting vulnerabilities.
If you want to support my work you can do it by following me, leaving a star, sharing my projects or also donating at the links below. Choose what you find more suitable for you:
This repository is licensed under MIT License.
