GitHub’s official command line tool

GitHub CLI

gh is GitHub on the command line. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already working with git and your code.

screenshot of gh pr status

GitHub CLI is available for repositories hosted on GitHub.com and GitHub Enterprise Server 2.20+, and to install on macOS, Windows, and Linux.

Documentation

See the manual for setup and usage instructions.

Contributing

If anything feels off, or if you feel that some functionality is missing, please check out the contributing page. There you will find instructions for sharing your feedback, building the tool locally, and submitting pull requests to the project.

Installation

macOS

gh is available via Homebrew, MacPorts, and as a downloadable binary from the releases page.

Homebrew

Install: Upgrade:
brew install gh brew upgrade gh

MacPorts

Install: Upgrade:
sudo port install gh sudo port selfupdate && sudo port upgrade gh

Linux

gh is available via Homebrew, and as downloadable binaries from the releases page.

For more information and distro-specific instructions, see the Linux installation docs.

Windows

gh is available via WinGet, scoop, Chocolatey, and as downloadable MSI.

WinGet

Install: Upgrade:
winget install gh winget install gh

WinGet does not have a specialized upgrade command yet, but the install command should work for upgrading to a newer version of GitHub CLI.

scoop

Install: Upgrade:
scoop install gh scoop update gh

Chocolatey

Install: Upgrade:
choco install gh choco upgrade gh

Signed MSI

MSI installers are available for download on the releases page.

Other platforms

Download packaged binaries from the releases page.

Build from source

See here on how to build GitHub CLI from source.

Comparison with hub

For many years, hub was the unofficial GitHub CLI tool. gh is a new project that helps us explore what an official GitHub CLI tool can look like with a fundamentally different design. While both tools bring GitHub to the terminal, hub behaves as a proxy to git, and gh is a standalone tool. Check out our more detailed explanation to learn more.

