Beginner

# Start the interactive authentication flow.
# gh will ask a series of questions to configure your credentials.
gh auth login
# => ? What account do you want to log into? GitHub.com
# => ? What is your preferred protocol for Git operations? HTTPS
# => ? Authenticate Git with your GitHub credentials? Yes
# => ? How would you like to authenticate GitHub CLI? Login with a web browser
# => ! First copy your one-time code: XXXX-XXXX
# => Press Enter to open github.com in your browser...
# => ✓ Authentication complete.
# => - gh config set -h github.com git_protocol https
# => ✓ Configured git protocol
# => ✓ Logged in as your-username

# Pipe a personal access token directly into gh auth login.
# The --with-token flag reads from stdin, avoiding interactive prompts.
echo "$MY_GITHUB_TOKEN" | gh auth login --with-token
# => (no output on success — token stored in config)
 
# Alternatively, export GH_TOKEN and gh will use it automatically.
# This requires no login step at all — useful in ephemeral CI containers.
export GH_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
# => GH_TOKEN is now set in the environment
# => Every gh command in this shell session will use this token
gh auth status
# => github.com
# =>   ✓ Logged in to github.com as your-bot-account (GH_TOKEN)

# Display authentication status for all configured hosts.
# Reports username, host, token source, and granted scopes.
gh auth status
# => github.com
# =>   ✓ Logged in to github.com account alice (keyring)
# =>   - Active account: true
# =>   - Git operations protocol: https
# =>   - Token: gho_************************************
# =>   - Token scopes: 'gist', 'read:org', 'repo', 'workflow'
 
# Check status for a specific host (useful with GitHub Enterprise).
gh auth status --hostname github.mycompany.com
# => github.mycompany.com
# =>   ✓ Logged in to github.mycompany.com account alice (keyring)

# Log out from GitHub.com, removing stored credentials.
gh auth logout
# => ? Are you sure you want to log out of github.com account alice? Yes
# => ✓ Logged out of github.com account alice
 
# Log out without the confirmation prompt (useful in scripts).
gh auth logout --hostname github.com
# => ✓ Logged out of github.com account alice

# Clone using the owner/repo shorthand — no URL needed.
# gh resolves the full URL based on your configured git protocol.
gh repo clone cli/cli
# => Cloning into 'cli'...
# => remote: Enumerating objects: 45231, done.
# => remote: Counting objects: 100% (1203/1203), done.
# => Resolving deltas: 100% (891/891), done.
 
# Clone into a specific local directory name.
gh repo clone cli/cli my-cli-fork
# => Cloning into 'my-cli-fork'...
# => (same progress output as above)
 
# Clone and pass additional git flags after the double dash.
gh repo clone cli/cli -- --depth 1
# => Cloning into 'cli'...
# => (shallow clone — only latest commit history)

# Create a new public repository interactively.
gh repo create my-new-project
# => ? What would you like to do? Create a new repository on GitHub from scratch
# => ? Repository name: my-new-project
# => ? Description: My new project
# => ? Visibility: Public
# => ✓ Created repository alice/my-new-project on GitHub
# =>   https://github.com/alice/my-new-project
 
# Create a private repository non-interactively with all options specified.
gh repo create my-private-app \
  --private \
  --description "Internal application" \
  --add-readme \
  --clone
# => ✓ Created repository alice/my-private-app on GitHub
# => Cloning into 'my-private-app'...
# => (local directory my-private-app now contains the cloned repo)
 
# Push an existing local repository to a new GitHub repo.
# Run from inside the local git repository directory.
gh repo create alice/existing-project --source=. --public --push
# => ✓ Created repository alice/existing-project on GitHub
# => Branch 'main' set up to track remote branch 'main' from 'origin'.

# View the current repository's metadata (run from inside a git repo).
gh repo view
# => alice/my-project
# => No description provided
# =>
# => ★ 0  Watching: 1  Forks: 0
# =>
# => https://github.com/alice/my-project
 
# View a specific repository by owner/name.
gh repo view cli/cli
# => cli/cli
# => GitHub's official command line tool
# =>
# => ★ 38421  Watching: 382  Forks: 5291
# => Topics: cli, github, go
# =>
# => https://github.com/cli/cli
 
# View the README content in the terminal.
gh repo view cli/cli --readme
# => (renders the README.md content with terminal formatting)
 
# Open the repository in your default browser.
gh repo view cli/cli --web
# => Opening github.com/cli/cli in your browser.

