ghitgud

A better GitHub CLI that extends the official gh CLI.

---

Table of Contents

• What It Does
• How It Works
• Features
• Install
• Configuration
• Profile Management
• Commands
• PR Workflow
• Templates
• Output Format
• Development Checks
• Repository Structure
• Contributing
• Security
• Support
• License

---

What It Does

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.

---

How It Works

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.

---

Features

• 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
• Multi-Account Profiles — switch between GitHub accounts and tokens per repository
• 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 Utilities — validate and preview GitHub Actions workflows before pushing
• Cache Inspection — inspect and download GitHub Actions cache metadata
• Run Debugging — fetch logs, artifacts, and annotations for workflow runs
• Proxy Passthrough — pass any unrecognized command directly to the gh CLI
• 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 ghg workflow surface from ghg tui
• Release Automation — generate changelogs, auto-detect next semver, verify signatures, render templated notes, and create draft releases
• Milestone Management — track sprint progress with create, list, close, and progress commands
• Project Boards — render an ASCII kanban board for any GitHub Project v2
• Issue Subtasks — create, link, and organize sub-issues with parent support
• 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

---

Install

npm install -g @airscript/ghitgud

Published 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 ghitgud and ghg commands. This documentation uses the compact ghg form.

---

Configuration

Set a GitHub personal access token and repository (in owner/repo format):

ghg config set token <your-token>
ghg config set repo owner/repository

Retrieve a configured value:

ghg config get token
ghg config get repo

Token type recommendation: Use a classic personal access token with at least repo, notifications, read:user, and read:org scopes. 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

Configuration is stored in ~/.config/ghitgud/credentials.json and supports per-repository .ghitgudrc files for automatic profile detection.

---

Profile Management

ghg introduces multi-account support through named profiles. Each profile stores its own token and optional repository association.

# Add or update a profile.
ghg profile add work --repo owner/repo --token ghp_xxx

# List all profiles.
ghg profile list

# Activate a profile for the current session.
ghg profile switch work

# Auto-detect profile from current repository.
ghg profile detect

When 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, including a per-repo .ghitgudrc file if present.

---

Commands

Notifications

ghg tui
ghg notifications list
ghg notifications read <id>
ghg notifications done <id>

• tui launches the full-screen terminal UI.
• list lists unread notifications.
• read marks a notification as read.
• done marks a notification as done.

Activity & Mentions

ghg activity
ghg mentions

• activity shows assigned issues, review requests, and mentions.
• mentions shows recent @mentions of you.

Labels

ghg labels list
ghg labels pull
ghg labels push
ghg labels prune

• list lists all repository labels.
• pull pulls labels from the repository to local config.
• push pushes local labels to the repository.
• prune deletes all labels from the repository.

Repository Governance

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 30d

• inspect checks for README, LICENSE, SECURITY.md, and CODEOWNERS.
• govern applies repository rulesets across the selected repositories.
• label syncs label templates or metadata across many repositories.
• retire finds and optionally archives inactive repositories.
• report summarizes repository health and velocity.

Insights

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/repo

• traffic shows repository traffic data.
• contributors shows top contributors.
• commits shows commit activity.
• frequency shows code frequency.
• popularity shows referrers and popular paths.
• participation shows participation stats.

Review

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> --push

• comment creates a line review comment.
• threads lists review threads for a pull request.
• resolve marks a review thread as resolved.
• suggest creates a single-line suggestion.
• apply applies review suggestions locally.

Cache

ghg cache inspect <key> --repo owner/repo
ghg cache download <key> --repo owner/repo --output-dir ./cache-debug

• inspect inspects GitHub Actions cache metadata.
• download downloads cache-related debug artifacts.

Run

ghg run debug <run-id> --repo owner/repo --output-dir ./run-debug

• debug fetches logs, artifacts, and annotations for a workflow run.

Workflow

ghg workflow validate [path]
ghg workflow preview [path]

• validate validates GitHub Actions workflow files.
• preview previews workflow structure.

Configuration

ghg config set <key> <val>
ghg config get <key>

• set sets a config value such as token or repo.
• get reads a configured value.

Profile

ghg profile add <name>
ghg profile list
ghg profile switch <name>
ghg profile detect

• add adds or updates a profile.
• list lists all profiles.
• switch activates a profile.
• detect detects the profile for the current repository.

Passthrough

ghg proxy <args>

• proxy passes any arguments through to the official gh CLI.

Utility

ghg tui
ghg ping
ghg version

• tui launches the full-screen terminal UI.
• ping checks if the CLI is working.
• version shows the current version number.

Milestones

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"

• create creates a repository milestone with a due date.
• list lists open or closed milestones.
• close closes a milestone by title.
• progress shows milestone completion percentage.

Project Boards

ghg project board <id> --owner <owner>

• board renders an ASCII kanban board for a GitHub Project v2.

Issue Management

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>

• subtasks lists sub-issues for a parent issue.
• subtasks --create creates and links a new sub-issue.
• subtasks --link links an existing issue as a sub-issue.
• parent links an existing issue to a parent issue.

Security & Compliance

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 open

