gh-cli

# GitHub CLI (gh) Comprehensive reference for GitHub CLI (gh) - work seamlessly with GitHub from the command line. **Version:** 2.85.0 (current as of January 2026) ## Prerequisites ### Installation ```bash # macOS brew install gh # Linux curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null sudo apt update sudo apt install gh # Windows winget install --id GitHub.cli # Verify installation gh --version ``` ### Authentication ```bash # Interactive login (default: github.com) gh auth login # Login with specific hostname gh auth login --hostname enterprise.internal # Login with token gh auth login --with-token < mytoken.txt # Check authentication status gh auth status # Switch accounts gh auth switch --hostname github.com --user username # Logout gh auth logout --hostname github.com --user username ``` ### Setup Git Integration ```bash # Configure git to use gh as credential helper gh auth setup-git # View active token gh auth token # Refresh authentication scopes gh auth refresh --scopes write:org,read:public_key ``` ## CLI Structure ``` gh # Root command ├── auth # Authentication │ ├── login │ ├── logout │ ├── refresh │ ├── setup-git │ ├── status │ ├── switch │ └── token ├── browse # Open in browser ├── codespace # GitHub Codespaces │ ├── code │ ├── cp │ ├── create │ ├── delete │ ├── edit │ ├── jupyter │ ├── list │ ├── logs │ ├── ports │ ├── rebuild │ ├── ssh │ ├── stop │ └── view ├── gist # Gists │ ├── clone │ ├── create │ ├── delete │ ├── edit │ ├── list │ ├── rename │ └── view ├── issue # Issues │ ├── create │ ├── list │ ├── status │ ├── close │ ├── comment │ ├── delete │ ├── develop │ ├── edit │ ├── lock │ ├── pin │ ├── reopen │ ├── transfer │ ├── unlock │ └── view ├── org # Organizations │ └── list ├── pr # Pull Requests │ ├── create │ ├── list │ ├── status │ ├── checkout │ ├── checks │ ├── close │ ├── comment │ ├── diff │ ├── edit │ ├── lock │ ├── merge │ ├── ready │ ├── reopen │ ├── revert │ ├── review │ ├── unlock │ ├── update-branch │ └── view ├── project # Projects │ ├── close │ ├── copy │ ├── create │ ├── delete │ ├── edit │ ├── field-create │ ├── field-delete │ ├── field-list │ ├── item-add │ ├── item-archive │ ├── item-create │ ├── item-delete │ ├── item-edit │ ├── item-list │ ├── link │ ├── list │ ├── mark-template │ ├── unlink │ └── view ├── release # Releases │ ├── create │ ├── list │ ├── delete │ ├── delete-asset │ ├── download │ ├── edit │ ├── upload │ ├── verify │ ├── verify-asset │ └── view ├── repo # Repositories │ ├── create │ ├── list │ ├── archive │ ├── autolink │ ├── clone │ ├── delete │ ├── deploy-key │ ├── edit │ ├── fork │ ├── gitignore │ ├── license │ ├── rename │ ├── set-default │ ├── sync │ ├── unarchive │ └── view ├── cache # Actions caches │ ├── delete │ └── list ├── run # Workflow runs │ ├── cancel │ ├── delete │ ├── download │ ├── list │ ├── rerun │ ├── view │ └── watch ├── workflow # Workflows │ ├── disable │ ├── enable │ ├── list │ ├── run │ └── view ├── agent-task # Agent tasks ├── alias # Command aliases │ ├── delete │ ├── import │ ├── list │ └── set ├── api # API requests ├── attestation # Artifact attestations │ ├── download │ ├── trusted-root │ └── verify ├── completion # Shell completion ├── config # Configuration │ ├── clear-cache │ ├── get │ ├── list │ └── set ├── extension # Extensions │ ├── browse │ ├── create │ ├── exec │ ├── install │ ├── list │ ├── remove │ ├── search │ └── upgrade ├── gpg-key # GPG keys │ ├── add │ ├── delete │ └── list ├── label # Labels │ ├── clone │ ├── create │ ├── delete │ ├── edit │ └── list ├── preview # Preview features ├── ruleset # Rulesets │ ├── check │ ├── list │ └── view ├── search # Search │ ├── code │ ├── commits │ ├── issues │ ├── prs │ └── repos ├── secret # Secrets │ ├── delete │ ├── list │ └── set ├── ssh-key # SSH keys │ ├── add │ ├── delete │ └── list ├── status # Status overview └── variable # Variables ├── delete ├── get ├── list └── set ``` ## Configuration ### Global Configuration ```bash # List all configuration gh config list # Get specific configuration value gh config list git_protocol gh config get editor # Set configuration value gh config set editor vim gh config set git_protocol ssh gh config set prompt disabled gh config set pager "less -R" # Clear configuration cache gh config clear-cache ``` ### Environment Variables ```bash # GitHub token (for automation) export GH_TOKEN=<YOUR_GITHUB_TOKEN> # 請替換為你的實際 token，切勿提交到版控 # GitHub hostname export GH_HOST=github.com # Disable prompts export GH_PROMPT_DISABLED=true # Custom editor export GH_EDITOR=vim # Custom pager export GH_PAGER=less # HTTP timeout export GH_TIMEOUT=30 # Custom repository (override default) export GH_REPO=owner/repo # Custom git protocol export GH_ENTERPRISE_HOSTNAME=hostname ``` ## Authentication (gh auth) ### Login ```bash # Interactive login gh auth login # Web-based authentication gh auth login --web # With clipboard for OAuth code gh auth login --web --clipboard # With specific git protocol gh auth login --git-protocol ssh # With custom hostname (GitHub Enterprise) gh auth login --hostname enterprise.internal # Login with token from stdin gh auth login --with-token < token.txt # Insecure storage (plain text) gh auth login --insecure-storage ``` ### Status ```bash # Show all authentication status gh auth status # Show active account only gh auth status --active # Show specific hostname gh auth status --hostname github.com # Show token in output gh auth status --show-token # JSON output gh auth status --json hosts # Filter with jq gh auth status --json hosts --jq '.hosts | add' ``` ### Switch Accounts ```bash # Interactive switch gh auth switch # Switch to specific user/host gh auth switch --hostname github.com --user monalisa ``` ### Token ```bash # Print authentication token gh auth token # Token for specific host/user gh auth token --hostname github.com --user monalisa ``` ### Refresh ```bash # Refresh credentials gh auth refresh # Add scopes gh auth refresh --scopes write:org,read:public_key # Remove scopes gh auth refresh --remove-scopes delete_repo # Reset to default scopes gh auth refresh --reset-scopes # With clipboard gh auth refresh --clipboard ``` ### Setup Git ```bash # Setup git credential helper gh auth setup-git # Setup for specific host gh auth setup-git --hostname enterprise.internal # Force setup even if host not known gh auth setup-git --hostname enterprise.internal --force ``` ## Browse (gh browse) ```bash # Open repository in browser gh browse # Open specific path gh browse script/ gh browse main.go:312 # Open issue or PR gh browse 123 # Open commit gh browse 77507cd94ccafcf568f8560cfecde965fcfa63 # Open with specific branch gh browse main.go --branch bug-fix # Open different repository gh browse --repo owner/repo # Open specific pages gh browse --actions # Actions tab gh browse --projects # Projects tab gh browse --releases # Releases tab gh browse --settings # Settings page gh browse --wiki # Wiki page # Print URL instead of opening gh browse --no-browser ``` ## Repositories (gh repo) ### Create Repository ```bash # Create new repository gh repo create my-repo # Create with description gh repo create my-repo --description "My awesome project" # Create public repository gh repo create my-repo --public # Create private repository gh repo create my-repo --private # Create with homepage gh repo create my-repo --homepage https://example.com # Create with license gh repo create my-repo --license mit # Create with gitignore gh repo create my-repo --gitignore python # Initialize as template repository gh repo create my-repo --template # Create repository in organization gh repo create org/my-repo # Create without cloning locally gh repo create my-repo --source=. # Disable issues gh repo create my-repo --disable-issues # Disable wiki gh repo create my-repo --disable-wiki ``` ### Clone Repository ```bash # Clone repository gh repo clone owner/repo # Clone to specific directory gh repo clone owner/repo my-directory # Clone with different branch gh repo clone owner/repo --branch develop ``` ### List Repositories ```bash # List all repositories gh repo list # List repositories for owner gh repo list owner # Limit results gh repo list --limit 50 # Public repositories only gh repo list --public # Source repositories only (not forks) gh repo list --source # JSON output gh repo list --json name,visibility,owner # Table output gh repo list --limit 100 | tail -n +2 # Filter with jq gh repo list --json name --jq '.[].name' ``` ### View Repository ```bash # View repository details gh repo view # View specific repository gh repo view owner/repo # JSON output gh repo view --json name,description,defaultBranchRef # View in browser gh repo view --web ``` ### Edit Repository ```bash # Edit description gh repo edit --description "New description" # Set homepage gh repo edit --homepage https://example.com # Change visibility gh repo edit --visibility private gh repo edit --visibility public # Enable/disable features gh repo edit --enable-issues gh repo edit --disable-issues gh repo edit --enable-wiki gh repo edit --disable-wiki gh repo edit --enable-projects gh repo edit --disable-projects # Set default branch gh repo edit --default-branch main # Rename repository gh repo rename new-name # Archive repository gh repo archive gh repo unarchive ``` ### Delete Repository ```bash # Delete repository gh repo delete owner/repo # Confirm without prompt gh repo delete owner/repo --yes ``` ### Fork Repository ```bash # Fork repository gh repo fork owner/repo # Fork to organization gh repo fork owner/repo --org org-name # Clone after forking gh repo fork owner/repo --clone # Remote name for fork gh repo fork owner/repo --remote-name upstream ``` ### Sync Fork ```bash # Sync fork with upstream gh repo sync # Sync specific branch gh repo sync --branch feature # Force sync gh repo sync --force ``` ### Set Default Repository ```bash # Set default repository for current directory gh repo set-default # Set default explicitly gh repo set-default owner/repo # Unset default gh repo set-default --unset ``` ### Repository Autolinks ```bash # List autolinks gh repo autolink list # Add autolink gh repo autolink add \ --key-prefix JIRA- \ --url-template https://jira.example.com/browse/<num> # Delete autolink gh repo autolink delete 12345 ``` ### Repository Deploy Keys ```bash # List deploy keys gh repo deploy-key list # Add deploy key gh repo deploy-key add ~/.ssh/id_rsa.pub \ --title "Production server" \ --read-only # Delete deploy key gh repo deploy-key delete 12345 ``` ### Gitignore and License ```bash # View gitignore template gh repo gitignore # View license template gh repo license mit # License with full name gh repo license mit --fullname "John Doe" ``` ## Issues (gh issue) ### Create Issue ```bash # Create issue interactively gh issue create # Create with title gh issue create --title "Bug: Login not working" # Create with title and body gh issue create \ --title "Bug: Login not working" \ --body "Steps to reproduce..." # Create with body from file gh issue create --body-file issue.md # Create with labels gh issue create --title "Fix bug" --labels bug,high-priority # Create with assignees gh issue create --title "Fix bug" --assignee user1,user2 # Create in specific repository gh issue create --repo owner/repo --title "Issue title" # Create issue from web gh issue create --web ``` ### List Issues ```bash # List all open issues gh issue list # List all issues (including closed) gh issue list --state all # List closed issues gh issue list --state closed # Limit results gh issue list --limit 50 # Filter by assignee gh issue list --assignee username gh issue list --assignee @me # Filter by labels gh issue list --labels bug,enhancement # Filter by milestone gh issue list --milestone "v1.0" # Search/filter gh issue list --search "is:open is:issue label:bug" # JSON output gh issue list --json number,title,state,author # Table view gh issue list --json number,title,labels --jq '.[] | [.number, .title, .labels[].name] | @tsv' # Show comments count gh issue list --json number,title,comments --jq '.[] | [.number, .title, .comments]' # Sort by gh issue list --sort created --order desc ``` ### View Issue ```bash # View issue gh issue view 123 # View with comments gh issue view 123 --comments # View in browser gh issue view 123 --web # JSON output gh issue view 123 --json title,body,state,labels,comments # View specific fields gh issue view 123 --json title --jq '.title' ``` ### Edit Issue ```bash # Edit interactively gh issue edit 123 # Edit title gh issue edit 123 --title "New title" # Edit body gh issue edit 123 --body "New description" # Add labels gh issue edit 123 --add-label bug,high-priority # Remove labels gh issue edit 123 --remove-label stale # Add assignees gh issue edit 123 --add-assignee user1,user2 # Remove assignees gh issue edit 123 --remove-assignee user1 # Set milestone gh issue edit 123 --milestone "v1.0" ``` ### Close/Reopen Issue ```bash # Close issue gh issue close 123 # Close with comment gh issue close 123 --comment "Fixed in PR #456" # Reopen issue gh issue reopen 123 ``` ### Comment on Issue ```bash # Add comment gh issue comment 123 --body "This looks good!" # Edit comment gh issue comment 123 --edit 456789 --body "Updated comment" # Delete comment gh issue comment 123 --delete 456789 ``` ### Issue Status ```bash # Show issue status summary gh issue status # Status for specific repository gh issue status --repo owner/repo ``` ### Pin/Unpin Issues ```bash # Pin issue (pinned to repo dashboard) gh issue pin 123 # Unpin issue gh issue unpin 123 ``` ### Lock/Unlock Issue