# List your own repositories (defaults to the authenticated user).
gh repo list
# => NAME                   DESCRIPTION              INFO          UPDATED
# => alice/my-project       My main project          public        about 2 hours ago
# => alice/dotfiles         Shell configuration      public        about 1 day ago
# => alice/private-notes    Personal notes           private       about 3 days ago
 
# List repositories for a specific user or organization.
gh repo list github
# => NAME                      DESCRIPTION                         INFO      UPDATED
# => github/docs               The open-source repo for docs...   public    about 1 hour ago
# => github/gitignore          A collection of useful .gitignore  public    about 2 days ago
 
# Filter by visibility and limit results.
gh repo list --public --limit 5
# => (shows up to 5 public repositories)
 
# Filter by language.
gh repo list --language go --limit 10
# => (shows up to 10 Go repositories)

# Fork a repository and clone it locally in one step.
# --clone clones the fork; upstream remote is set automatically.
gh repo fork cli/cli --clone
# => ✓ Created fork alice/cli
# => Cloning into 'cli'...
# => remote: Enumerating objects: 45231, done.
# => ✓ Cloned fork
# => (current directory is now inside the cloned fork)
 
# Verify that both origin (fork) and upstream (original) remotes are set.
git remote -v
# => origin    https://github.com/alice/cli.git (fetch)
# => origin    https://github.com/alice/cli.git (push)
# => upstream  https://github.com/cli/cli.git (fetch)
# => upstream  https://github.com/cli/cli.git (push)
 
# Fork without cloning (creates the fork on GitHub only).
gh repo fork cli/go-gh
# => ✓ Created fork alice/go-gh
# => ! To clone the fork, run: gh repo clone alice/go-gh

# Create an issue interactively — gh prompts for title, body, and options.
gh issue create
# => ? Title: Fix login button alignment on mobile
# => ? Body: <editor opens>
# => ? What's next? Submit
# => https://github.com/alice/my-project/issues/42
 
# Create an issue non-interactively with all fields specified.
gh issue create \
  --title "Fix login button alignment on mobile" \
  --body "The login button overlaps the footer on screens < 375px wide." \
  --label "bug,mobile" \
  --assignee alice \
  --milestone "v2.1"
# => https://github.com/alice/my-project/issues/43
 
# Create an issue and open it in the browser immediately.
gh issue create --title "Add dark mode support" --body "" --web
# => Opening github.com/alice/my-project/issues/new in your browser.

# List all open issues for the current repository.
gh issue list
# => Showing 5 of 5 open issues in alice/my-project
# =>
# => ID   TITLE                                  LABELS    UPDATED
# => #43  Add dark mode support                            about 5 minutes ago
# => #42  Fix login button alignment on mobile   bug       about 10 minutes ago
# => #38  Improve test coverage for auth module            about 2 days ago
# => #35  Update dependencies to latest versions           about 3 days ago
# => #30  Document API endpoints                           about 1 week ago
 
# Filter issues by label.
gh issue list --label "bug"
# => ID   TITLE                                  LABELS  UPDATED
# => #42  Fix login button alignment on mobile   bug     about 10 minutes ago
 
# List closed issues.
gh issue list --state closed --limit 5
# => (shows up to 5 closed issues)
 
# Filter by assignee.
gh issue list --assignee alice
# => (shows all issues assigned to alice)

# View issue #42 in the terminal.
gh issue view 42
# => Fix login button alignment on mobile #42
# => Open • alice opened about 10 minutes ago • 0 comments
# =>
# => Labels: bug
# => Assignees: alice
# =>
# => The login button overlaps the footer on screens < 375px wide.
# => Reproduced on iPhone 12 (375px) and Galaxy S21 (360px).
 
# View the issue including all comments.
gh issue view 42 --comments
# => (full issue content + comment thread)
 
# Open the issue in the browser.
gh issue view 42 --web
# => Opening github.com/alice/my-project/issues/42 in your browser.

# Close issue #42 without a comment.
gh issue close 42
# => ✓ Closed issue #42 (Fix login button alignment on mobile)
 
# Close an issue with a comment explaining the resolution.
gh issue close 42 --comment "Fixed in commit abc1234. Updated CSS media query for < 376px."
# => ✓ Closed issue #42 (Fix login button alignment on mobile)
# => (comment added documenting the fix)
 
# Reopen a closed issue (for example, if the fix was incomplete).
gh issue reopen 42
# => ✓ Reopened issue #42 (Fix login button alignment on mobile)
 
# Reopen with an explanatory comment.
gh issue reopen 42 --comment "Bug reappeared after merging PR #55. Reopening for investigation."
# => ✓ Reopened issue #42 (Fix login button alignment on mobile)

