SSD Nodes Learn Hosting plans →
Guides Matt ConnorBy Matt Connor

Use the GitHub CLI (gh) with Claude Code

Ubuntu ships a gh build that the gh team calls broken. Install the current one, give Claude Code a narrow token, and fix gh: command not found.

The short answer

To use the GitHub CLI (gh) with Claude Code on a VPS, install gh from GitHub's own apt repository, then give it a token that can reach only the repositories the agent works on. Skip the Ubuntu archive package. The gh maintainers say the 2.45.x and 2.46.x versions that Ubuntu ships are broken. Claude Code calls gh through its Bash tool like any other program, so whatever gh can do, the agent can do.

That last point is why this guide spends as much time on the token as on the install. A CLI (command-line interface) login is a credential. Once it sits in the agent's environment, every command the agent runs can use it. gh is one of the command-line tools a coding agent needs on a VPS, and it is the one with the most power over your code.

Which gh version does Ubuntu give you?

Check the version before you trust the package. As of 15 November 2026, packages.ubuntu.com lists these builds. Both are in the universe component, not main.

  • Ubuntu 24.04 (noble): gh 2.45.0. On amd64 it is 2.45.0-1ubuntu0.3 from the security pocket. The other architectures carry 2.45.0-1build1.
  • Ubuntu 26.04 (resolute): gh 2.46.0, as 2.46.0-4.

The gh install documentation calls the Debian and Ubuntu packages unofficial community builds, and says Ubuntu syncs its package from the Debian one. The same page says that as of November 2025 the maintainers "strongly recommend" their own packages, because the community 2.45.x and 2.46.x versions are broken due to deprecated GitHub APIs. That is exactly the range both LTS (long-term support) releases ship. This guide did not run the archive build to watch it fail, so treat that as the upstream statement it is. It is still enough reason to skip sudo apt install gh from the default sources.

GitHub's own repository at cli.github.com served gh 2.104.0 on 15 November 2026. It has one suite, stable, for every Debian-family release, so noble and resolute get the same build. It publishes packages for i386, amd64, armhf and arm64. If your VPS runs on ppc64el, riscv64 or s390x, the Ubuntu archive is the only apt source of the two.

The snap is not a good fallback. The gh install page lists snap among the methods the team actively discourages, and suggests "never installing gh as a snap".

How do you install gh from GitHub's apt repository?