Comments
  • Support for GitHub Enterprise

    Support for GitHub Enterprise

    This looks awesome! Are you planning GHE support already?


    Update from the GitHub CLI team:

    In the README we shared additional information about this to help set expectations. Enterprise Server support is something we're really excited to provide, but we want to ensure it's actually usable and that the API endpoints are available on the GHES versions people are using.

  • Post https://api.github.com/graphql: net/http: TLS handshake timeout

    Post https://api.github.com/graphql: net/http: TLS handshake timeout

    Describe the bug

    TLS handshake timeout error upon first ever run of gh issue list after having the CLI installed.

    gh version 0.5.5 (2020-02-13)
    https://github.com/cli/cli/releases/tag/v0.5.5
    

    Steps to reproduce the behavior

    1. brew install github/gh/gh
    2. gh issue list
    3. Authenticate via the URL provided.
    4. Authentication complete. Press Enter to continue…
    5. Retry gh issue list
    6. Observe the error after ~10 seconds:
    Post https://api.github.com/graphql: net/http: TLS handshake timeout
    

    Expected vs actual behavior

    I was expecting to see the list of issues for the current working directory's repo, however it ended up error-ing on me.

  • Additional or alternative authentication method

    Additional or alternative authentication method

    A browser is not always available for authentication.

    I am working on a vagrant linux guest, which cannot open browser in the Windows host.

    I would love to see a gh login command (or similar) to store credentials as appropriate by the system without opening a browser.

    At the very least - if this is not changed, or until it is - I would love to see the URL it wants to open so I can open it manually.

  • Known problems with `repo create` command

    Known problems with `repo create` command

    The gh repo create command right now has separate and potentially confusing behaviors when ran inside an existing local git repository vs. outside of it.

    Bugs:

    • [x] Remote origin already exists https://github.com/cli/cli/issues/2166 #893
    • [x] Can't create a new repo while within a repo https://github.com/cli/cli/issues/2059
    • [x] Takes parent directory instead of current directory name https://github.com/cli/cli/issues/2026
    • [x] Confusing prompt This will create 'your-repo-name' in your current directory. Continue? (Y/n) #1913 #2180 https://github.com/cli/cli/pull/2295 https://github.com/cli/cli/pull/2214 https://github.com/cli/cli/pull/2507
    • [ ] Do not offer INTERNAL visibility option if it's not supported on the platform https://github.com/cli/cli/issues/2106
    • [ ] Have repo create pick up the default branch setting on GitHub #1810
    • [x] Repo create: local directory for new repo not created when non-interactive and --confirm #2587

    Features:

    • [x] Ask to git init https://github.com/cli/cli/issues/2099 https://github.com/cli/cli/issues/1280
    • [x] Specify the base dir for the new repo https://github.com/cli/cli/issues/2077
    • [x] Create with gitignore and license files #1907
    • [x] Expose more repository settings https://github.com/cli/cli/issues/995
    • [x] After initializing a repo with a template pull down changes https://github.com/cli/cli/issues/2290

    Ref. https://github.com/cli/cli/pull/547

  • MSI installer ignores selected target folder

    MSI installer ignores selected target folder

    Describe the bug

    The MSI installer for Windows 10 x64

    1. suggests a wrong install folder (x86 instead of x64)
    2. ignores different install folder when changed by user

    Tested with installer for 0.6.2: https://github.com/cli/cli/releases/download/v0.6.2/gh_0.6.2_windows_amd64.msi

    Steps to reproduce the behavior

    1. Launch .msi install file on Windows 10 x64.
    2. See default install location: C:\Program Files (x86)\GitHub CLI (error 1)
    3. Change install location to: C:\Program Files\GitHub CLI
    4. Finish the install process.
    5. See application installed in: C:\Program Files (x86)\GitHub CLI (error 2)

    Expected vs actual behavior

    1. Default install location to be: C:\Program Files\GitHub CLI
    2. User changes to install location to be reflected
  • Re-enable label colors for issue list

    Re-enable label colors for issue list

    This reverts commit 930ee60ac5895e4eb4e19a22bf34148b76a2d431 and uses the text.Truncate function from PR #3519 that correctly measures ANSI escape codes.

  • Filtering options for issues and pull requests

    Filtering options for issues and pull requests

    This is a tracking ticket listing all the filtering options for issues and pull request currently available on GitHub and the status of their availability in GitHub CLI. (Checked means implemented and merged to master.)

    We do not plan to explicitly support all these filtering options in CLI. We will select those that we intend to implement on a case-by-case basis.

    Filtering options available through GitHub web UI

    Issues

    • [x] assignee --assignee, -a
    • [x] assigned to the current authenticating user
    • [ ] no assignee
    • [x] ~labels --label, -l ("OR" logic)~
    • [x] labels --label, -l ("AND" logic) #419
    • [ ] excluding a label
    • [ ] no label
    • [x] state --state, -s
    • [x] author --author, -A #625
    • [x] authored by the current authenticating user
    • [x] mentioning user
    • [x] mentioning the the current authenticating user
    • [ ] mentioning team
    • [ ] project
    • [ ] no project
    • [x] milestone
    • [ ] no milestone

    Pull requests

    • [x] assignee --assignee, -a
    • [x] assigned to the current authenticating user
    • [ ] no assignee
    • [x] ~labels --label, -l ("OR" logic)~
    • [x] labels --label, -l ("AND" logic) #419
    • [ ] excluding a label
    • [ ] no label
    • [x] state --state, -s
    • [x] author --author, -A
    • [x] authored by the current authenticating user
    • [ ] mentioning {user|team}
    • [x] mentioning the current authenticating user
    • [ ] project
    • [ ] no project
    • [ ] milestone
    • [ ] no milestone
    • review status
      • [ ] no reviews
      • [ ] review required
      • [ ] approved
      • [ ] changes requested
      • [ ] reviewed by {user|team}
      • [ ] reviewed by the current authenticating user
      • [ ] not reviewed by {user|team}
      • [ ] not reviewed by the current authenticating user
      • [ ] awaiting review from {user|team}
      • [ ] awaiting review from the current authenticating user

    Filtering options available through advanced search syntax

    Issues

    • [ ] commented on by {user}
    • [ ] number of comments
    • [ ] number of interactions
    • [ ] number of reactions
    • [ ] involves {user}
    • [ ] linked issue/pull request
    • [ ] date created
    • [ ] date updated
    • [ ] date closed

    Pull requests

    • [ ] commented on by {user}
    • [ ] number of comments
    • [ ] number of interactions
    • [ ] number of reactions
    • [ ] involves {user}
    • [ ] linked issue/pull request
    • [ ] date created
    • [ ] date updated
    • [ ] date closed
    • [ ] date merged
    • [ ] search by commit SHA
    • [ ] draft status
    • [x] base branch --base, -B
    • [ ] head branch
  • Ability to configure a default editor for use with `gh`

    Ability to configure a default editor for use with `gh`

    Describe the feature or problem you’d like to solve

    I used gh pr create (surprised that it defaulted to open my PR from a fork into the upstream repo - it was awesome🤩) and when I went to edit the PR body, it defaulted to nano but I'd prefer it to use vim.

    Proposed solution

    1. When a user first install gh prompt them to choose a default editor:
    • nano
    • vim
    1. Let a user specify editor
    gh set-editor vim
    

    How will it benefit CLI and its users?

    • it will support nano and vim users ❤️

    Additional context

    N/A

  • Uploading new releases is too slow and mostly times out

    Uploading new releases is too slow and mostly times out

    Describe the bug

    We are trying to upload artefacts created with our build server. We are uploading two files, one ~50Mb and the other ~90Mb. We can upload one or the other, but it takes 20 minutes to do so. If we try to upload both the process fails with http2: Transport: cannot retry err [stream error: stream ID 1; REFUSED_STREAM] after Request.Body was written; define Request.GetBody to avoid this error.

    If I run the speedtest CLI tool the upload speed is nearing 100Mb/s, yet while the gh release create command is running it barely reaches 1Mb/s. If I use the website, the upload is very fast.

    Our version is gh version 1.7.0 (2021-03-04).

    Steps to reproduce the behavior

    1. Type gh release create speed-test build1.tar.gz build2.tar.gz
    2. Wait 20 minutes
    3. Error appears

    Expected vs actual behavior

    The release should upload relatively quickly and the process should not fail.

    Logs

      Starting: /opt/buildagent/temp/agentTmp/custom_script1786572503185520936
    18:31:43
      in directory: /opt/buildagent/work/cd80fa15c4f3d102
    18:51:31
      Post "https://uploads.github.com/repos/our-team/our-project/releases/release-id/assets?label=&name=our-file.tar.gz": http2: Transport: cannot retry err [stream error: stream ID 1; REFUSED_STREAM] after Request.Body was written; define Request.GetBody to avoid this error
    18:51:31
      Process exited with code 1
    18:51:31
      Process exited with code 1 (Step: Create GitHub release (Command Line))
    
  • shell aliases

    shell aliases

    This PR augments gh pr alias set with the ability to accept -s/--shell. Shell aliases are executed through $SHELL and allow executing various commands in composition instead of just rewriting invocations of gh subcommands.

    It works like this:

    $ gh alias set -s checklist 'gh issue list -l$1 | sed "s/^/- [ ] /" > checklist.md'
    - Adding alias for checklist: gh issue list -l$1 | sed "s/^/- [ ] /" > checklist.md
    ✓ Added alias.
    $ gh checklist epic
    
    Showing 2 of 2 issues in cli/cli that match your search
    
    $ cat checklist.md
    - [ ] 957       [Tracking issue] Improve GitHub authentication via GitHub CLI   enhancement, epic       about 4 days ago
    - [ ] 939       Alias support phase 2   aliases, epic   about 12 days ago
    

    Below is the initial sketch/discussion about this feature:


    $ gh alias set igrep '!sh -c "gh issue list -L100 | grep $1"'
    $ gh igrep alias
    
    Showing 100 of 206 issues in cli/cli
    
    1128    completions for aliases aliases, enhancement    about 18 minutes ago
    1045    Share and consume gh aliases    enhancement     about 9 days ago
    941     shell version of `gh alias set` aliases about 3 hours ago
    940     Scriptability audit     aliases, tech-debt      about 9 days ago
    939     Alias support phase 2   aliases, epic   about 2 hours ago
    

    But the caveats:

    ! character

    Enclosing the expansion in single quotes is necessary. both bash and zsh interpret ! as a special character and it will not make it into gh, which will lead to potentially confusing errors for users who forget to use single quotes when using ! style aliases.

    Potential alternatives:

    • Use a different character. None really felt right to me and just about every special character means something to shells.
    • Have gh alias set respect a --external flag. This is circular because to support this we'd have to re-enable flag parsing on gh alias set. In other words, to support --external, this would no longer work: gh alias set co pr checkout.
    • Assume an external alias if the expansion does not map to a gh command. I don't love this; losing that bit of validation for non-external aliases seems not worth it.

    my opinion: we're not going to do better than ! and requiring single quotes is acceptable.

    quote madness

    There are a lot of quote characters in gh alias set igrep '!sh -c "gh issue list | grep $1"'.

    The sh -c in !sh -c "command goes here" is not needed in all cases. It's only necessary when you want to compose commands.

    For example, this works fine:

    $ gh alias set echo '!echo'
    $ gh echo hi how are you
    hi how are you
    

    But this won't do what you want:

    $ gh alias set igrep '!gh issue list | grep $1'
    $ gh igrep alias
    
    # (...just runs issue list and discards subsequent |...)
    

    My concern here is that it's cognitively confusing for people who aren't used to scripting in shells. The sh -c is probably confusing and the need to put what they actually want to run in the double quotes when they're already wrapping everything in single quotes could lead users to frustration.

    Potential alternative:

    • always wrapping ! aliases in sh -c "<expansion>". I've hacked this together and it seems to work well; the downside is that users are now stuck invoking their composed commands via sh. They might prefer to run things through zsh or bash to pick up their own shell aliases (i.e. aliases they've defined in their shells, not gh aliases). We could expose the shell for external aliases as a config option with a default of sh.

    That could lead to something like this:

    # In ZSH:
    $ alias g=grep
    $ gh alias set ig '!gh issue list | g $1'
    $ gh ig alias
    external alias failed: sh: 1: command not found: g
    
    $ gh config set shell zsh
    $ gh ig alias
    # ... expected output ...
    

    my opinion: I'm really intrigued by always wrapping in a sh -c "<...>". I like combining it with the new config setting.

    Multiline input

    I started experimenting with accepting an --input <filename> argument with an alias expansion in it so that alias definitions could be written on multiple lines. This felt kind of bad; I wasn't sure if suddenly having to worry about newlines in alias expansions was worth it.

    Potential paths:

    • Continue trying to allow for file input and handling newlines appropriately when setting up commands.
    • Leave as-is and worry about more complex scripting in @mislav's extensions hack day proposal.

    my opinion: we can punt on this for now.

    If you read this far

    I'd love feedback on the above three caveats as well as any other thoughts y'all have about this.

    tl;dr:

    • is the ! character ok for signalling to gh that the user wants an external alias?
    • should we wrap all external aliases in sh -c "<expansion>"?
    • should we worry about multi-line input at this point?
  • Document oh-my-zsh workaround for completion support

    Document oh-my-zsh workaround for completion support

    Describe the bug

    After following the instructions for enabling shell completion I still can’t get the completion functionality to work. I’ve tried both the eval and Homebrew options. I’m on Mac OS 10.15.4 using zsh with Oh My Zsh and gh version 0.6.2.

    Steps to reproduce the behavior

    1. Add the Homebrew completion snippet to .zshrc. and open a new terminal.
    2. Type gh
    3. Press Tab
    4. Run eval "$(gh completion -s zsh)”
    5. Repeat steps 2-3

    Expected vs actual behavior

    I expect to see completion options for gh commands but instead I get my shell’s standard file path completion.

  • Always use same protocol for clone remotes

    Always use same protocol for clone remotes

    This PR makes it so when we add an upstream remote during repo clone the URL uses the same protocol as the origin remote. If the clone URL does not include the protocol to use we only need to checks the users git_protocol preference once since a repo parent has to come from the same host as the fork.

    In #5984 the user had ssh git_protocol configured for "github.com" and https git_protocol as the normal default, so in some odd circumstances when the canonicalRepo.Parent.RepoHost() did not return the same host as repo.RepoHost() it caused us to write different protocols for the upstream and origin remotes.

    Fixes https://github.com/cli/cli/issues/5984

  • Show action run url in `gh run` output

    Show action run url in `gh run` output

    Describe the feature or problem you’d like to solve

    During/after running gh run watch in terminal users might want to check logs in web app. Currently only the ID of the run is printed. Users have to usually navigate to the repo site on github, press Actions and then locate the run in a list of pipelines.

    Proposed solution

    Example output

    gh run watch
    ? Select a workflow run  [Use arrows to move, type to filter]
    > * ci/cd: add e2e test case, CI (main)
    
    See in browser: https://github.com/aljorhythm/tack/actions/runs/2781021545
    
    JOBS
    
    * build_and_deploy (ID 7627539044)
      ✓ Set up job
      ✓ Run actions/[email protected]
    

    How will it benefit CLI and its users?

    Printing the URL of the run will allow users to quickly access the run in browser.

    Additional context

    Add any other context like screenshots or mockups are helpful, if applicable.

  • Add a way to only fetch a PR without checking it out

    Add a way to only fetch a PR without checking it out

    Describe the feature or problem you’d like to solve

    Sometimes I only want to fetch a PR to reference its commits in a cherry-pick instead of checking it out. --fetch in #6018 does exactly that.

    Proposed solution

    #6018

    Additional context

  • CS ssh helptext to indicate how to install ssh

    CS ssh helptext to indicate how to install ssh

    Requested: https://github.com/cli/cli/issues/5739#issuecomment-1199780829

    SSH is no longer autgo-installed on connect, on codespace container. Users will need to ensure their container has sshd pre-installed, before they can connect to it. This PR updates the docs to reflect the same.

  • Change default markdown wrap limit from 80 to 120

    Change default markdown wrap limit from 80 to 120

    The default word wrap limit in Glamour is 80, see https://github.com/charmbracelet/glamour/issues/161

    This causes problems rendering hard-wrapped text and blockquoted text.

    For example, with a PR body hard-wrapped at 80 (not an unusual editor setting), wrapping is skewed when viewing PRs as the body is indented.

    Block quoted text is similarly affected, when wrapped at 80, things get skewed, e.g. see comments on gh issue view -R cli/cli -c 359

    Fix by overriding the glamour default with a custom default of 120, which is the same default set by the glow cli markdown renderer. While this does not solve all problems, IMO it is a significant improvement.

    Fixes #3501

    Possible improvement: wrap at terminal width if less than 120

