Ghitgud

A simple CLI to give superpowers to GitHub.

Table of Contents

• Installation
• Configuration
• Commands
• Templates
• Output Format
• Development
• Contributing
• Support
• License

Installation

npm install -g @airscript/ghitgud

Configuration

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

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

Retrieve a configured value:

ghitgud config get token
ghitgud config get repo

Create a token at: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens

Commands

ghitgud gh <args>              Pass through to the gh CLI
ghitgud notifications list       List notifications
ghitgud notifications list -a    Include read notifications
ghitgud notifications list -p    Only participating
ghitgud notifications list -r owner/repo  Filter by repository
ghitgud notifications read <id>   Mark a notification as read
ghitgud notifications done <id>   Mark a notification as done
ghitgud activity                 Assigned issues, review requests, mentions
ghitgud mentions                 Recent @mentions of you
ghitgud ping                     Check if the CLI is working
ghitgud labels list              List all labels for a repository
ghitgud labels pull              Pull labels from a repository to local config
ghitgud labels pull -t <name>   Pull labels from a built-in template
ghitgud labels push              Push local labels to a repository
ghitgud labels push -t <name>   Push a built-in template to a repository
ghitgud labels prune             Delete all local labels from a repository
ghitgud config set <key> <val>   Set a configuration value (token or repo)
ghitgud config get <key>         Get a configuration value

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

ghitgud labels pull -t conventional
ghitgud labels push -t conventional

Output Format

All commands output JSON to stdout on success and JSON to stderr on failure.

Success:

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

Error:

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

Development

pnpm install            # install dependencies
pnpm build              # build with Vite (single CJS bundle)
pnpm start              # run the CLI locally
pnpm test               # run tests (watch mode)
pnpm test -- --run      # single test run (no watch)
pnpm test:coverage      # run tests with coverage
pnpm typecheck          # type check without emitting
pnpm lint               # type check (alias for typecheck)
pnpm clean              # remove build artifacts

Contributing

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

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 GPL-3.0 License.