# Table of Contents - [Manual | GitHub CLI](#manual-github-cli) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) - [GitHub CLI | Take GitHub to the command line](#github-cli-take-github-to-the-command-line) --- # Manual | GitHub CLI CLI manual GitHub CLI manual ================= GitHub CLI, or `gh`, is a command-line interface to GitHub for use in your terminal or your scripts. * [Available commands](./gh) * [Usage examples](./examples) * [Community extensions](https://github.com/topics/gh-extension) Installation ------------ You can find installation instructions on our [README](https://github.com/cli/cli#installation) . Configuration ------------- * Run [`gh auth login`](./gh_auth_login) to authenticate with your GitHub account. Alternatively, `gh` will respect the `GITHUB_TOKEN` [environment variable](./gh_help_environment) . * To set your preferred editor, use `gh config set editor `. Read more about [`gh config`](./gh_config) and [environment variables](./gh_help_environment) . * Declare your aliases for often-used commands with [`gh alias set`](./gh_alias_set) . GitHub Enterprise ----------------- GitHub CLI supports GitHub Enterprise Server 2.20 and above. To authenticate with a GitHub instance, run: gh auth login --hostname To define this host as a default for all GitHub CLI commands, set the GH\_HOST environment variable: export GH_HOST= Finally, to authenticate commands in scripting mode or automation, set the GH\_ENTERPRISE\_TOKEN: export GH_ENTERPRISE_TOKEN= Support ------- * Ask usage questions and send us feedback in [Discussions](https://github.com/cli/cli/discussions) * Report bugs or search for existing feature requests in our [issue tracker](https://github.com/cli/cli/issues) --- # GitHub CLI | Take GitHub to the command line Take GitHub to the command line =============================== GitHub CLI brings GitHub to your terminal. Free and open source. `brew install gh` or [Download for Mac](https://github.com/cli/cli/releases/download/v2.67.0/gh_2.67.0_macOS_amd64.zip) [Download for Windows](https://github.com/cli/cli/releases/download/v2.67.0/gh_2.67.0_windows_amd64.msi) [Install for Linux](https://github.com/cli/cli/blob/trunk/docs/install_linux.md) [View installation instructions →](https://github.com/cli/cli#installation) $ gh issue list gh pr status gh pr checkout gh pr create gh pr checks gh release create gh repo view gh alias set ----------------------------------------------------------------------------------------------------------------- View and filter a repository’s open issues. Check on the status of your pull requests. Check out pull requests locally. Create a new pull request. View your pull requests’ checks. Create a new release. View repository READMEs. Create a shortcut for a gh command. [](#0) [](#0) $ gh issue list **Showing 4 of 4 issues in cli/cli** #16 Improving interactions with protected branches #14 PR commands on a detached head #13 Support for GitHub Enterprise (enhancement) #8 Add an easier upgrade command (bug) gh pr status Relevant pull requests in cli/cli **Current branch** There is no pull request associated with \[fix-homepage-bug\] **Created by you** You have no open pull requests **Requesting a code review from you** #100 Fix footer on homepage \[fix-homepage-footer\] ✓ Checks passing \- Review pending gh pr checkout 12 remote: Enumerating objects: 66, done. remote: Counting objects: 100% (66/66), done. remote: Total 83 (delta 66), reused 66 (delta 66), pack-reused 17 Unpacking objects: 100% (83/83), done. From https://github.com/owner/repo \* \[new ref\] refs/pull/8896/head -> patch-2 M README.md Switched to branch 'patch-2' gh pr create Creating pull request for feature-branch into main in ampinsk/test **? Title** My new pull request **? Body** \[(e) to launch vim, enter to skip\] **? What's next?** Submit https://github.com/owner/repo/pull/1 gh pr checks **All checks were successful** 1 failing, 3 successful, and 1 pending checks \- CodeQL 3m43s https://github.com/cli/cli/runs/123 ✓ build (macos-latest) 4m18s https://github.com/cli/cli/runs/123 ✓ build (ubuntu-latest) 1m23s https://github.com/cli/cli/runs/123 ✓ build (windows-latest) 4m43s https://github.com/cli/cli/runs/123 × lint 47s https://github.com/cli/cli/runs/123 gh release create 1.0 **? Title** GitHub CLI 1.0 **? Release notes** Write my own **? Is this a prerelease?** No **? Submit?** Publish release https://github.com/octocat/.github/releases/tag/1.0 gh repo view **cli/cli** 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. Image: screenshot of gh pr status → https://user-images.githubusercontent.com/98482/84171218-327e7a80-aa40-11ea-8cd1-5177fc2d0e72.png View this repository on GitHub: https://github.com/cli/cli gh alias set bugs 'issue list --label="bugs"' \- Adding alias for bugs: issue list --label="bugs" ✓ Added alias. $ gh bugs **Showing 2 of 7 issues in cli/cli that match your search** #19 Pagination request returns empty JSON (bug) #21 Error raised when passing valid parameters (bug) [View all GitHub CLI commands →](/manual/gh) Goodbye, context switching. Hello, terminal. -------------------------------------------- ### Your entire GitHub workflow Work with issues, pull requests, checks, releases and more. [View all GitHub CLI commands →](/manual/gh) ### Script and customize Call the GitHub API to script almost any action, and set a custom alias for any command. [Learn about aliases and API →](/manual) ### Enterprise-ready Connect to GitHub Enterprise Server in addition to GitHub.com. [Get set up with Enterprise →](/manual#github-enterprise) ### We <3 community GitHub CLI is open source and ready for your contributions. [Contribute to CLI →](https://github.com/cli/cli) Try GitHub on the command line ------------------------------ GitHub CLI brings GitHub to your terminal. Free and open source. `brew install gh` or [Download for Mac](https://github.com/cli/cli/releases/download/v2.67.0/gh_2.67.0_macOS_amd64.zip) [Download for Windows](https://github.com/cli/cli/releases/download/v2.67.0/gh_2.67.0_windows_amd64.msi) [Install for Linux](https://github.com/cli/cli/blob/trunk/docs/install_linux.md) [View installation instructions →](https://github.com/cli/cli#installation) ![Windows](/assets/images/icon-windows.svg) ![Mac](/assets/images/icon-mac.svg) ![Linux](/assets/images/icon-linux.svg) ![](assets/images/square-pattern.png) --- # GitHub CLI | Take GitHub to the command line CLI manual gh -- Work seamlessly with GitHub from the command line. ### Core commands * [gh auth](./gh_auth) * [gh browse](./gh_browse) * [gh codespace](./gh_codespace) * [gh gist](./gh_gist) * [gh issue](./gh_issue) * [gh org](./gh_org) * [gh pr](./gh_pr) * [gh project](./gh_project) * [gh release](./gh_release) * [gh repo](./gh_repo) ### GitHub Actions commands * [gh cache](./gh_cache) * [gh run](./gh_run) * [gh workflow](./gh_workflow) ### Additional commands * [gh alias](./gh_alias) * [gh api](./gh_api) * [gh attestation](./gh_attestation) * [gh completion](./gh_completion) * [gh config](./gh_config) * [gh extension](./gh_extension) * [gh gpg-key](./gh_gpg-key) * [gh label](./gh_label) * [gh ruleset](./gh_ruleset) * [gh search](./gh_search) * [gh secret](./gh_secret) * [gh ssh-key](./gh_ssh-key) * [gh status](./gh_status) * [gh variable](./gh_variable) ### Options `--version` Show gh version ### Examples $ gh issue create $ gh repo clone cli/cli $ gh pr checkout 321 --- # GitHub CLI | Take GitHub to the command line CLI manual gh alias -------- Aliases can be used to make shortcuts for gh commands or to compose multiple commands. Run `gh help alias set` to learn more. ### Available commands * [gh alias delete](./gh_alias_delete) * [gh alias import](./gh_alias_import) * [gh alias list](./gh_alias_list) * [gh alias set](./gh_alias_set) ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh alias delete --------------- Delete set aliases gh alias delete { | --all} [flags] ### Options `--all` Delete all aliases ### See also * [gh alias](./gh_alias) --- # GitHub CLI | Take GitHub to the command line CLI manual gh alias import --------------- gh alias import [ | -] [flags] Import aliases from the contents of a YAML file. Aliases should be defined as a map in YAML, where the keys represent aliases and the values represent the corresponding expansions. An example file should look like the following: bugs: issue list --label=bug igrep: '!gh issue list --label="$1" | grep "$2"' features: |- issue list --label=enhancement Use `-` to read aliases (in YAML format) from standard input. The output from `gh alias list` can be used to produce a YAML file containing your aliases, which you can use to import them from one machine to another. Run `gh help alias list` to learn more. ### Options `--clobber` Overwrite existing aliases of the same name ### Examples # Import aliases from a file $ gh alias import aliases.yml # Import aliases from standard input $ gh alias import - ### See also * [gh alias](./gh_alias) --- # GitHub CLI | Take GitHub to the command line CLI manual gh alias list ------------- gh alias list This command prints out all of the aliases gh is configured to use. ### ALIASES gh alias ls ### See also * [gh alias](./gh_alias) --- # GitHub CLI | Take GitHub to the command line CLI manual gh api ------ gh api [flags] Makes an authenticated HTTP request to the GitHub API and prints the response. The endpoint argument should either be a path of a GitHub API v3 endpoint, or `graphql` to access the GitHub API v4. Placeholder values `{owner}`, `{repo}`, and `{branch}` in the endpoint argument will get replaced with values from the repository of the current directory or the repository specified in the `GH_REPO` environment variable. Note that in some shells, for example PowerShell, you may need to enclose any value that contains `{...}` in quotes to prevent the shell from applying special meaning to curly braces. The default HTTP request method is `GET` normally and `POST` if any parameters were added. Override the method with `--method`. Pass one or more `-f/--raw-field` values in `key=value` format to add static string parameters to the request payload. To add non-string or placeholder-determined values, see `-F/--field` below. Note that adding request parameters will automatically switch the request method to `POST`. To send the parameters as a `GET` query string instead, use `--method GET`. The `-F/--field` flag has magic type conversion based on the format of the value: * literal values `true`, `false`, `null`, and integer numbers get converted to appropriate JSON types; * placeholder values `{owner}`, `{repo}`, and `{branch}` get populated with values from the repository of the current directory; * if the value starts with `@`, the rest of the value is interpreted as a filename to read the value from. Pass `-` to read from standard input. For GraphQL requests, all fields other than `query` and `operationName` are interpreted as GraphQL variables. To pass nested parameters in the request payload, use `key[subkey]=value` syntax when declaring fields. To pass nested values as arrays, declare multiple fields with the syntax `key[]=value1`, `key[]=value2`. To pass an empty array, use `key[]` without a value. To pass pre-constructed JSON or payloads in other formats, a request body may be read from file specified by `--input`. Use `-` to read from standard input. When passing the request body this way, any parameters specified via field flags are added to the query string of the endpoint URL. In `--paginate` mode, all pages of results will sequentially be requested until there are no more pages of results. For GraphQL requests, this requires that the original query accepts an `$endCursor: String` variable and that it fetches the `pageInfo{ hasNextPage, endCursor }` set of fields from a collection. Each page is a separate JSON array or object. Pass `--slurp` to wrap all pages of JSON arrays or objects into an outer JSON array. ### Options `--cache ` Cache the response, e.g. "3600s", "60m", "1h" `-F`, `--field ` Add a typed parameter in key=value format `-H`, `--header ` Add a HTTP request header in key:value format `--hostname ` The GitHub hostname for the request (default "github.com") `-i`, `--include` Include HTTP response status line and headers in the output `--input ` The file to use as body for the HTTP request (use "-" to read from standard input) `-q`, `--jq ` Query to select values from the response using jq syntax `-X`, `--method (default "GET")` The HTTP method for the request `--paginate` Make additional HTTP requests to fetch all pages of results `-p`, `--preview ` GitHub API preview names to request (without the "-preview" suffix) `-f`, `--raw-field ` Add a string parameter in key=value format `--silent` Do not print the response body `--slurp` Use with "--paginate" to return an array of all pages of either JSON arrays or objects `-t`, `--template ` Format JSON output using a Go template; see "gh help formatting" `--verbose` Include full HTTP request and response in the output ### Examples # list releases in the current repository $ gh api repos/{owner}/{repo}/releases # post an issue comment $ gh api repos/{owner}/{repo}/issues/123/comments -f body='Hi from CLI' # post nested parameter read from a file $ gh api gists -F 'files[myfile.txt][content]=@myfile.txt' # add parameters to a GET request $ gh api -X GET search/issues -f q='repo:cli/cli is:open remote' # set a custom HTTP header $ gh api -H 'Accept: application/vnd.github.v3.raw+json' ... # opt into GitHub API previews $ gh api --preview baptiste,nebula ... # print only specific fields from the response $ gh api repos/{owner}/{repo}/issues --jq '.[].title' # use a template for the output $ gh api repos/{owner}/{repo}/issues --template \ '{{range .}}{{.title}} ({{.labels | pluck "name" | join ", " | color "yellow"}}){{"\n"}}{{end}}' # update allowed values of the "environment" custom property in a deeply nested array gh api -X PATCH /orgs/{org}/properties/schema \ -F 'properties[][property_name]=environment' \ -F 'properties[][default_value]=production' \ -F 'properties[][allowed_values][]=staging' \ -F 'properties[][allowed_values][]=production' # list releases with GraphQL $ gh api graphql -F owner='{owner}' -F name='{repo}' -f query=' query($name: String!, $owner: String!) { repository(owner: $owner, name: $name) { releases(last: 3) { nodes { tagName } } } } ' # list all repositories for a user $ gh api graphql --paginate -f query=' query($endCursor: String) { viewer { repositories(first: 100, after: $endCursor) { nodes { nameWithOwner } pageInfo { hasNextPage endCursor } } } } ' # get the percentage of forks for the current user $ gh api graphql --paginate --slurp -f query=' query($endCursor: String) { viewer { repositories(first: 100, after: $endCursor) { nodes { isFork } pageInfo { hasNextPage endCursor } } } } ' | jq 'def count(e): reduce e as $_ (0;.+1); [.[].data.viewer.repositories.nodes[]] as $r | count(select($r[].isFork))/count($r[])' ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh alias set ------------ gh alias set [flags] Define a word that will expand to a full gh command when invoked. The expansion may specify additional arguments and flags. If the expansion includes positional placeholders such as `$1`, extra arguments that follow the alias will be inserted appropriately. Otherwise, extra arguments will be appended to the expanded command. Use `-` as expansion argument to read the expansion string from standard input. This is useful to avoid quoting issues when defining expansions. If the expansion starts with `!` or if `--shell` was given, the expansion is a shell expression that will be evaluated through the `sh` interpreter when the alias is invoked. This allows for chaining multiple commands via piping and redirection. ### Options `--clobber` Overwrite existing aliases of the same name `-s`, `--shell` Declare an alias to be passed through a shell interpreter ### Examples # note: Command Prompt on Windows requires using double quotes for arguments $ gh alias set pv 'pr view' $ gh pv -w 123 #=> gh pr view -w 123 $ gh alias set bugs 'issue list --label=bugs' $ gh bugs $ gh alias set homework 'issue list --assignee @me' $ gh homework $ gh alias set 'issue mine' 'issue list --mention @me' $ gh issue mine $ gh alias set epicsBy 'issue list --author="$1" --label="epic"' $ gh epicsBy vilmibm #=> gh issue list --author="vilmibm" --label="epic" $ gh alias set --shell igrep 'gh issue list --label="$1" | grep "$2"' $ gh igrep epic foo #=> gh issue list --label="epic" | grep "foo" ### See also * [gh alias](./gh_alias) --- # GitHub CLI | Take GitHub to the command line CLI manual gh attestation trusted-root --------------------------- gh attestation trusted-root [--tuf-url --tuf-root ] [--verify-only] [flags] ### NOTE: This feature is currently in public preview, and subject to change. Output contents for a trusted\_root.jsonl file, likely for offline verification. When using `gh attestation verify`, if your machine is on the internet, this will happen automatically. But to do offline verification, you need to supply a trusted root file with `--custom-trusted-root`; this command will help you fetch a `trusted_root.jsonl` file for that purpose. You can call this command without any flags to get a trusted root file covering the Sigstore Public Good Instance as well as GitHub's Sigstore instance. Otherwise you can use `--tuf-url` to specify the URL of a custom TUF repository mirror, and `--tuf-root` should be the path to the `root.json` file that you securely obtained out-of-band. If you just want to verify the integrity of your local TUF repository, and don't want the contents of a trusted\_root.jsonl file, use `--verify-only`. ### Options `--hostname ` Configure host to use `--tuf-root ` Path to the TUF root.json file on disk `--tuf-url ` URL to the TUF repository mirror `--verify-only` Don't output trusted\_root.jsonl contents ### Examples # Get a trusted_root.jsonl for both Sigstore Public Good and GitHub's instance gh attestation trusted-root ### See also * [gh attestation](./gh_attestation) --- # GitHub CLI | Take GitHub to the command line CLI manual gh attestation -------------- Download and verify artifact attestations. ### Available commands * [gh attestation download](./gh_attestation_download) * [gh attestation trusted-root](./gh_attestation_trusted-root) * [gh attestation verify](./gh_attestation_verify) ### ALIASES gh at ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh attestation download ----------------------- gh attestation download [ | oci://] [--owner | --repo] [flags] ### NOTE: This feature is currently in public preview, and subject to change. Download attestations associated with an artifact for offline use. The command requires either: * a file path to an artifact, or * a container image URI (e.g. `oci://`) * (note that if you provide an OCI URL, you must already be authenticated with its container registry) In addition, the command requires either: * the `--repo` flag (e.g. --repo github/example). * the `--owner` flag (e.g. --owner github), or The `--repo` flag value must match the name of the GitHub repository that the artifact is linked with. The `--owner` flag value must match the name of the GitHub organization that the artifact's linked repository belongs to. Any associated bundle(s) will be written to a file in the current directory named after the artifact's digest. For example, if the digest is "sha256:1234", the file will be named "sha256:1234.jsonl". Colons are special characters on Windows and cannot be used in file names. To accommodate, a dash will be used to separate the algorithm from the digest in the attestations file name. For example, if the digest is "sha256:1234", the file will be named "sha256-1234.jsonl". ### Options `-d`, `--digest-alg (default "sha256")` The algorithm used to compute a digest of the artifact: {sha256|sha512} `--hostname ` Configure host to use `-L`, `--limit (default 30)` Maximum number of attestations to fetch `-o`, `--owner ` a GitHub organization to scope attestation lookup by `--predicate-type ` Filter attestations by provided predicate type `-R`, `--repo ` Repository name in the format / ### Examples # Download attestations for a local artifact linked with an organization $ gh attestation download example.bin -o github # Download attestations for a local artifact linked with a repository $ gh attestation download example.bin -R github/example # Download attestations for an OCI image linked with an organization $ gh attestation download oci://example.com/foo/bar:latest -o github ### See also * [gh attestation](./gh_attestation) --- # GitHub CLI | Take GitHub to the command line CLI manual gh attestation verify --------------------- gh attestation verify [ | oci://] [--owner | --repo] [flags] Verify the integrity and provenance of an artifact using its associated cryptographically signed attestations. In order to verify an attestation, you must validate the identity of the Actions workflow that produced the attestation (a.k.a. the signer workflow). Given this identity, the verification process checks the signatures in the attestations, and confirms that the attestation refers to provided artifact. To specify the artifact, the command requires: * a file path to an artifact, or * a container image URI (e.g. `oci://`) * (note that if you provide an OCI URL, you must already be authenticated with its container registry) To fetch the attestation, and validate the identity of the signer, the command requires either: * the `--repo` flag (e.g. --repo github/example). * the `--owner` flag (e.g. --owner github), or The `--repo` flag value must match the name of the GitHub repository that the artifact is linked with. The `--owner` flag value must match the name of the GitHub organization that the artifact's linked repository belongs to. By default, the verify command will: * only verify provenance attestations * attempt to fetch relevant attestations via the GitHub API. To verify other types of attestations, use the `--predicate-type` flag. To use your artifact's OCI registry instead of GitHub's API, use the `--bundle-from-oci` flag. For offline verification, using attestations stored on desk (c.f. the download command), provide a path to the `--bundle` flag. To see the full results that are generated upon successful verification, i.e. for use with a policy engine, provide the `--format=json` flag. The signer workflow's identity is validated against the Subject Alternative Name (SAN) within the attestation certificate. Often, the signer workflow is the same workflow that started the run and generated the attestation, and will be located inside your repository. For this reason, by default this command uses either the `--repo` or the `--owner` flag value to validate the SAN. However, sometimes the caller workflow is not the same workflow that performed the signing. If your attestation was generated via a reusable workflow, then that reusable workflow is the signer whose identity needs to be validated. In this situation, the signer workflow may or may not be located inside your `--repo` or `--owner`. When using reusable workflows, use the `--signer-repo`, `--signer-workflow`, or `--cert-identity` flags to validate the signer workflow's identity. For more policy verification options, see the other available flags. ### Options `-b`, `--bundle ` Path to bundle on disk, either a single bundle in a JSON file or a JSON lines file with multiple bundles `--bundle-from-oci` When verifying an OCI image, fetch the attestation bundle from the OCI registry instead of from GitHub `--cert-identity ` Enforce that the certificate's subject alternative name matches the provided value exactly `-i`, `--cert-identity-regex ` Enforce that the certificate's subject alternative name matches the provided regex `--cert-oidc-issuer (default "https://token.actions.githubusercontent.com")` Issuer of the OIDC token `--custom-trusted-root ` Path to a trusted\_root.jsonl file; likely for offline verification `--deny-self-hosted-runners` Fail verification for attestations generated on self-hosted runners `-d`, `--digest-alg (default "sha256")` The algorithm used to compute a digest of the artifact: {sha256|sha512} `--format ` Output format: {json} `--hostname ` Configure host to use `-q`, `--jq ` Filter JSON output using a jq expression `-L`, `--limit (default 30)` Maximum number of attestations to fetch `--no-public-good` Do not verify attestations signed with Sigstore public good instance `-o`, `--owner ` GitHub organization to scope attestation lookup by `--predicate-type (default "https://slsa.dev/provenance/v1")` Filter attestations by provided predicate type `-R`, `--repo ` Repository name in the format / `--signer-repo ` Repository of reusable workflow that signed attestation in the format / `--signer-workflow ` Workflow that signed attestation in the format \[host/\]//// `-t`, `--template ` Format JSON output using a Go template; see "gh help formatting" ### Examples # Verify an artifact linked with a repository $ gh attestation verify example.bin --repo github/example # Verify an artifact linked with an organization $ gh attestation verify example.bin --owner github # Verify an artifact and output the full verification result $ gh attestation verify example.bin --owner github --format json # Verify an OCI image using attestations stored on disk $ gh attestation verify oci:// --owner github --bundle sha256:foo.jsonl # Verify an artifact signed with a reusable workflow $ gh attestation verify example.bin --owner github --signer-repo actions/example ### See also * [gh attestation](./gh_attestation) --- # GitHub CLI | Take GitHub to the command line CLI manual gh auth logout -------------- gh auth logout [flags] Remove authentication for a GitHub account. This command removes the stored authentication configuration for an account. The authentication configuration is only removed locally. This command does not invalidate authentication tokens. ### Options `-h`, `--hostname ` The hostname of the GitHub instance to log out of `-u`, `--user ` The account to log out of ### Examples # Select what host and account to log out of via a prompt $ gh auth logout # Log out of a specific host and specific account $ gh auth logout --hostname enterprise.internal --user monalisa ### See also * [gh auth](./gh_auth) --- # GitHub CLI | Take GitHub to the command line CLI manual gh auth ------- Authenticate gh and git with GitHub ### Available commands * [gh auth login](./gh_auth_login) * [gh auth logout](./gh_auth_logout) * [gh auth refresh](./gh_auth_refresh) * [gh auth setup-git](./gh_auth_setup-git) * [gh auth status](./gh_auth_status) * [gh auth switch](./gh_auth_switch) * [gh auth token](./gh_auth_token) ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh auth refresh --------------- gh auth refresh [flags] Expand or fix the permission scopes for stored credentials for active account. The `--scopes` flag accepts a comma separated list of scopes you want your gh credentials to have. If no scopes are provided, the command maintains previously added scopes. The `--remove-scopes` flag accepts a comma separated list of scopes you want to remove from your gh credentials. Scope removal is idempotent. The minimum set of scopes (`repo`, `read:org`, and `gist`) cannot be removed. The `--reset-scopes` flag resets the scopes for your gh credentials to the default set of scopes for your auth flow. If you have multiple accounts in `gh auth status` and want to refresh the credentials for an inactive account, you will have to use `gh auth switch` to that account first before using this command, and then switch back when you are done. For more information on OAuth scopes, [https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps/](https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps/) . ### Options `-h`, `--hostname ` The GitHub host to use for authentication `--insecure-storage` Save authentication credentials in plain text instead of credential store `-r`, `--remove-scopes ` Authentication scopes to remove from gh `--reset-scopes` Reset authentication scopes to the default minimum set of scopes `-s`, `--scopes ` Additional authentication scopes for gh to have ### Examples $ gh auth refresh --scopes write:org,read:public_key # => open a browser to add write:org and read:public_key scopes $ gh auth refresh # => open a browser to ensure your authentication credentials have the correct minimum scopes $ gh auth refresh --remove-scopes delete_repo # => open a browser to idempotently remove the delete_repo scope $ gh auth refresh --reset-scopes # => open a browser to re-authenticate with the default minimum scopes ### See also * [gh auth](./gh_auth) --- # GitHub CLI | Take GitHub to the command line CLI manual gh auth login ------------- gh auth login [flags] Authenticate with a GitHub host. The default hostname is `github.com`. This can be overridden using the `--hostname` flag. The default authentication mode is a web-based browser flow. After completion, an authentication token will be stored securely in the system credential store. If a credential store is not found or there is an issue using it gh will fallback to writing the token to a plain text file. See `gh auth status` for its stored location. Alternatively, use `--with-token` to pass in a personal access token (classic) on standard input. The minimum required scopes for the token are: `repo`, `read:org`, and `gist`. Take care when passing a fine-grained personal access token to `--with-token` as the inherent scoping to certain resources may cause confusing behaviour when interacting with other resources. Favour setting `GH_TOKEN$` for fine-grained personal access token usage. Alternatively, gh will use the authentication token found in environment variables. This method is most suitable for "headless" use of gh such as in automation. See `gh help environment` for more info. To use gh in GitHub Actions, add `GH_TOKEN: ${{ github.token }}` to `env`. The git protocol to use for git operations on this host can be set with `--git-protocol`, or during the interactive prompting. Although login is for a single account on a host, setting the git protocol will take effect for all users on the host. Specifying `ssh` for the git protocol will detect existing SSH keys to upload, prompting to create and upload a new key if one is not found. This can be skipped with `--skip-ssh-key` flag. For more information on OAuth scopes, [https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps/](https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps/) . ### Options `-p`, `--git-protocol ` The protocol to use for git operations on this host: {ssh|https} `-h`, `--hostname ` The hostname of the GitHub instance to authenticate with `--insecure-storage` Save authentication credentials in plain text instead of credential store `-s`, `--scopes ` Additional authentication scopes to request `--skip-ssh-key` Skip generate/upload SSH key prompt `-w`, `--web` Open a browser to authenticate `--with-token` Read token from standard input ### Examples # Start interactive setup $ gh auth login # Authenticate against github.com by reading the token from a file $ gh auth login --with-token < mytoken.txt # Authenticate with specific host $ gh auth login --hostname enterprise.internal ### See also * [gh auth](./gh_auth) --- # GitHub CLI | Take GitHub to the command line CLI manual gh auth setup-git ----------------- gh auth setup-git [flags] This command configures `git` to use GitHub CLI as a credential helper. For more information on git credential helpers please reference: [https://git-scm.com/docs/gitcredentials](https://git-scm.com/docs/gitcredentials) . By default, GitHub CLI will be set as the credential helper for all authenticated hosts. If there is no authenticated hosts the command fails with an error. Alternatively, use the `--hostname` flag to specify a single host to be configured. If the host is not authenticated with, the command fails with an error. ### Options `-f`, `--force <--hostname>` Force setup even if the host is not known. Must be used in conjunction with --hostname `-h`, `--hostname ` The hostname to configure git for ### Examples # Configure git to use GitHub CLI as the credential helper for all authenticated hosts $ gh auth setup-git # Configure git to use GitHub CLI as the credential helper for enterprise.internal host $ gh auth setup-git --hostname enterprise.internal ### See also * [gh auth](./gh_auth) --- # GitHub CLI | Take GitHub to the command line CLI manual gh auth status -------------- gh auth status [flags] Display active account and authentication state on each known GitHub host. For each host, the authentication state of each known account is tested and any issues are included in the output. Each host section will indicate the active account, which will be used when targeting that host. If an account on any host (or only the one given via `--hostname`) has authentication issues, the command will exit with 1 and output to stderr. To change the active account for a host, see `gh auth switch`. ### Options `-a`, `--active` Display the active account only `-h`, `--hostname ` Check only a specific hostname's auth status `-t`, `--show-token` Display the auth token ### See also * [gh auth](./gh_auth) --- # GitHub CLI | Take GitHub to the command line CLI manual gh auth token ------------- gh auth token [flags] This command outputs the authentication token for an account on a given GitHub host. Without the `--hostname` flag, the default host is chosen. Without the `--user` flag, the active account for the host is chosen. ### Options `-h`, `--hostname ` The hostname of the GitHub instance authenticated with `-u`, `--user ` The account to output the token for ### See also * [gh auth](./gh_auth) --- # GitHub CLI | Take GitHub to the command line CLI manual gh browse --------- gh browse [ | | ] [flags] Transition from the terminal to the web browser to view and interact with: * Issues * Pull requests * Repository content * Repository home page * Repository settings ### Options `-b`, `--branch ` Select another branch by passing in the branch name `-c`, `--commit ` Select another commit by passing in the commit SHA, default is the last commit `-n`, `--no-browser` Print destination URL instead of opening the browser `-p`, `--projects` Open repository projects `-r`, `--releases` Open repository releases `-R`, `--repo <[HOST/]OWNER/REPO>` Select another repository using the \[HOST/\]OWNER/REPO format `-s`, `--settings` Open repository settings `-w`, `--wiki` Open repository wiki ### Examples $ gh browse #=> Open the home page of the current repository $ gh browse script/ #=> Open the script directory of the current repository $ gh browse 217 #=> Open issue or pull request 217 $ gh browse 77507cd94ccafcf568f8560cfecde965fcfa63 #=> Open commit page $ gh browse --settings #=> Open repository settings $ gh browse main.go:312 #=> Open main.go at line 312 $ gh browse main.go --branch bug-fix #=> Open main.go with the repository at head of bug-fix branch $ gh browse main.go --commit=77507cd94ccafcf568f8560cfecde965fcfa63 #=> Open main.go with the repository at commit 775007cd ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh cache -------- Work with GitHub Actions caches. ### Available commands * [gh cache delete](./gh_cache_delete) * [gh cache list](./gh_cache_list) ### Options `-R`, `--repo <[HOST/]OWNER/REPO>` Select another repository using the \[HOST/\]OWNER/REPO format ### Examples $ gh cache list $ gh cache delete --all ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh auth switch -------------- gh auth switch [flags] Switch the active account for a GitHub host. This command changes the authentication configuration that will be used when running commands targeting the specified GitHub host. If the specified host has two accounts, the active account will be switched automatically. If there are more than two accounts, disambiguation will be required either through the `--user` flag or an interactive prompt. For a list of authenticated accounts you can run `gh auth status`. ### Options `-h`, `--hostname ` The hostname of the GitHub instance to switch account for `-u`, `--user ` The account to switch to ### Examples # Select what host and account to switch to via a prompt $ gh auth switch # Switch the active account on a specific host to a specific user $ gh auth switch --hostname enterprise.internal --user monalisa ### See also * [gh auth](./gh_auth) --- # GitHub CLI | Take GitHub to the command line CLI manual gh cache list ------------- List GitHub Actions caches gh cache list [flags] ### Options `-q`, `--jq ` Filter JSON output using a jq expression `--json ` Output JSON with the specified fields `-k`, `--key ` Filter by cache key prefix `-L`, `--limit (default 30)` Maximum number of caches to fetch `-O`, `--order (default "desc")` Order of caches returned: {asc|desc} `-r`, `--ref ` Filter by ref, formatted as refs/heads/ or refs/pull//merge `-S`, `--sort (default "last_accessed_at")` Sort fetched caches: {created\_at|last\_accessed\_at|size\_in\_bytes} `-t`, `--template ` Format JSON output using a Go template; see "gh help formatting" ### Options inherited from parent commands `-R`, `--repo <[HOST/]OWNER/REPO>` Select another repository using the \[HOST/\]OWNER/REPO format ### ALIASES gh cache ls ### JSON Fields `createdAt`, `id`, `key`, `lastAccessedAt`, `ref`, `sizeInBytes`, `version` ### Examples # List caches for current repository $ gh cache list # List caches for specific repository $ gh cache list --repo cli/cli # List caches sorted by least recently accessed $ gh cache list --sort last_accessed_at --order asc # List caches that have keys matching a prefix (or that match exactly) $ gh cache list --key key-prefix # To list caches for a specific branch, replace with the actual branch name $ gh cache list --ref refs/heads/ # To list caches for a specific pull request, replace with the actual pull request number $ gh cache list --ref refs/pull//merge ### See also * [gh cache](./gh_cache) --- # GitHub CLI | Take GitHub to the command line CLI manual gh cache delete --------------- gh cache delete [| | --all] [flags] Delete GitHub Actions caches. Deletion requires authorization with the `repo` scope. ### Options `-a`, `--all` Delete all caches ### Options inherited from parent commands `-R`, `--repo <[HOST/]OWNER/REPO>` Select another repository using the \[HOST/\]OWNER/REPO format ### Examples # Delete a cache by id $ gh cache delete 1234 # Delete a cache by key $ gh cache delete cache-key # Delete a cache by id in a specific repo $ gh cache delete 1234 --repo cli/cli # Delete all caches $ gh cache delete --all ### See also * [gh cache](./gh_cache) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace ------------ Connect to and manage codespaces ### Available commands * [gh codespace code](./gh_codespace_code) * [gh codespace cp](./gh_codespace_cp) * [gh codespace create](./gh_codespace_create) * [gh codespace delete](./gh_codespace_delete) * [gh codespace edit](./gh_codespace_edit) * [gh codespace jupyter](./gh_codespace_jupyter) * [gh codespace list](./gh_codespace_list) * [gh codespace logs](./gh_codespace_logs) * [gh codespace ports](./gh_codespace_ports) * [gh codespace rebuild](./gh_codespace_rebuild) * [gh codespace ssh](./gh_codespace_ssh) * [gh codespace stop](./gh_codespace_stop) * [gh codespace view](./gh_codespace_view) ### ALIASES gh cs ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace code ----------------- Open a codespace in Visual Studio Code gh codespace code [flags] ### Options `-c`, `--codespace ` Name of the codespace `--insiders` Use the insiders version of Visual Studio Code `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) `-w`, `--web` Use the web version of Visual Studio Code ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace cp --------------- gh codespace cp [-e] [-r] [-- [...]] ... The `cp` command copies files between the local and remote file systems. As with the UNIX `cp` command, the first argument specifies the source and the last specifies the destination; additional sources may be specified after the first, if the destination is a directory. The `--recursive` flag is required if any source is a directory. A `remote:` prefix on any file name argument indicates that it refers to the file system of the remote (Codespace) machine. It is resolved relative to the home directory of the remote user. By default, remote file names are interpreted literally. With the `--expand` flag, each such argument is treated in the manner of `scp`, as a Bash expression to be evaluated on the remote machine, subject to expansion of tildes, braces, globs, environment variables, and backticks. For security, do not use this flag with arguments provided by untrusted users; see [https://lwn.net/Articles/835962/](https://lwn.net/Articles/835962/) for discussion. By default, the `cp` command will create a public/private ssh key pair to authenticate with the codespace inside the `~/.ssh directory`. ### Options `-c`, `--codespace ` Name of the codespace `-e`, `--expand` Expand remote file names on remote shell `-p`, `--profile ` Name of the SSH profile to use `-r`, `--recursive` Recursively copy directories `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) ### Examples $ gh codespace cp -e README.md 'remote:/workspaces/$RepositoryName/' $ gh codespace cp -e 'remote:~/*.go' ./gofiles/ $ gh codespace cp -e 'remote:/workspaces/myproj/go.{mod,sum}' ./gofiles/ $ gh codespace cp -e -- -F ~/.ssh/codespaces_config 'remote:~/*.go' ./gofiles/ ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace delete ------------------- gh codespace delete [flags] Delete codespaces based on selection criteria. All codespaces for the authenticated user can be deleted, as well as codespaces for a specific repository. Alternatively, only codespaces older than N days can be deleted. Organization administrators may delete any codespace billed to the organization. ### Options `--all` Delete all codespaces `-c`, `--codespace ` Name of the codespace `--days (default 0)` Delete codespaces older than N days `-f`, `--force` Skip confirmation for codespaces that contain unsaved changes `-o`, `--org ` The login handle of the organization (admin-only) `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) `-u`, `--user ` The username to delete codespaces for (used with --org) ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace create ------------------- Create a codespace gh codespace create [flags] ### Options `-b`, `--branch ` repository branch `--default-permissions` do not prompt to accept additional permissions requested by the codespace `--devcontainer-path ` path to the devcontainer.json file to use when creating codespace `-d`, `--display-name ` display name for the codespace (48 characters or less) `--idle-timeout ` allowed inactivity before codespace is stopped, e.g. "10m", "1h" `-l`, `--location ` location: {EastUs|SouthEastAsia|WestEurope|WestUs2} (determined automatically if not provided) `-m`, `--machine ` hardware specifications for the VM `-R`, `--repo ` repository name with owner: user/repo `--retention-period ` allowed time after shutting down before the codespace is automatically deleted (maximum 30 days), e.g. "1h", "72h" `-s`, `--status` show status of post-create command and dotfiles `-w`, `--web` create codespace from browser, cannot be used with --display-name, --idle-timeout, or --retention-period ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace edit ----------------- Edit a codespace gh codespace edit [flags] ### Options `-c`, `--codespace ` Name of the codespace `-d`, `--display-name ` Set the display name `-m`, `--machine ` Set hardware specifications for the VM `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace jupyter -------------------- Open a codespace in JupyterLab gh codespace jupyter [flags] ### Options `-c`, `--codespace ` Name of the codespace `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace list ----------------- gh codespace list [flags] List codespaces of the authenticated user. Alternatively, organization administrators may list all codespaces billed to the organization. ### Options `-q`, `--jq ` Filter JSON output using a jq expression `--json ` Output JSON with the specified fields `-L`, `--limit (default 30)` Maximum number of codespaces to list `-o`, `--org ` The login handle of the organization to list codespaces for (admin-only) `-R`, `--repo ` Repository name with owner: user/repo `-t`, `--template ` Format JSON output using a Go template; see "gh help formatting" `-u`, `--user ` The username to list codespaces for (used with --org) `-w`, `--web` List codespaces in the web browser, cannot be used with --user or --org ### ALIASES gh cs ls, gh codespace ls ### JSON Fields `createdAt`, `displayName`, `gitStatus`, `lastUsedAt`, `machineName`, `name`, `owner`, `repository`, `state`, `vscsTarget` ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace ports forward -------------------------- Forward ports gh codespace ports forward :... ### Options inherited from parent commands `-c`, `--codespace ` Name of the codespace `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) ### See also * [gh codespace ports](./gh_codespace_ports) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace ports ------------------ List ports in a codespace gh codespace ports [flags] ### Available commands * [gh codespace ports forward](./gh_codespace_ports_forward) * [gh codespace ports visibility](./gh_codespace_ports_visibility) ### Options `-c`, `--codespace ` Name of the codespace `-q`, `--jq ` Filter JSON output using a jq expression `--json ` Output JSON with the specified fields `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) `-t`, `--template ` Format JSON output using a Go template; see "gh help formatting" ### JSON Fields `browseUrl`, `label`, `sourcePort`, `visibility` ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace logs ----------------- Access codespace logs gh codespace logs [flags] ### Options `-c`, `--codespace ` Name of the codespace `-f`, `--follow` Tail and follow the logs `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace rebuild -------------------- gh codespace rebuild [flags] Rebuilding recreates your codespace. Your code and any current changes will be preserved. Your codespace will be rebuilt using your working directory's dev container. A full rebuild also removes cached Docker images. ### Options `-c`, `--codespace ` Name of the codespace `--full` perform a full rebuild `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace ports visibility ----------------------------- Change the visibility of the forwarded port gh codespace ports visibility :{public|private|org}... ### Options inherited from parent commands `-c`, `--codespace ` Name of the codespace `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) ### Examples gh codespace ports visibility 80:org 3000:private 8000:public ### See also * [gh codespace ports](./gh_codespace_ports) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace stop ----------------- Stop a running codespace gh codespace stop [flags] ### Options `-c`, `--codespace ` Name of the codespace `-o`, `--org ` The login handle of the organization (admin-only) `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) `-u`, `--user ` The username to stop codespace for (used with --org) ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace ssh ---------------- gh codespace ssh [...] [-- ...] [] The `ssh` command is used to SSH into a codespace. In its simplest form, you can run `gh cs ssh`, select a codespace interactively, and connect. The `ssh` command will automatically create a public/private ssh key pair in the `~/.ssh` directory if you do not have an existing valid key pair. When selecting the key pair to use, the preferred order is: 1. Key specified by `-i` in `` 2. Automatic key, if it already exists 3. First valid key pair in ssh config (according to `ssh -G`) 4. Automatic key, newly created The `ssh` command also supports deeper integration with OpenSSH using a `--config` option that generates per-codespace ssh configuration in OpenSSH format. Including this configuration in your `~/.ssh/config` improves the user experience of tools that integrate with OpenSSH, such as Bash/Zsh completion of ssh hostnames, remote path completion for `scp/rsync/sshfs`, `git` ssh remotes, and so on. Once that is set up (see the second example below), you can ssh to codespaces as if they were ordinary remote hosts (using `ssh`, not `gh cs ssh`). Note that the codespace you are connecting to must have an SSH server pre-installed. If the docker image being used for the codespace does not have an SSH server, install it in your `Dockerfile` or, for codespaces that use Debian-based images, you can add the following to your `devcontainer.json`: "features": { "ghcr.io/devcontainers/features/sshd:1": { "version": "latest" } } ### Options `-c`, `--codespace ` Name of the codespace `--config` Write OpenSSH configuration to stdout `-d`, `--debug` Log debug data to a file `--debug-file ` Path of the file log to `--profile ` Name of the SSH profile to use `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) `--server-port (default 0)` SSH server port number (0 => pick unused) ### Examples $ gh codespace ssh $ gh codespace ssh --config > ~/.ssh/codespaces $ printf 'Match all\nInclude ~/.ssh/codespaces\n' >> ~/.ssh/config ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh codespace view ----------------- View details about a codespace gh codespace view [flags] ### Options `-c`, `--codespace ` Name of the codespace `-q`, `--jq ` Filter JSON output using a jq expression `--json ` Output JSON with the specified fields `-R`, `--repo ` Filter codespace selection by repository name (user/repo) `--repo-owner ` Filter codespace selection by repository owner (username or org) `-t`, `--template ` Format JSON output using a Go template; see "gh help formatting" ### JSON Fields `billableOwner`, `createdAt`, `devcontainerPath`, `displayName`, `environmentId`, `gitStatus`, `idleTimeoutMinutes`, `lastUsedAt`, `location`, `machineDisplayName`, `machineName`, `name`, `owner`, `prebuild`, `recentFolders`, `repository`, `retentionExpiresAt`, `retentionPeriodDays`, `state`, `vscsTarget` ### Examples # select a codespace from a list of all codespaces you own $ gh cs view # view the details of a specific codespace $ gh cs view -c codespace-name-12345 # view the list of all available fields for a codespace $ gh cs view --json # view specific fields for a codespace $ gh cs view --json displayName,machineDisplayName,state ### See also * [gh codespace](./gh_codespace) --- # GitHub CLI | Take GitHub to the command line CLI manual gh completion ------------- gh completion -s Generate shell completion scripts for GitHub CLI commands. When installing GitHub CLI through a package manager, it's possible that no additional shell configuration is necessary to gain completion support. For Homebrew, see [https://docs.brew.sh/Shell-Completion](https://docs.brew.sh/Shell-Completion) If you need to set up completions manually, follow the instructions below. The exact config file locations might vary based on your system. Make sure to restart your shell before testing whether completions are working. ### bash First, ensure that you install `bash-completion` using your package manager. After, add this to your `~/.bash_profile`: eval "$(gh completion -s bash)" ### zsh Generate a `_gh` completion script and put it somewhere in your `$fpath`: gh completion -s zsh > /usr/local/share/zsh/site-functions/_gh Ensure that the following is present in your `~/.zshrc`: autoload -U compinit compinit -i Zsh version 5.7 or later is recommended. ### fish Generate a `gh.fish` completion script: gh completion -s fish > ~/.config/fish/completions/gh.fish ### PowerShell Open your profile script with: mkdir -Path (Split-Path -Parent $profile) -ErrorAction SilentlyContinue notepad $profile Add the line and save the file: Invoke-Expression -Command $(gh completion -s powershell | Out-String) ### Options `-s`, `--shell ` Shell type: {bash|zsh|fish|powershell} ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh config --------- Display or change configuration settings for gh. Current respected settings: * `git_protocol`: the protocol to use for git clone and push operations {https|ssh} (default https) * `editor`: the text editor program to use for authoring text * `prompt`: toggle interactive prompting in the terminal {enabled|disabled} (default enabled) * `prefer_editor_prompt`: toggle preference for editor-based interactive prompting in the terminal {enabled|disabled} (default disabled) * `pager`: the terminal pager program to send standard output to * `http_unix_socket`: the path to a Unix socket through which to make an HTTP connection * `browser`: the web browser to use for opening URLs ### Available commands * [gh config clear-cache](./gh_config_clear-cache) * [gh config get](./gh_config_get) * [gh config list](./gh_config_list) * [gh config set](./gh_config_set) ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh config clear-cache --------------------- Clear the cli cache gh config clear-cache ### Examples # Clear the cli cache $ gh config clear-cache ### See also * [gh config](./gh_config) --- # GitHub CLI | Take GitHub to the command line CLI manual gh config get ------------- Print the value of a given configuration key gh config get [flags] ### Options `-h`, `--host ` Get per-host setting ### Examples $ gh config get git_protocol https ### See also * [gh config](./gh_config) --- # GitHub CLI | Take GitHub to the command line CLI manual gh config list -------------- Print a list of configuration keys and values gh config list [flags] ### Options `-h`, `--host ` Get per-host configuration ### ALIASES gh config ls ### See also * [gh config](./gh_config) --- # GitHub CLI | Take GitHub to the command line CLI manual gh config set ------------- Update configuration with a value for the given key gh config set [flags] ### Options `-h`, `--host ` Set per-host setting ### Examples $ gh config set editor vim $ gh config set editor "code --wait" $ gh config set git_protocol ssh --host github.com $ gh config set prompt disabled ### See also * [gh config](./gh_config) --- # GitHub CLI | Take GitHub to the command line CLI manual gh extension ------------ GitHub CLI extensions are repositories that provide additional gh commands. The name of the extension repository must start with `gh-` and it must contain an executable of the same name. All arguments passed to the `gh ` invocation will be forwarded to the `gh-` executable of the extension. An extension cannot override any of the core gh commands. If an extension name conflicts with a core gh command, you can use `gh extension exec `. When an extension is executed, gh will check for new versions once every 24 hours and display an upgrade notice. See `gh help environment` for information on disabling extension notices. For the list of available extensions, see [https://github.com/topics/gh-extension](https://github.com/topics/gh-extension) . ### Available commands * [gh extension browse](./gh_extension_browse) * [gh extension create](./gh_extension_create) * [gh extension exec](./gh_extension_exec) * [gh extension install](./gh_extension_install) * [gh extension list](./gh_extension_list) * [gh extension remove](./gh_extension_remove) * [gh extension search](./gh_extension_search) * [gh extension upgrade](./gh_extension_upgrade) ### ALIASES gh ext, gh extensions ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh extension browse ------------------- gh extension browse [flags] This command will take over your terminal and run a fully interactive interface for browsing, adding, and removing gh extensions. A terminal width greater than 100 columns is recommended. To learn how to control this interface, press `?` after running to see the help text. Press `q` to quit. Running this command with `--single-column` should make this command more intelligible for users who rely on assistive technology like screen readers or high zoom. For a more traditional way to discover extensions, see: gh ext search along with `gh ext install`, `gh ext remove`, and `gh repo view`. ### Options `--debug` log to /tmp/extBrowse-\* `-s`, `--single-column` Render TUI with only one column of text ### See also * [gh extension](./gh_extension) --- # GitHub CLI | Take GitHub to the command line CLI manual gh extension create ------------------- Create a new extension gh extension create [] [flags] ### Options `--precompiled ` Create a precompiled extension. Possible values: go, other ### Examples # Use interactively gh extension create # Create a script-based extension gh extension create foobar # Create a Go extension gh extension create --precompiled=go foobar # Create a non-Go precompiled extension gh extension create --precompiled=other foobar ### See also * [gh extension](./gh_extension) --- # GitHub CLI | Take GitHub to the command line CLI manual gh extension exec ----------------- gh extension exec [args] Execute an extension using the short name. For example, if the extension repository is `owner/gh-extension`, you should pass `extension`. You can use this command when the short name conflicts with a core gh command. All arguments after the extension name will be forwarded to the executable of the extension. ### Examples # execute a label extension instead of the core gh label command $ gh extension exec label ### See also * [gh extension](./gh_extension) --- # GitHub CLI | Take GitHub to the command line CLI manual gh extension install -------------------- gh extension install [flags] Install a GitHub CLI extension from a GitHub or local repository. For GitHub repositories, the repository argument can be specified in `OWNER/REPO` format or as a full repository URL. The URL format is useful when the repository is not hosted on github.com. For remote repositories, the GitHub CLI first looks for the release artifacts assuming that it's a binary extension i.e. prebuilt binaries provided as part of the release. In the absence of a release, the repository itself is cloned assuming that it's a script extension i.e. prebuilt executable or script exists on its root. The `--pin` flag may be used to specify a tag or commit for binary and script extensions respectively, the latest version is used otherwise. For local repositories, often used while developing extensions, use `.` as the value of the repository argument. Note the following: * After installing an extension from a locally cloned repository, the GitHub CLI will manage this extension as a symbolic link (or equivalent mechanism on Windows) pointing to an executable file with the same name as the repository in the repository's root. For example, if the repository is named `gh-foobar`, the symbolic link will point to `gh-foobar` in the extension repository's root. * When executing the extension, the GitHub CLI will run the executable file found by following the symbolic link. If no executable file is found, the extension will fail to execute. * If the extension is precompiled, the executable file must be built manually and placed in the repository's root. For the list of available extensions, see [https://github.com/topics/gh-extension](https://github.com/topics/gh-extension) . ### Options `--force` force upgrade extension, or ignore if latest already installed `--pin ` pin extension to a release tag or commit ref ### Examples # Install an extension from a remote repository hosted on GitHub $ gh extension install owner/gh-extension # Install an extension from a remote repository via full URL $ gh extension install https://my.ghes.com/owner/gh-extension # Install an extension from a local repository in the current working directory $ gh extension install . ### See also * [gh extension](./gh_extension) --- # GitHub CLI | Take GitHub to the command line CLI manual gh extension list ----------------- List installed extension commands gh extension list ### ALIASES gh extension ls, gh extensions ls, gh ext ls ### See also * [gh extension](./gh_extension) --- # GitHub CLI | Take GitHub to the command line CLI manual gh extension remove ------------------- Remove an installed extension gh extension remove ### See also * [gh extension](./gh_extension) --- # GitHub CLI | Take GitHub to the command line CLI manual gh extension search ------------------- gh extension search [] [flags] Search for gh extensions. With no arguments, this command prints out the first 30 extensions available to install sorted by number of stars. More extensions can be fetched by specifying a higher limit with the `--limit` flag. When connected to a terminal, this command prints out three columns. The first has a ✓ if the extension is already installed locally. The second is the full name of the extension repository in `OWNER/REPO` format. The third is the extension's description. When not connected to a terminal, the ✓ character is rendered as the word "installed" but otherwise the order and content of the columns are the same. This command behaves similarly to `gh search repos` but does not support as many search qualifiers. For a finer grained search of extensions, try using: gh search repos --topic "gh-extension" and adding qualifiers as needed. See `gh help search repos` to learn more about repository search. For listing just the extensions that are already installed locally, see: gh ext list ### Options `-q`, `--jq ` Filter JSON output using a jq expression `--json ` Output JSON with the specified fields `--license ` Filter based on license type `-L`, `--limit (default 30)` Maximum number of extensions to fetch `--order (default "desc")` Order of repositories returned, ignored unless '--sort' flag is specified: {asc|desc} `--owner ` Filter on owner `--sort (default "best-match")` Sort fetched repositories: {forks|help-wanted-issues|stars|updated} `-t`, `--template ` Format JSON output using a Go template; see "gh help formatting" `-w`, `--web` Open the search query in the web browser ### JSON Fields `createdAt`, `defaultBranch`, `description`, `forksCount`, `fullName`, `hasDownloads`, `hasIssues`, `hasPages`, `hasProjects`, `hasWiki`, `homepage`, `id`, `isArchived`, `isDisabled`, `isFork`, `isPrivate`, `language`, `license`, `name`, `openIssuesCount`, `owner`, `pushedAt`, `size`, `stargazersCount`, `updatedAt`, `url`, `visibility`, `watchersCount` ### Examples # List the first 30 extensions sorted by star count, descending $ gh ext search # List more extensions $ gh ext search --limit 300 # List extensions matching the term "branch" $ gh ext search branch # List extensions owned by organization "github" $ gh ext search --owner github # List extensions, sorting by recently updated, ascending $ gh ext search --sort updated --order asc # List extensions, filtering by license $ gh ext search --license MIT # Open search results in the browser $ gh ext search -w ### See also * [gh extension](./gh_extension) --- # GitHub CLI | Take GitHub to the command line CLI manual gh extension upgrade -------------------- Upgrade installed extensions gh extension upgrade { | --all} [flags] ### Options `--all` Upgrade all extensions `--dry-run` Only display upgrades `--force` Force upgrade extension ### See also * [gh extension](./gh_extension) --- # GitHub CLI | Take GitHub to the command line CLI manual gh gist ------- Work with GitHub gists. ### Available commands * [gh gist clone](./gh_gist_clone) * [gh gist create](./gh_gist_create) * [gh gist delete](./gh_gist_delete) * [gh gist edit](./gh_gist_edit) * [gh gist list](./gh_gist_list) * [gh gist rename](./gh_gist_rename) * [gh gist view](./gh_gist_view) ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh gist clone ------------- gh gist clone [] [-- ...] Clone a GitHub gist locally. A gist can be supplied as argument in either of the following formats: * by ID, e.g. `5b0e0062eb8e9654adad7bb1d81cc75f` * by URL, e.g. `https://gist.github.com/OWNER/5b0e0062eb8e9654adad7bb1d81cc75f` Pass additional `git clone` flags by listing them after `--`. ### See also * [gh gist](./gh_gist) --- # GitHub CLI | Take GitHub to the command line CLI manual gh gist create -------------- gh gist create [... | -] [flags] Create a new GitHub gist with given contents. Gists can be created from one or multiple files. Alternatively, pass `-` as file name to read from standard input. By default, gists are secret; use `--public` to make publicly listed ones. ### Options `-d`, `--desc ` A description for this gist `-f`, `--filename ` Provide a filename to be used when reading from standard input `-p`, `--public` List the gist publicly (default "secret") `-w`, `--web` Open the web browser with created gist ### ALIASES gh gist new ### Examples # publish file 'hello.py' as a public gist $ gh gist create --public hello.py # create a gist with a description $ gh gist create hello.py -d "my Hello-World program in Python" # create a gist containing several files $ gh gist create hello.py world.py cool.txt # read from standard input to create a gist $ gh gist create - # create a gist from output piped from another command $ cat cool.txt | gh gist create ### See also * [gh gist](./gh_gist) --- # GitHub CLI | Take GitHub to the command line CLI manual gh gist delete -------------- gh gist delete { | } [flags] Delete a GitHub gist. To delete a gist interactively, use `gh gist delete` with no arguments. To delete a gist non-interactively, supply the gist id or url. ### Options `--yes` confirm deletion without prompting ### Examples # delete a gist interactively gh gist delete # delete a gist non-interactively gh gist delete 1234 ### See also * [gh gist](./gh_gist) --- # GitHub CLI | Take GitHub to the command line CLI manual gh gist edit ------------ Edit one of your gists gh gist edit { | } [] [flags] ### Options `-a`, `--add ` Add a new file to the gist `-d`, `--desc ` New description for the gist `-f`, `--filename ` Select a file to edit `-r`, `--remove ` Remove a file from the gist ### See also * [gh gist](./gh_gist) --- # GitHub CLI | Take GitHub to the command line CLI manual gh gist list ------------ gh gist list [flags] List gists from your user account. You can use a regular expression to filter the description, file names, or even the content of files in the gist using `--filter`. For supported regular expression syntax, see [https://pkg.go.dev/regexp/syntax](https://pkg.go.dev/regexp/syntax) . Use `--include-content` to include content of files, noting that this will be slower and increase the rate limit used. Instead of printing a table, code will be printed with highlights similar to `gh search code`: {{gist ID}} {{file name}} {{description}} {{matching lines from content}} No highlights or other color is printed when output is redirected. ### Options `--filter ` Filter gists using a regular expression `--include-content` Include gists' file content when filtering `-L`, `--limit (default 10)` Maximum number of gists to fetch `--public` Show only public gists `--secret` Show only secret gists ### ALIASES gh gist ls ### Examples # list all secret gists from your user account $ gh gist list --secret # find all gists from your user account mentioning "octo" anywhere $ gh gist list --filter octo --include-content ### See also * [gh gist](./gh_gist) --- # GitHub CLI | Take GitHub to the command line CLI manual gh gist rename -------------- gh gist rename { | } Rename a file in the given gist ID / URL. ### See also * [gh gist](./gh_gist) --- # GitHub CLI | Take GitHub to the command line CLI manual gh gpg-key delete ----------------- Delete a GPG key from your GitHub account gh gpg-key delete [flags] ### Options `-y`, `--yes` Skip the confirmation prompt ### See also * [gh gpg-key](./gh_gpg-key) --- # GitHub CLI | Take GitHub to the command line CLI manual gh gist view ------------ gh gist view [ | ] [flags] View the given gist or select from recent gists. ### Options `-f`, `--filename ` Display a single file from the gist `--files` List file names from the gist `-r`, `--raw` Print raw instead of rendered gist contents `-w`, `--web` Open gist in the browser ### See also * [gh gist](./gh_gist) --- # GitHub CLI | Take GitHub to the command line CLI manual gh gpg-key ---------- Manage GPG keys registered with your GitHub account. ### Available commands * [gh gpg-key add](./gh_gpg-key_add) * [gh gpg-key delete](./gh_gpg-key_delete) * [gh gpg-key list](./gh_gpg-key_list) ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh help ------- gh help [command] Help provides help for any command in the application. Simply type gh help \[path to command\] for full details. ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh environment -------------- `GH_TOKEN`, `GITHUB_TOKEN` (in order of precedence): an authentication token that will be used when a command targets either github.com or a subdomain of ghe.com. Setting this avoids being prompted to authenticate and takes precedence over previously stored credentials. `GH_ENTERPRISE_TOKEN`, `GITHUB_ENTERPRISE_TOKEN` (in order of precedence): an authentication token that will be used when a command targets a GitHub Enterprise Server host. `GH_HOST`: specify the GitHub hostname for commands where a hostname has not been provided, or cannot be inferred from the context of a local Git repository. If this host was previously authenticated with, the stored credentials will be used. Otherwise, setting `GH_TOKEN` or `GH_ENTERPRISE_TOKEN` is required, depending on the targeted host. `GH_REPO`: specify the GitHub repository in the `[HOST/]OWNER/REPO` format for commands that otherwise operate on a local repository. `GH_EDITOR`, `GIT_EDITOR`, `VISUAL`, `EDITOR` (in order of precedence): the editor tool to use for authoring text. `GH_BROWSER`, `BROWSER` (in order of precedence): the web browser to use for opening links. `GH_DEBUG`: set to a truthy value to enable verbose output on standard error. Set to `api` to additionally log details of HTTP traffic. `DEBUG` (deprecated): set to `1`, `true`, or `yes` to enable verbose output on standard error. `GH_PAGER`, `PAGER` (in order of precedence): a terminal paging program to send standard output to, e.g. `less`. `GLAMOUR_STYLE`: the style to use for rendering Markdown. See [https://github.com/charmbracelet/glamour#styles](https://github.com/charmbracelet/glamour#styles) `NO_COLOR`: set to any value to avoid printing ANSI escape sequences for color output. `CLICOLOR`: set to `0` to disable printing ANSI colors in output. `CLICOLOR_FORCE`: set to a value other than `0` to keep ANSI colors in output even when the output is piped. `GH_FORCE_TTY`: set to any value to force terminal-style output even when the output is redirected. When the value is a number, it is interpreted as the number of columns available in the viewport. When the value is a percentage, it will be applied against the number of columns available in the current viewport. `GH_NO_UPDATE_NOTIFIER`: set to any value to disable GitHub CLI update notifications. When any command is executed, gh checks for new versions once every 24 hours. If a newer version was found, an upgrade notice is displayed on standard error. `GH_NO_EXTENSION_UPDATE_NOTIFIER`: set to any value to disable GitHub CLI extension update notifications. When an extension is executed, gh checks for new versions for the executed extension once every 24 hours. If a newer version was found, an upgrade notice is displayed on standard error. `GH_CONFIG_DIR`: the directory where gh will store configuration files. If not specified, the default value will be one of the following paths (in order of precedence): * `$XDG_CONFIG_HOME/gh` (if `$XDG_CONFIG_HOME` is set), * `$AppData/GitHub CLI` (on Windows if `$AppData` is set), or * `$HOME/.config/gh`. `GH_PROMPT_DISABLED`: set to any value to disable interactive prompting in the terminal. `GH_PATH`: set the path to the gh executable, useful for when gh can not properly determine its own path such as in the cygwin terminal. `GH_MDWIDTH`: default maximum width for markdown render wrapping. The max width of lines wrapped on the terminal will be taken as the lesser of the terminal width, this value, or 120 if not specified. This value is used, for example, with `pr view` subcommand. ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh gpg-key add -------------- Add a GPG key to your GitHub account gh gpg-key add [] [flags] ### Options `-t`, `--title ` Title for the new key ### See also * [gh gpg-key](./gh_gpg-key) --- # GitHub CLI | Take GitHub to the command line CLI manual gh exit-codes ------------- gh follows normal conventions regarding exit codes. * If a command completes successfully, the exit code will be 0 * If a command fails for any reason, the exit code will be 1 * If a command is running but gets cancelled, the exit code will be 2 * If a command requires authentication, the exit code will be 4 NOTE: It is possible that a particular command may have more exit codes, so it is a good practice to check documentation for the command if you are relying on exit codes to control some behavior. ### See also * [gh](./gh) --- # GitHub CLI | Take GitHub to the command line CLI manual gh gpg-key list --------------- Lists GPG keys in your GitHub account gh gpg-key list ### ALIASES gh gpg-key ls ### See also * [gh gpg-key](./gh_gpg-key) --- # GitHub CLI | Take GitHub to the command line CLI manual gh formatting ------------- By default, the result of `gh` commands are output in line-based plain text format. Some commands support passing the `--json` flag, which converts the output to JSON format. Once in JSON, the output can be further formatted according to a required formatting string by adding either the `--jq` or `--template` flag. This is useful for selecting a subset of data, creating new data structures, displaying the data in a different format, or as input to another command line script. The `--json` flag requires a comma separated list of fields to fetch. To view the possible JSON field names for a command omit the string argument to the `--json` flag when you run the command. Note that you must pass the `--json` flag and field names to use the `--jq` or `--template` flags. The `--jq` flag requires a string argument in jq query syntax, and will only print those JSON values which match the query. jq queries can be used to select elements from an array, fields from an object, create a new array, and more. The `jq` utility does not need to be installed on the system to use this formatting directive. When connected to a terminal, the output is automatically pretty-printed. To learn about jq query syntax, see: [https://jqlang.github.io/jq/manual/](https://jqlang.github.io/jq/manual/) The `--template` flag requires a string argument in Go template syntax, and will only print those JSON values which match the query. In addition to the Go template functions in the standard library, the following functions can be used with this formatting directive: * `autocolor`: like `color`, but only emits color to terminals * `color