A command line tool that builds and (re)starts your web application everytime you save a Go or template fileA command line tool that builds and (re)starts your web application everytime you save a Go or template file

# Fresh Fresh is a command line tool that builds and (re)starts your web application everytime you save a Go or template file. If the web framework yo

Nov 22, 2021
git-xargs is a command-line tool (CLI) for making updates across multiple Github repositories with a single command.
git-xargs is a command-line tool (CLI) for making updates across multiple Github repositories with a single command.

Table of contents Introduction Reference Contributing Introduction Overview git-xargs is a command-line tool (CLI) for making updates across multiple

Aug 7, 2022
git-xargs is a command-line tool (CLI) for making updates across multiple GitHub repositories with a single command
git-xargs is a command-line tool (CLI) for making updates across multiple GitHub repositories with a single command

git-xargs is a command-line tool (CLI) for making updates across multiple GitHub repositories with a single command. You give git-xargs:

Feb 5, 2022
An open-source GitLab command line tool bringing GitLab's cool features to your command line
An open-source GitLab command line tool bringing GitLab's cool features to your command line

GLab is an open source GitLab CLI tool bringing GitLab to your terminal next to where you are already working with git and your code without switching

Aug 9, 2022
A command line tool to prompt for a value to be included in another command line.

readval is a command line tool which is designed for one specific purpose—to prompt for a value to be included in another command line. readval prints

