GitHub’s official command line tool

Overview

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.

Issues
  • 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.

    enhancement 
    opened by plu 44
  • 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.

    bug p3 
    opened by DannyBen 42
  • 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.

    bug 
    opened by exalted 42
  • Add table and helper template functions

    Add table and helper template functions

    Resolves #3488

    enhancement 
    opened by heaths 32
  • 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.

    opened by heaths 31
  • Termux installation for Android does not work

    Termux installation for Android does not work

    When I use 'pkg install gh' But my termux warn me 'pkg install gh: command not found'

    packaging help wanted 
    opened by greenhandzdl 29
  • 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.

    enhancement docs help wanted 
    opened by diminutivesloop 25
  • 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))
    
    bug needs-investigation 
    opened by gregopet 25
  • 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

    enhancement 
    opened by jsjoeio 25
  • 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?
    opened by vilmibm 25
  • Retrieve open security vulnerabilities

    Retrieve open security vulnerabilities

    Describe the feature or problem you’d like to solve

    It would be quite useful for scripting needs to make package security upgrades more efficient to retrieve all open security vulnerabilities, and be able to sort/filter them by severity.

    Proposed solution

    Given the following security alerts for a repo:

    image

    gh sec list or gh security list could return:

    Showing 4 of 4 open security alerts in cli/cli:
    
    trim-newlines high 3.0.0 -> 3.0.1
    glob-parent high  5.1.0 -> 5.1.2
    lodash  high  4.17.19 -> 4.17.21
    underscore  high  1.12.0 -> 1.12.1
    

    This would allow scripts to iterate through vulnerable versions (with the --json output), find appropriate lock file resolution blocks, delete those blocks, and programmatically run npm or yarn install to easily bump dependencies with permissive version constraints.

    Right now this is O(n) process that can be made a bit more simple if Dependabot PRs are possible but that's not always the case and it's exceedingly common for organizations like my employer to have a horde of security upgrades to do in one batch. Doing so in discrete PRs is not always a good solution for some repos.

    enhancement 
    opened by olivierlacan 0
  • Allow extensions to use the config system

    Allow extensions to use the config system

    Describe the feature or problem you’d like to solve

    While working with the recently introduced ability to create CLI extensions, I found it useful to use configuration settings for my extension. This works fine, except that gh config set prints a warning to stderr when used with an unknown key. That warning is reasonable -- it's good to protect users from typos --, but there seems to be no way around it (short of redirecting stderr to /dev/null, which would suppress other errors too) when I really want to use a setting key I've defined myself.

    Proposed solution

    One possible solution is to define a configuration key namespace for extensions, and assume that any settings within that namespace should be treated opaquely (and, in particular, not validated) by the main CLI. Here's a RFC proposal:

    Document the expected namespace and tweak validation

    For the extension gh-foo, we reserve the settings namespace extensions.foo.*. When calling gh config set on a key that begins with extensions.foo.*, the only validation is that gh-foo is an installed extension (if not, print a warning). As now, print a warning when setting extensions.foo or other unknown keys.

    Provide better porcelain support

    In addition, we could add an --extension flag to gh config set and gh config get. Passing --extension foo would internally prefix the provided setting key with extensions.foo., thus hiding the implementation detail from the user. It could warn (or even error) if gh-foo is not installed.

    Optionally, we could treat the entire extensions.* setting namespace as private, erroring in gh config get and gh config set if someone tries to read it directly and expecting --extension to be used -- this might be appealing if we plan to make it an error to set unknown config keys.

    Optional: Provide a hook for extensions to enumerate and validate settings

    We could allow extensions to provide additional polish if we create a config validation hook. For example, suppose that the gh-foo extension can optionally provide a gh-foo-config binary (alongide the gh-foo binary). Run without arguments, it would output a list of recognised/respected settings, similar to what gh config outputs. (Indeed, gh config --extension foo could then incorporate that output to help the user discover what's possible.) Running gh-foo-config with a single argument would exit 0 if the argument is a recognised config key, and non-zero otherwise. Running gh-foo-config with two arguments could exit 0 if the given setting/value combination is potentially valid, and non-zero (with some stderr output) if it is invalid -- for example, preventing non-numeric values for numeric settings. gh config set would use this facility to warn (or, perhaps, error) when the user specifies a setting the extension does not recognise.

    enhancement 
    opened by p0 0
  • cli.github.com help topic page not rendering properly

    cli.github.com help topic page not rendering properly

    The help topic rendering on cli.github.com is broken and results in incomplete rendering as seen here. It appears the formatting page is the only one that is actually broken.

    cc https://github.com/cli/cli/issues/3488#issuecomment-917718648

    bug p3 
    opened by samcoe 1
  • gh repo edit

    gh repo edit

    This PR adds a repo edit command to update settings of a repository.

    Closes #995

    opened by g14a 1
  • Add `--draft` and `--non-draft` filters to `gh pr list`

    Add `--draft` and `--non-draft` filters to `gh pr list`

    Adds --draft and --non-draft filters to gh pr list. I didn't create new ticket for this, but it was previously mentioned in https://github.com/cli/cli/issues/641 Implementation was done using other options as a reference: seems to work :)

    opened by SiarheiFedartsou 11
  • install binary extensions

    install binary extensions

    This pull request teaches gh extension install how to detect, download, and install a precompiled ("binary") extension.

    This is not full support for binary extensions; see #4194 for the remaining TODOs. However, this PR can be merged without breaking any existing functionality or advertising any new functionality.

    I included tests.

    opened by vilmibm 1
  • Add repository deploy key operations support

    Add repository deploy key operations support

    Fixes #4242

    opened by n1lesh 0
  • Add a -tui parameter to the CLI

    Add a -tui parameter to the CLI

    Describe the feature or problem you’d like to solve

    When browsing issues or PRs, usually you need to find the issue then launch the command again using the view option it you want to see the context.

    Proposed solution

    Add a -tui parameter à la GDB in order to browse stuff like issues and pull request more comfortably

    enhancement needs-user-input 
    opened by RMPR 2
  • feat: allow issue comment to work on PRs

    feat: allow issue comment to work on PRs

    Fixes #4202

    opened by 3b3ziz 1
  • docs: add hint how to use use stdin in api command

    docs: add hint how to use use stdin in api command

    show in the help page that the API command can read from stdin (handy when passing complex body)

    opened by rethab 1
Releases(v2.0.0)
 OS X command line tools for developers – The ultimate tool to manage your Mac. It provides a huge set of command line commands that automatize the usage of your OS X system.

Mac CLI  macOS command line tools for developers ⭐ Now with modularity and plugins! You can check the plugins folder: /mac-cli/plugins Contributions

Gabriel Guarino 8.1k Sep 21, 2021
cliclick is a macOS CLI tool for emulating mouse and keyboard events

cliclick (short for “Command Line Interface Click”) is a tool for executing mouse- and keyboard-related actions from the shell/Terminal. It is written in Objective-C and runs on OS X 10.15 or later.

Carsten Blüm 1.1k Sep 17, 2021
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

GitHub CLI 25.5k Sep 24, 2021
 Swiss Army Knife for macOS

 m-cli ?? Swiss Army Knife for macOS ! Overview Install Uninstall How To Use All Commands Contributing Overview m-cli is a macOS command line tool th

Roger 8.5k Sep 21, 2021
The best command-line tool to install and switch between multiple versions of Xcode.

xcodes The best command-line tool to install and switch between multiple versions of Xcode. If you're looking for an app version of xcodes, try Xcodes

Robots and Pencils 917 Sep 19, 2021
Mac App Store command line interface

mas-cli A simple command line interface for the Mac App Store. Designed for scripting and automation. ?? Install ?? Homebrew Homebrew is the preferred

mas-cli 8.4k Sep 20, 2021
Command-line tool that instantly fetches Stack Overflow results when an exception is thrown

rebound Rebound is a command-line tool that instantly fetches Stack Overflow results when an exception is thrown. Just use the rebound command to exec

Jonathan Shobrook 3.7k Sep 19, 2021
A code-searching tool similar to ack, but faster.

The Silver Searcher A code searching tool similar to ack, with a focus on speed. Do you know C? Want to improve ag? I invite you to pair with me. What

Geoff Greer 22.6k Sep 23, 2021
Git-integrated backup tool for macOS and Linux devs.

shallow-backup shallow-backup lets you easily create lightweight backups of installed packages, applications, fonts and dotfiles, and automatically pu

Aaron Lichtman 786 Sep 17, 2021
Tasks, boards notes for the command-line habitat

Taskbook Tasks, boards & notes for the command-line habitat Description By utilizing a simple and minimal usage syntax, that requires a flat learning

Klaus Sinani 8.2k Sep 18, 2021
Manage complex tmux sessions easily

Tmuxinator Create and manage tmux sessions easily. Installation RubyGems gem install tmuxinator Homebrew brew install tmuxinator tmuxinator aims to

tmuxinator 10.9k Sep 24, 2021
Glances an Eye on your system. A top/htop alternative for GNU/Linux, BSD, Mac OS and Windows operating systems.

Glances - An eye on your system Summary Glances is a cross-platform monitoring tool which aims to present a large amount of monitoring information thr

Nicolas Hennion 19.2k Sep 19, 2021
Miller is like awk, sed, cut, join, and sort for name-indexed data such as CSV, TSV, and tabular JSON

What is Miller? Miller is like awk, sed, cut, join, and sort for name-indexed data such as CSV, TSV, and tabular JSON. Build status License: BSD2 Docs

John Kerl 4.4k Sep 22, 2021
A cd command that learns - easily navigate directories from the command line

NAME autojump - a faster way to navigate your filesystem DESCRIPTION autojump is a faster way to navigate your filesystem. It works by maintaining a d

William Ting 13k Sep 23, 2021
Terminal session recorder 📹

Note: This is README for development branch. See the version for latest stable release. asciinema Terminal session recorder and the best companion of

asciinema 9.6k Sep 22, 2021
:rocket::star: A Zsh prompt for Astronauts

?? ⭐ Spaceship ZSH Zsh prompt for Astronauts. Website | Install | Features | Options | API Built with ❤︎ by Denys Dovhan and contributors Spaceship is

Denys Dovhan 15.2k Sep 16, 2021
🚀 Bring your favorite shell wherever you go through the ssh.

You stuffed command shell with aliases, tools and colors but you lose it all when using ssh. The mission of xxh is to bring your favorite shell wherev

null 1.9k Sep 24, 2021
Log file navigator

This is the source repository for lnav, visit http://lnav.org for a high level overview. LNAV -- The Logfile Navigator The Log File Navigator, lnav fo

Tim Stack 3.8k Sep 24, 2021
A new type of shell

README Nushell A new type of shell. Status This project has reached a minimum-viable product level of quality. While contributors dogfood it as their

Nushell Project 15.9k Sep 24, 2021