How to Install GitHub Copilot CLI

Installing Copilot CLI takes one command. The reason this lesson is longer than one command is that a large fraction of the installation instructions currently reachable through search install a different, retired product — and the failure is silent, because the retired product also works. It just cannot do any of the things this cluster is about.

Before you start

That last point causes more confused installations than the others combined. The install itself will succeed on a managed account with CLI access disabled; the failure appears later, at authentication or first request. If you are on a work account and /login refuses, the problem is policy rather than your machine.

The trap worth naming first

The confusing part is that gh copilot still works — but it means something new. Since January 2026, running gh copilot from the GitHub CLI prompts to install Copilot CLI on first run and then executes it, forwarding unsupported arguments and flags. So the same words now launch the current product.

This makes gh copilot a legitimate sixth installation route, and it also makes search results almost impossible to date by their commands alone. The reliable signal is the package name: @github/copilot is current, github/gh-copilot is retired.

Installation methods

npm — all platforms

npm install -g @github/copilot

Requires Node.js 22 or later. This is the route that works identically everywhere and the one most likely to match documentation you find later.

Homebrew — macOS and Linux

brew install --cask copilot-cli

Note it is a cask, not a formula. brew install copilot-cli without --cask will not find it.

WinGet — Windows

winget install GitHub.Copilot

PowerShell v6 or later is required. Windows Subsystem for Linux is also supported and behaves like the Linux install.

Install script — macOS and Linux

curl -fsSL https://gh.io/copilot-install | bash

Direct download

Executables are published on the github/copilot-cli releases page. This is the route for air-gapped machines, for pinning an exact version, or for environments where package managers are not available.

Prerelease versions

Append @prerelease to the npm, WinGet or Homebrew command. For the install script, set the VERSION environment variable.

About that pipe-to-shell command

curl … | bash downloads a script and executes it immediately, with your user’s privileges, before you have seen a line of it. That is worth thinking about even when the source is legitimate — and gh.io is GitHub’s own domain, so this one is.

The concern is not that GitHub is untrustworthy. It is that the pattern trains a habit that transfers to domains that are not, and that a piped script gives you no opportunity to notice a compromised endpoint or a redirect you did not expect.

First launch and authentication

Start the CLI in a directory you are happy for it to read:

copilot

On first run in a directory, it asks whether you trust that directory. This is a real security decision rather than a formality — a repository can contain hooks, MCP server definitions, and instruction files that shape or execute during the session. The pillar covers what you are actually agreeing to; for now, answer yes only for code you know.

Then authenticate:

/login

On a local desktop this opens a browser and captures the result on a loopback callback. In environments GitHub detects as remote or headless — SSH sessions, Codespaces, dev containers, CI, headless Linux — it defaults to the OAuth device code flow instead. --device-code and --web-flow force a specific mode.

The token is stored in your system credential store where one is available. Where it is not, it falls back to a plain text config file under ~/.copilot/.

Token-based authentication

For automation, Copilot CLI reads a token from the environment. Three variables are checked, in this order of precedence:

1. COPILOT_GITHUB_TOKEN
2. GH_TOKEN
3. GITHUB_TOKEN

Supported token types include fine-grained personal access tokens (v2 PATs) with the Copilot Requests permission, and OAuth tokens from the GitHub Copilot CLI app.

Inside GitHub Actions the situation is better still: workflows can authenticate with the built-in GITHUB_TOKEN given a copilot-requests: write permission, with no additional secret. The GitHub Actions lesson covers that in full.

Verifying the install

copilot --version
copilot --help

Neither requires authentication, which makes them the right first check — if --version prints and /login fails, you have a policy or account problem, not an installation problem.

copilot help also exposes topic pages that are the most reliable reference available for the version you actually have:

copilot help permissions
copilot help sandbox
copilot help config
copilot help environment

Which platforms, precisely

Copilot CLI runs on Linux, macOS, and Windows. On Windows it works through PowerShell and through Windows Subsystem for Linux, and the WSL route behaves like the Linux one in every respect that matters to this cluster — the same install commands, the same paths, the same permission model.

That distinction is worth choosing deliberately rather than by accident. A CLI session inside WSL sees the WSL filesystem and the WSL shell; a session in PowerShell sees Windows. If your repository lives under /home/you/ in WSL, run the CLI there. Crossing the boundary through /mnt/c/ works but gives you Windows file permissions viewed through a Linux lens, which is a source of confusion the agent will inherit rather than resolve.

Codespaces, containers and remote machines

These are the environments where Copilot CLI is most obviously useful — a terminal-native agent on a machine with no editor attached — and also where authentication differs. GitHub detects SSH sessions, Codespaces, dev containers, CI and headless Linux, and defaults them to the device code flow rather than the browser flow.

For a dev container or an image you rebuild often, installing through npm in the image definition is the least friction, with the token supplied by environment variable rather than an interactive login.

Avoiding two installations at once

It is easy to end up with more than one copy — an npm global install and a Homebrew cask, or a direct download left on PATH from an earlier experiment. The symptom is confusing: copilot --version reports a version that does not match what you just installed, and behaviour does not change when you update.