Dec 22, 2021
Simple command line tool helper to integrate with hashicorp vault & github api

Overview CI/CD Toolkit is small command line tool helper to integrate with vault secret kv management & github api We can use simple command to genera

Apr 2, 2022
A command line tool for simplified docker volume command built with go

dockervol A command line tool for simplified docker volume command built with go. Features: Remove anonymous volume (beta) Remove volume by matching n

Dec 18, 2021
github stats from the command line
github stats from the command line

Retrieve GitHub statistics per username from the command line: no need to open the browser anymore!

Jul 18, 2022
A command-line to create a pull request to review the entire content of a Github repository.

Pull Request Me Pull Request Me (PRMe) creates a pull request for the entire content of a Github repository. This is useful to solicit review comments

Nov 2, 2021
GitHub on the command line with golang
GitHub on the command line with golang

GitHub CLI gh is GitHub on the command line. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already

Dec 31, 2021
Simple command line Github Search

ghs is a simple command line tool which will open the corresponding url for your github search in your default web browser.

Nov 10, 2021
gh is GitHub on the command line
gh is GitHub on the command line

gh is GitHub on the command line. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already working with git and your code.

Nov 10, 2021
Gh: GitHub on the command line
Gh: GitHub on the command line

GitHub CLI gh is GitHub on the command line. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already