This follows the official command from the gh install page, with one change: the repository address is taken from the keyring address, because both live in the same directory. ${key_url%/*} strips the file name from the end. The command is the same on 24.04 and 26.04.

(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
  && key_url=https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  && repo_url=${key_url%/*} \
  && sudo mkdir -p -m 755 /etc/apt/keyrings \
  && out=$(mktemp) && wget -nv -O$out "$key_url" \
  && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
  && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
  && sudo mkdir -p -m 755 /etc/apt/sources.list.d \
  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] $repo_url stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
  && sudo apt update \
  && sudo apt install gh -y

The install page also publishes the keyring's SHA256 checksum. Compare it with the file you downloaded:

sha256sum /etc/apt/keyrings/githubcli-archive-keyring.gpg

The first field must read 6084d5d7bd8e288441e0e94fc6275570895da18e6751f70f057485dc2d1a811b. If it does not, remove gh, delete the keyring and /etc/apt/sources.list.d/github-cli.list, and start again. A wrong key means apt trusted packages signed by someone other than GitHub.

Then confirm which package apt chose:

apt-cache policy gh
gh --version

apt-cache policy lists every source that offers gh. The Installed: version should be the cli.github.com build, and gh --version should report 2.104.0 or newer. By default apt prefers the higher version, so a box that already had Ubuntu's 2.45.0 moves to GitHub's build when you install from the new source. Later upgrades come through sudo apt update and sudo apt install gh, or with the rest of the system in sudo apt upgrade.

How do you log in to gh on a headless VPS?

Two routes suit a server. Pick based on whose identity the agent should carry.

The browser flow, finished on your laptop

The default mode of gh auth login is a web-based browser flow. A VPS has no browser, so you finish that step on another machine. The flow uses a one-time OAuth device code, which is why the manual offers -c/--clipboard to copy it. (OAuth is the standard GitHub uses to let an app act for an account.) Run it and follow the prompts it prints:

gh auth login --hostname github.com --git-protocol https

When the flow finishes, gh stores the token in the system credential store. If no credential store is usable, it falls back to a plain-text file. A minimal server image is exactly where you should check which one happened:

gh auth status

gh auth status shows the active account on each host and where its token is stored. It exits with status 1 when it finds a problem, so it also works inside scripts. Since gh 2.104.0 it reports the underlying rate-limit, server or network error instead of hiding it.

The catch with this route is identity. gh is logged in as whoever approved the code. Approve it with your personal account and the agent now holds everything your personal login can reach. The next route is narrower.

A fine-grained token in GH_TOKEN

A fine-grained personal access token (PAT) is limited to resources owned by one user or one organization, with a separate grant for each permission. You can also restrict it to "Only select repositories". For an agent, that is the right shape.

You might expect to feed it to gh auth login --with-token. The manual documents --with-token for a classic token, with the minimum scopes repo, read:org and gist, and warns that fine-grained tokens passed that way can behave confusingly. The gh source says it plainly: "Favour setting GH_TOKEN for fine-grained personal access token usage."

When GH_TOKEN is set, gh uses it, skips every login prompt, and ignores stored credentials. GH_TOKEN also wins over GITHUB_TOKEN. Read the token into the shell without echoing it and without writing it to shell history. Paste it after the first line and press Enter.

read -rs GH_TOKEN
export GH_TOKEN
gh auth status
claude

Start Claude Code from that same shell, for example inside the session described in running Claude Code on a VPS inside tmux. The order matters. Claude Code's docs say each Bash command runs in a separate process and that an export in one command is not available in the next. A token exported inside the agent's own command is gone one command later, while a token exported before claude starts is in the environment the whole session inherits.

One interaction to know about. While GH_TOKEN is set, gh auth login refuses to store credentials. The current gh source prints this message:

The value of the GH_TOKEN environment variable is being used for authentication. To have GitHub CLI store credentials instead, first clear the value from the environment.

unset GH_TOKEN clears it for that shell.

Which permissions should the agent's fine-grained token get?

When you create a fine-grained token you choose the resource owner, an expiration, the repositories it reaches, and the permissions it holds. GitHub's docs ask for "the minimal permissions necessary" and "the minimal repository access that meets your needs".

  • Expiration. Anything from 1 to 366 days, or none. The default is 30 days, or less if the organization sets a token lifetime policy. Keep a short lifetime, because a leaked token then stops working on its own.
  • Repository access. Choose "Only select repositories" and pick the ones the agent works on.
  • Reading code. Contents: read.
  • Writing files through the API. Contents: write. GitHub's table says this endpoint needs additional permissions it does not list on that row.
  • Pull requests. Pull requests: read to read them, Pull requests: write to create them.
  • Issues. Issues: read to list them, Issues: write to open them.

Three limits come with every fine-grained token. It always includes read-only access to all public repositories on GitHub. It cannot reach more than one organization at once. It cannot access Packages or the Checks API. If the owner is an organization that requires approval, the token "will only be able to read public resources until it is approved". Organization owners are approved automatically.

The permission mapping above comes from GitHub's table for REST endpoints. gh also uses GraphQL, GitHub's other API, where one request asks for exactly the fields it needs, for commands such as gh pr create. This guide did not test which permissions those GraphQL calls need. Before you rely on a minimal set, run the exact gh commands your agent will use, with the token, against a scratch repository.

How do you let git push with gh's credentials?

gh auth setup-git configures git to use gh as its credential helper. A credential helper is the program git asks for a username and password when it talks to a remote over HTTPS.

gh auth setup-git
git config --global --list | grep credential

The second command shows the credential entries that were written. By default setup-git installs gh as the helper for every authenticated host. If gh has no authenticated hosts, it fails with an error. --hostname github.com limits it to one host, and --force, which only works together with --hostname, sets up a host gh does not know.

This guide did not check whether a token held only in GH_TOKEN counts as authenticated for setup-git, or test an HTTPS push with a fine-grained token. Prove it on your box with a throwaway branch before the agent depends on it:

git push origin HEAD:refs/heads/gh-token-test
git push origin --delete gh-token-test

A push that asks for a username means git is not using gh. A push that GitHub rejects usually means the token lacks Contents: write on that repository.

What does a token in the agent's environment expose?

Everything the token can do, to every command the agent runs. That includes commands the agent was talked into by text it read. Prompt injection is text, such as an issue body, written so that a model follows the attacker's instructions instead of yours. An agent that reads a hostile issue while holding a token with write access to ten repositories is a risk to all ten.

Claude Code has a setting that strips credentials from subprocesses, CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1. By design it does not protect a GitHub token. The docs say it leaves GITHUB_TOKEN, GH_TOKEN, GH_ENTERPRISE_TOKEN and GITHUB_ENTERPRISE_TOKEN in place so that gh keeps working. To keep a GitHub token away from sandboxed Bash commands, the docs point to a deny entry under sandbox.credentials instead, and they describe the scrub as one layer "alongside narrow permission rules rather than as the only control". The wider pattern is in keeping secrets out of an AI agent's reach.

The permission mode decides how much runs without asking you. On Claude Code v2.1.283 or later, interactive terminal sessions start in auto. Headless claude -p starts in default, labelled Manual in the CLI, and from v2.1.302 calls that need approval are denied unless a rule allows them. How auto mode decides what Claude Code may run covers the details. --dangerously-skip-permissions is a different matter. The docs say it "offers no protection against prompt injection", recommend it only for isolated environments, and on Linux it refuses to run as root or under sudo outside a recognized sandbox.

Deny rules help with the worst commands. A deny or ask rule matches past any leading variable assignment, so a rule such as Bash(gh repo delete *) in your deny list still catches GH_TOKEN=... gh repo delete. Allow rules are stricter and do not match past most assignments. gh 2.104.0 also warns before gh repo delete removes a private or internal repository's forks, but an agent can pass --yes --accept-cascading-deletion-of-private-forks as easily as you can. The real control is the token's permission list. Also keep the agent away from gh auth status --show-token, which prints the token into the transcript.

Why a machine account beats your personal login

A narrow token on your own account still acts as you. Its commits, comments and pull requests carry your name, and the next token you create from that account starts from your full reach again.

GitHub's terms allow a machine account: an account set up by a human who accepts the terms on its behalf. GitHub's docs call this a machine user. The terms allow "no more than one free machine account in addition to your free Personal Account", and the human stays responsible for its security. Add the machine account as a collaborator on the repositories the agent needs, and create the fine-grained token on that account. The agent's work then shows under its own name, and removing access means removing one collaborator. Giving your AI agent its own identity walks through the account, its SSH key and its Linux user. If the account is new, your first hour on GitHub covers the settings worth changing first.

This is a policy and hygiene argument, not a security guarantee. A machine account with a broad classic token is still a broad token.

How do you fix "gh: command not found" in Claude Code?

The shell prints gh: command not found when it searched every directory in PATH and found no program called gh. PATH is the list of directories a shell searches for commands. So the question is always the same: is gh missing from this machine, or missing from this shell's PATH?

Run these two lines in your own terminal, then ask Claude Code to run them:

type -a gh
echo "$PATH"

type -a prints every gh the shell can find. Compare the two answers.

  • Neither finds gh. It is not installed where Claude Code runs. A common version: gh is on your laptop, Claude Code is on the VPS. Install it on the VPS with the commands above.
  • Your terminal finds it and Claude Code does not. The directory holding gh is in your PATH and not in Claude Code's. Look at the path your terminal printed.
  • Claude Code runs as a different Linux user. A gh installed under one user's home directory is invisible to another user. The apt install puts gh in a system directory that every user's default PATH covers.
  • The path is under /snap. That is the snap build, which the gh team discourages. Remove it with sudo snap remove gh and install from apt.

The docs explain the mechanism. Claude Code sources ~/.zshrc, ~/.bashrc or ~/.profile at session start, depending on your shell, captures the aliases, functions and shell options, and applies them to every Bash command. Environment variables do not carry from one command to the next. It follows (an inference, not a statement from the docs) that a PATH entry added only in a file Claude Code does not source, or added by hand in a terminal after login, can be missing from the agent's commands. For a variable that must persist across commands, the docs name CLAUDE_ENV_FILE and a SessionStart hook, which Claude Code hooks explains.

The desktop app has a version of this problem, and its documentation covers it. The troubleshooting section "Session not finding installed tools" says that if Claude can't find tools like npm, node, or other CLI commands, you should "verify the tools work in your regular terminal, check that your shell profile properly sets up PATH, and restart the desktop app to reload environment variables." On Windows, the same page adds that Desktop doesn't read PowerShell profiles, so set PATH in your user or system environment variables, then quit and reopen Desktop. Issue #48253 is one user's report of the symptom. It describes Claude Code Desktop on macOS starting sessions with a minimal PATH, /usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin, which missed Homebrew. gh, node and npm all showed as command not found. The reporter's workaround was exporting PATH in each command. The issue was closed as a duplicate of #43210 and locked, with no maintainer reply. It is a Mac report, not a VPS one, but the check above finds the same cause.

Why do gh pr and gh issue fail in Claude Code cloud sessions?

In Anthropic-hosted cloud sessions, gh is preinstalled and reads GH_TOKEN automatically, so you do not run gh auth login and command not found is not the usual failure. The failure there is a 403. GitHub requests go through a proxy, and the proxy rejects GraphQL with a message that starts GitHub GraphQL is not available from Claude Code sessions. Subcommands that use GraphQL, such as gh pr and gh issue, get the same 403, even with a GH_TOKEN you set yourself. REST calls through gh api work, for example gh api repos/{owner}/{repo}/pulls, and so does gh workflow list.

The proxy also limits API calls to the repositories attached to the session. It rejects branch deletions and pushes that are not to a branch. It does not limit which branches a push can update.

When you set neither GH_TOKEN nor GITHUB_TOKEN, both read as the placeholder proxy-injected, and your real credentials stay encrypted on Anthropic's servers. Ask Claude to run echo $GH_TOKEN to see which case you are in. A token you set yourself is an ordinary environment variable that anyone who uses the environment can read. /web-setup sends your local gh token to your Claude account and reaches any repository that token can access, which is one more reason to keep your local gh login narrow. On Team and Enterprise plans, /web-setup is hidden unless an owner turns on the Quick setup setting.

Does /install-github-app work on a headless server?

/install-github-app is the quick setup for the Claude Code GitHub Action. It installs the Claude GitHub App, stores ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN as a repository secret, and opens GitHub in your browser with a pull request that adds the workflow file. It needs admin access to the repository, works only with github.com, and expects gh to be installed and logged in. Claude Code warns you if gh is missing.

The browser step is the weak point on a server. Three reports, each a single user's report and not a documented limit:

  • #22622, Claude Code 2.1.29 on a headless Ubuntu 22.04.5 code server: the flow returned Invalid OAuth Request - Unknown scope: user:inf, while the same flow worked on a Mac. A stale bot closed it as not planned, with no maintainer reply.
  • #3031, Claude CLI 1.0.43 in an Ubuntu devcontainer: the command tried to open a browser and showed no URL to open by hand. An Anthropic collaborator replied that the URL would be shown in a coming update. The issue does not show whether that shipped.
  • #6872, Claude Code 1.0.98 in a Docker container: Claude ran gh auth status -a and the installed gh rejected it with unknown shorthand flag: 'a' in -a. The current manual lists -a/--active, so an old gh is the likely gap, though the report does not name the version.

When the command fails, the docs offer a manual route. Install the app from https://github.com/apps/claude, add ANTHROPIC_API_KEY as a repository secret, or a token from claude setup-token as CLAUDE_CODE_OAUTH_TOKEN, then copy the example workflow examples/claude.yml into .github/workflows/. Know what you are approving. The docs say "When you install the app, you accept its full permission set". That set includes read and write on Contents, Issues, Pull requests, Actions and Workflows, among others. An organization that wants less must build its own GitHub App.

Should the agent call gh or the GitHub MCP server?

The GitHub MCP server is GitHub's own server for MCP (Model Context Protocol), which presents GitHub as a set of tools the model calls directly. The remote server lives at https://api.githubcopilot.com/mcp. Add it from your terminal, not from inside Claude Code, with the PAT in a variable:

claude mcp add --transport http github https://api.githubcopilot.com/mcp -H "Authorization: Bearer $GITHUB_PAT"
claude mcp list

Two switches make it narrower. Append /readonly to the URL, or send the X-MCP-Readonly header, and only read tools are offered. A path such as /x/issues limits it to one toolset, and the X-MCP-Toolsets header combines several. GitHub's guide also says to keep .env and .mcp.json out of git, because the token ends up in configuration.

On a VPS, the default choice is gh with a fine-grained token. The agent already has a shell, git needs the same credential to push, and the token's permission list is the one control both share. Add the MCP server in read-only mode when you want the agent to browse issues and pull requests through structured tools without any write path. Remember that Anthropic does not security-audit or manage any MCP server, including this one. How MCP servers compare with skills and rules files covers the wider trade-off.

FAQ

Why does Claude Code say "gh: command not found" when gh works in my terminal?

The shell Claude Code uses has a different PATH from yours, or runs as a different user, or runs on a different machine. Run type -a gh and echo "$PATH" in your terminal, then ask Claude Code to run the same two lines and compare. Installing gh from GitHub's apt repository puts it in a system directory every default PATH includes, which removes most PATH differences.

Should I install gh with apt install gh on Ubuntu 24.04 or 26.04?

Not from the default Ubuntu sources. Ubuntu 24.04 ships gh 2.45.0 and Ubuntu 26.04 ships 2.46.0, and the gh maintainers say the community 2.45.x and 2.46.x versions are broken because of deprecated GitHub APIs. Add GitHub's apt repository at cli.github.com first. It served gh 2.104.0 on 15 November 2026 for both releases.

Can I use a fine-grained token with gh auth login --with-token?

The manual documents --with-token for a classic token with the scopes repo, read:org and gist, and warns that fine-grained tokens passed that way can behave confusingly. The gh source recommends setting GH_TOKEN for fine-grained tokens instead. gh then uses the variable, skips login prompts and ignores stored credentials.

Why does gh pr create return a 403 in a Claude Code cloud session?

In Anthropic-hosted cloud sessions, GitHub traffic goes through a proxy that rejects GraphQL requests, with a message starting GitHub GraphQL is not available from Claude Code sessions. gh pr and gh issue use GraphQL, so they fail even with your own GH_TOKEN. Use REST calls through gh api repos/{owner}/{repo}/... instead.

Was this article useful?