command -v copilot     # which binary actually runs
copilot --version      # what it reports

On macOS and Linux, command -v resolves the one your shell will execute. If that path is not the one you expect, remove the other installation rather than reordering PATH — a stale copy that resurfaces after a shell restart is a problem you will have to solve twice.

Updating

The CLI checks for updates on startup and downloads them automatically. That behaviour is disabled in CI environments, detected through CI, BUILD_NUMBER, RUN_ID or SYSTEM_COLLECTIONURI.

copilot update              # stable channel
copilot update prerelease   # prerelease channel

--no-auto-update disables automatic updates for a session. Via npm, the equivalent is npm install -g @github/copilot@latest.

Uninstalling

Remove by the route you installed with:

npm uninstall -g @github/copilot          # npm
brew uninstall --cask copilot-cli         # Homebrew
winget uninstall GitHub.Copilot           # WinGet

Configuration and credentials live in ~/.copilot/ and are not removed by any of those. Delete that directory to clear stored tokens, logs, session history, personal agents and skills. On a shared or handed-over machine, that step is the one that matters.

Confirming the install is genuinely the current product

Because two products have shared a name, it is worth one explicit check that you have the agentic CLI rather than a leftover extension.

Three signals, in increasing strength. The binary is copilot, invoked on its own rather than as a gh subcommand. copilot --help lists subcommands including mcp, plugin and skill — none of which the old extension had. And copilot help permissions exists at all: the retired extension had no permission model to document, because it never executed anything.

If those three hold, you are looking at the current product and everything in this cluster applies.

What the first run actually asks you

Two prompts arrive before you do any work, and both are easy to click through without reading.

The trust prompt asks whether you trust the current directory. Answering yes allows the agent to read the repository — including files that instruct it. AGENTS.md, .github/copilot-instructions.md, hook definitions and MCP server configurations all shape the session. On a repository you cloned to evaluate, this is a decision rather than a formality.

The authentication prompt follows /login. On a desktop this hands off to a browser; over SSH it falls back to a device code. Neither stores anything until it succeeds, so an interrupted login leaves nothing behind.

Keeping several machines consistent

If you use the CLI on a laptop, a desktop and a server, small differences between them produce confusing behaviour — a rule that applies in one place and not another, a version that behaves differently.

Three things are worth keeping deliberately in sync.

The version. copilot --version on each. Auto-update usually keeps them close, but a machine that has not run the CLI in weeks will lag, and CI never auto-updates at all.

Personal instructions and agents. Anything under ~/.copilot/ is per-machine. An agent you wrote on your laptop does not exist on the server, and the absence is silent — the CLI simply does not find it.

Your aliases. The denial defaults are only protective on machines where you set them up, and the machine most likely to be missing them is the one you use least, which is often the one where a mistake costs most.

Troubleshooting

copilot: command not found after a successful npm install. The npm global bin directory is not on your PATH. npm bin -g prints it; add it to your shell profile.

Node version errors. The npm package requires Node.js 22 or later. node --version to check. Version managers frequently leave an older Node first on the PATH than the one you think is active.

/login fails on a work account. Most likely an organisation or enterprise policy disabling Copilot CLI. This cannot be resolved locally.

Browser login does nothing over SSH. Expected — the loopback callback cannot reach you. Use --device-code.

Homebrew cannot find it. It is a cask: brew install --cask copilot-cli.

It worked yesterday and behaves differently today. Auto-update. /changelog shows what changed, and takes summarize for an AI summary.

Choosing a method

For most people the answer is npm, because it behaves identically on every platform and matches the majority of documentation you will encounter later.

Prefer Homebrew or WinGet if you already manage other developer tools that way — a single brew upgrade covering everything is worth more than consistency with articles. Prefer the direct download when you need a pinned version, an air-gapped install, or a machine with no package manager. Prefer gh copilot if the GitHub CLI is already installed and you would rather not think about it at all.

The install script sits between those: convenient, official, and the only route that asks you to execute something you have not seen. That is a reasonable trade on a machine you control and a poor one on shared infrastructure.

After installing: three things worth doing once

Set up shell completion. The flag surface is large and several pairs differ only slightly. copilot completion bash — or zsh, fish, powershell — generates the script; redirect it wherever your shell loads completions from.

Read copilot help permissions on your own installation. It is the most important page in the tool and takes four minutes. Because the CLI ships frequently, your local copy is often ahead of published documentation.

Decide your default denials now, before you need them. Two rules cost nothing and close real categories of accident:

alias cop="copilot --deny-tool='shell(git push:*)' --deny-tool='write(.env)'"

Neither will matter on a normal day. Both matter on the day something goes wrong, and on that day they do not depend on you noticing in time. Setting them up while you are already thinking about installation is considerably more likely than setting them up later.

Next

With the CLI installed and authenticated, the beginner tutorial runs a complete first session on a throwaway project — trust, ask, change, test, review — and the commands cheat sheet is the reference to keep open beside it. If you want the conceptual model before touching anything, the pillar explains what the permission prompts are actually protecting.