• audit queries organization or enterprise audit logs.
• compliance check scores repository compliance posture.
• dependabot list inspects Dependabot alerts.
• dependabot dismiss dismisses a Dependabot alert.
• leaks scan runs a local scan for leaked secrets.
• leaks alerts lists secret scanning alerts.

Discussions

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 categories

• list lists discussions, optionally by category.
• view views a discussion and its comments.
• create creates a new discussion.
• comment adds a comment to a discussion.
• close closes a discussion.
• categories lists available discussion categories.

Variables

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>

• list lists repository, environment, or organization variables.
• set creates or updates a variable.
• delete removes a variable.

Environments

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>

• list lists configured environments.
• create creates an environment with an optional wait timer.
• protection list lists protection rules for an environment.
• protection add adds a protection rule.
• protection remove removes a protection rule.

Secrets

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>

• list lists repository, environment, or organization secrets.
• set creates or updates an encrypted secret.
• delete removes a secret.

Organization

ghg org members --org airscripts
ghg org invite --org airscripts --user octocat --role admin
ghg org remove --org airscripts --user octocat

• members lists all organization members with their roles.
• invite adds or updates a user's organization membership.
• remove removes a user from the organization.

Team

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 octocat

• list shows all teams in an organization.
• create creates a new team.
• add adds a member to a team.
• remove removes a member from a team.

Repository Access

ghg repo invite --user octocat --role push
ghg repo grant --team ops --role admin

• invite invites a collaborator to a repository.
• grant grants team access to a repository.

---

PR Workflow

Clean up merged branches

ghg pr cleanup

• cleanup deletes merged branches locally and remotely.

Push Back To Contributor's Fork

ghg pr push <pr-number>

• push pushes local changes to a contributor's fork.

Manage Stacked PRs

ghg pr stack create --base main
ghg pr stack list
ghg pr stack update
ghg pr stack push --title "feat: {branch}" --draft

• stack create creates a stack from the current branch.
• stack list shows the current stack status.
• stack update updates an existing stack after parent PR merges.
• stack push pushes a stack and creates or updates PRs.

Navigate PR Chain

ghg pr next

• next checks out the next PR in the chain.

---

Templates

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 conventional

---

Output Format

By 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 --json

You can also control the color theme with --theme:

ghg ping --theme dark
ghg ping --theme light
ghg ping --theme auto

When --json is used, success responses are written to stdout and errors to stderr as structured JSON.

Success:

{
  "success": true,
  "metadata": [...]
}

Error:

{
  "success": false,
  "error": "You must set the GHITGUD_GITHUB_REPO environment variable."
}

---

Development Checks

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 test

Optional 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.

---

Repository Structure

src/
  cli/
    index.ts            # Entry point — Commander program setup.
    ascii.ts            # Figlet banner for help output.
  commands/
    activity.ts         # ghg activity.
    audit.ts            # ghg audit.
    cache.ts            # ghg cache <inspect|download>.
    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 <subtasks|parent>.
    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             # ghg repo <invite|grant>.
    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 <cleanup|push|next|stack>.
    profile.ts          # ghg profile <add|list|switch|detect>.
    project.ts          # ghg project <board>.
    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>.
    secrets.ts          # ghg secret <list|set|delete>.
    variable.ts         # ghg variable <list|set|delete>.
    environment.ts      # ghg environment <list|create|protection>.
    workflow.ts         # ghg workflow <validate|preview>.
  services/
    labels.ts           # Label business logic.
    config.ts           # Config business logic.
    profile.ts          # Profile 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 inspection business logic.
    issue.ts            # Issue subtask and parent business logic.
    milestone.ts        # Milestone business logic.
    notifications.ts    # Notifications business logic.
    run.ts              # Workflow run debugging business logic.
    project.ts          # Project board business logic.
    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.
    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.
    commits.ts          # Commits API.
    contents.ts         # Contents API.
    insights.ts         # Insights API.
    issues.ts           # Issues API.
    milestones.ts       # Milestones API.
    projects.ts         # Projects 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.
    leaks.ts            # Secret scanning alerts API.
  core/
    command.ts          # Shared command runner.
    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).
    io.ts               # Generic file helpers.
    logger.ts           # Consola instance for rich CLI output.
    output.ts           # Terminal rendering (tables, sections, lists, key-values).
    output-state.ts     # Global output state (JSON mode tracking).
    progress.ts         # Bulk progress bars.
    prompt.ts           # Interactive prompts.
    spinner.ts          # Async loading spinners.
    theme.ts            # Color theme 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 Commander program and 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 shared client.ts — never call fetch directly.
• All constants live in src/core/constants.ts. No magic strings or numbers elsewhere.
• All custom errors live in src/core/errors.ts. No bare new Error() for domain errors.
• @/ import aliases are used throughout. Resolved by Vite at build time and by tsconfig.json paths for type checking.

---

Contributing

Contributions and suggestions about how to improve this project are welcome! Please follow our contribution guidelines.

---

Security

See SECURITY.md for reporting vulnerabilities.

---

Support

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:

---

License

This repository is licensed under MIT License.