# Add a label to an existing issue.
gh issue edit 42 --add-label "high-priority"
# => https://github.com/alice/my-project/issues/42
# => (label high-priority added to issue #42)
 
# Remove a label and add another in the same command.
gh issue edit 42 --remove-label "high-priority" --add-label "in-progress"
# => https://github.com/alice/my-project/issues/42
 
# Update the title of an issue.
gh issue edit 42 --title "Fix login button alignment on mobile and tablet"
# => https://github.com/alice/my-project/issues/42
 
# Assign and set a milestone simultaneously.
gh issue edit 42 --add-assignee bob --milestone "v2.2"
# => https://github.com/alice/my-project/issues/42

# Create a PR interactively — gh detects the current branch and suggests a title.
# Run from inside a git repository with a pushed feature branch checked out.
gh pr create
# => ? Title: Fix login button alignment on mobile
# => ? Body: <editor opens>
# => ? What's next? Submit
# => https://github.com/alice/my-project/pull/44
 
# Create a PR non-interactively with all options.
gh pr create \
  --title "Fix login button alignment on mobile" \
  --body "Resolves #42. Updated CSS media query to target screens < 376px." \
  --base main \
  --reviewer bob,carol \
  --label "bug,css" \
  --assignee alice
# => https://github.com/alice/my-project/pull/45
 
# Create a draft PR (not yet ready for review).
gh pr create --title "WIP: Add dark mode support" --draft
# => https://github.com/alice/my-project/pull/46
# => (PR created as a draft — reviewers are not notified yet)

# List all open pull requests for the current repository.
gh pr list
# => Showing 3 of 3 open pull requests in alice/my-project
# =>
# => ID   TITLE                                  BRANCH             UPDATED
# => #46  WIP: Add dark mode support             dark-mode          about 5 minutes ago
# => #45  Fix login button alignment on mobile   fix/login-btn      about 10 minutes ago
# => #44  Fix login button alignment on mobile   fix/login-btn-v2   about 15 minutes ago
 
# List PRs assigned to you.
gh pr list --assignee @me
# => (shows only PRs assigned to the authenticated user)
 
# List PRs that need your review.
gh pr list --reviewer @me
# => (shows PRs where you are a requested reviewer)
 
# List closed PRs.
gh pr list --state closed --limit 10
# => (shows the 10 most recently closed PRs)

# View the PR for the current branch (auto-detected from git context).
gh pr view
# => Fix login button alignment on mobile #45
# => Open • alice wants to merge 3 commits into main from fix/login-btn
# =>
# => Labels: bug, css
# => Reviewers: bob (Requested)
# => Assignees: alice
# =>
# => Resolves #42. Updated CSS media query to target screens < 376px.
 
# View a specific PR by number.
gh pr view 45
# => (same output as above)
 
# View the PR and include all comments.
gh pr view 45 --comments
# => (full PR content + review comments + general comments)
 
# Open the PR in the browser.
gh pr view 45 --web
# => Opening github.com/alice/my-project/pull/45 in your browser.

# Check out PR #45 by number — switches to the PR's branch.
gh pr checkout 45
# => remote: Enumerating objects: 5, done.
# => remote: Counting objects: 100% (5/5), done.
# => Switched to branch 'fix/login-btn'
# => Branch 'fix/login-btn' set up to track remote branch 'fix/login-btn' from 'origin'.
 
# Check out a PR from a fork (gh handles the remote setup automatically).
gh pr checkout 50
# => remote: Enumerating objects: 8, done.
# => Switched to branch 'fork-contributor/feature-x'
# => (remote for the fork was automatically added)
 
# Verify the current branch after checkout.
git branch --show-current
# => fix/login-btn

# Merge PR #45 using the default merge strategy.
# gh will prompt for merge method if not specified.
gh pr merge 45
# => ? What merge method would you like to use? Squash and merge
# => ? Delete the branch locally and on GitHub? Yes
# => ✓ Squashed and merged pull request #45 (Fix login button alignment on mobile)
# => ✓ Deleted branch fix/login-btn and pushed deletion to GitHub
 
# Merge non-interactively using squash and auto-delete the branch.
gh pr merge 45 --squash --delete-branch
# => ✓ Squashed and merged pull request #45
# => ✓ Deleted branch fix/login-btn and pushed deletion to GitHub
 
# Merge with a rebase (replays commits on top of the base branch).
gh pr merge 45 --rebase --delete-branch
# => ✓ Rebased and merged pull request #45
 