Jan 5, 2022
A command line utility for labeling GitHub issues and pull requests

A command line utility for labeling GitHub issues and pull requests

Nov 12, 2021
Command-line utility to grab Github gists from your own account.
Command-line utility to grab Github gists from your own account.

gistfetch Command-line utility to grab Github gists from your own account. How do I use this? Add an API token with permissions to read Gists Fetch th

Dec 14, 2021
gh is GitHub on the command line.
gh is GitHub on the command line.

gh is GitHub on the command line. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already working with git and your code.

Mar 22, 2022
GTDF-CLI - The official CLI tool to operate with Getting Things Done Framework
GTDF-CLI - The official CLI tool to operate with Getting Things Done Framework

This is the official CLI tool to operate with Getting Things Done Framework. How

Feb 14, 2022
Go package to make lightweight ASCII line graph ╭┈╯ in command line apps with no other dependencies.
Go package to make lightweight ASCII line graph ╭┈╯ in command line apps with no other dependencies.

asciigraph Go package to make lightweight ASCII line graphs ╭┈╯. Installation go get github.com/guptarohit/asciigraph Usage Basic graph package main

Aug 5, 2022
fofax is a fofa query tool written in go, positioned as a command-line tool and characterized by simplicity and speed.
fofax is a fofa query tool written in go, positioned as a command-line tool and characterized by simplicity and speed.

fofaX 0x00 Introduction fofax is a fofa query tool written in go, positioned as

Jul 30, 2022