# Enable auto-merge: merge automatically when all checks pass.
gh pr merge 45 --auto --squash --delete-branch
# => ✓ Pull request #45 will be automatically merged via squash when all requirements are met.

# Set the default editor for gh (used when composing issue/PR bodies).
gh config set editor "code --wait"
# => (editor set to VS Code; --wait makes gh wait until the file is closed)
 
# Set the preferred Git protocol (https or ssh).
gh config set git_protocol ssh
# => (git clone operations will now use SSH by default)
 
# Set for a specific hostname (GitHub Enterprise).
gh config set git_protocol https --host github.mycompany.com
# => (HTTPS used for enterprise host; SSH still used for github.com)
 
# Disable browser opening for auth (useful in headless environments).
gh config set browser ""
# => (no browser will be launched; gh will print URLs instead)

# Get a single configuration value.
gh config get editor
# => code --wait
 
# Get the git protocol setting.
gh config get git_protocol
# => ssh
 
# List all configuration values.
gh config list
# => git_protocol=ssh
# => editor=code --wait
# => browser=
# => prompt=enabled
# => pager=
 
# Get a value for a specific host.
gh config get git_protocol --host github.mycompany.com
# => https

# Create an alias for listing your open issues.
gh alias set myissues "issue list --assignee @me"
# => - Adding alias for myissues: issue list --assignee @me
# => ✓ Added alias.
 
# Use the alias just like any other gh command.
gh myissues
# => ID   TITLE                     LABELS    UPDATED
# => #42  Fix login button issue    bug       about 10 minutes ago
 
# Create a shell alias (prefixed with !) for more complex operations.
# Shell aliases can run any shell command, not just gh subcommands.
gh alias set prcreate "!git push -u origin HEAD && gh pr create"
# => - Adding alias for prcreate: !git push -u origin HEAD && gh pr create
# => ✓ Added alias.
 
# List all defined aliases.
gh alias list
# => myissues:  issue list --assignee @me
# => prcreate:  !git push -u origin HEAD && gh pr create
 
# Delete an alias.
gh alias delete myissues
# => ✓ Deleted alias myissues

# Add a comment directly from the command line.
gh issue comment 42 --body "Reproduced on Android 12 as well. Priority should be raised."
# => https://github.com/alice/my-project/issues/42#issuecomment-123456789
 
# Open an editor to compose the comment body.
gh issue comment 42
# => (editor opens; comment posted when file is saved and closed)
 
# Add a comment to an issue in a specific repository.
gh issue comment 42 --repo alice/other-project --body "This affects other-project too."
# => https://github.com/alice/other-project/issues/42#issuecomment-123456790

# View repository details including topics from the current repo.
gh repo view --json name,description,repositoryTopics,stargazerCount
# => {
# =>   "name": "my-project",
# =>   "description": "My main project",
# =>   "repositoryTopics": [
# =>     {"name": "typescript"},
# =>     {"name": "nextjs"}
# =>   ],
# =>   "stargazerCount": 12
# => }
 
# List topics for a specific repository.
gh repo view cli/cli --json repositoryTopics --jq '.repositoryTopics[].name'
# => cli
# => github
# => go

# Pin issue #42 to the top of the repository's issue list.
gh issue pin 42
# => ✓ Pinned issue #42 (Fix login button alignment on mobile)
 
# Unpin the issue when it no longer needs to be highlighted.
gh issue unpin 42
# => ✓ Unpinned issue #42 (Fix login button alignment on mobile)

# Transfer issue #42 to a different repository.
# The target repository must be owned by the same user or organization.
gh issue transfer 42 alice/other-project
# => https://github.com/alice/other-project/issues/15
# => (issue #42 is now issue #15 in other-project; original URL redirects)

# Lock issue #42 with an off-topic reason.
# Reason options: off-topic, too heated, resolved, spam
gh issue lock 42 --reason resolved
# => ✓ Locked issue #42
 
# Unlock the issue to allow further discussion.
gh issue unlock 42
# => ✓ Unlocked issue #42

# Delete a repository — this is irreversible.
# gh requires the full owner/repo name to reduce accidental deletions.
gh repo delete alice/test-throwaway
# => ? Type alice/test-throwaway to confirm deletion:
# => alice/test-throwaway
# => ✓ Deleted repository alice/test-throwaway
 
# Delete without the interactive confirmation prompt (use with extreme caution).
gh repo delete alice/test-throwaway --yes
# => ✓ Deleted repository alice/test-throwaway
# => (no confirmation prompt — dangerous in scripts unless intention is explicit)