---
title: GitHub Copilot CLI command reference
shortTitle: CLI command reference
intro: 'Find commands and keyboard shortcuts to help you use {% data variables.copilot.copilot_cli_short %} effectively.'
versions:
feature: copilot
category:
- Author and optimize with Copilot # Copilot discovery page
- Build with Copilot CLI # Copilot CLI bespoke landing page
contentType: reference
redirect_from:
- /copilot/reference/cli-command-reference
docsTeamMetrics:
- copilot-cli
---
## Command-line commands
| Command | Purpose |
|------------------------|----------------------------------------------------|
| `copilot` | Launch the interactive user interface. |
| `copilot completion SHELL` | Print a shell script for the chosen shell that can be used to enable tab completion for {% data variables.copilot.copilot_cli_short %}. Supported shells: `bash`, `zsh`, `fish`. See [Using `copilot completion`](#using-copilot-completion). |
| `copilot help [TOPIC]` | Display help information. Help topics include: `billing`, `config`, `commands`, `environment`, `logging`, `monitoring`, `permissions`, and `providers`. |
| `copilot init` | Initialize {% data variables.product.prodname_copilot_short %} custom instructions for this repository. |
| `copilot login` | Authenticate with {% data variables.product.prodname_copilot_short %} via the OAuth device flow. Accepts `--host HOST` to specify the {% data variables.product.github %} host URL (default: `https://github.com`). |
| `copilot login` [OPTION] | Authenticate with {% data variables.product.prodname_copilot_short %} via the OAuth device flow. See [`copilot login` options](#copilot-login-options). |
| `copilot mcp` | Manage MCP server configurations from the command line. |
| `copilot plugin` | Manage plugins and plugin marketplaces. |
| `copilot plugins list` | Non-interactively inspect every plugin, MCP server, skill, instruction source, and language server discovered for the current working directory—the same resources the in-CLI plugins dashboard shows. See [Using `copilot plugins list`](#using-copilot-plugins-list). |
| `copilot skill` | Manage agent skills from the command line (list, add, and remove skills). See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-skills). |
| `copilot update` | Download and install the latest version. |
| `copilot version` | Display version information and check for updates. |
### `copilot login` options
| Option | Purpose |
|-------------------------|-----------------------------------------------------------------------------------------------|
| `--host HOST` | {% data variables.product.github %} host URL (default: `https://github.com`). Use this to authenticate with a {% data variables.product.prodname_ghe_cloud %} instance that uses data residency (for example, `https://example.ghe.com`). |
The default authentication mode is a web-based browser flow. After completion, an authentication token is stored securely in the system credential store. If a credential store is not found, the token is stored in a plain text configuration file under `~/.copilot/` (or the directory specified by `COPILOT_HOME` if set).
Alternatively, {% data variables.copilot.copilot_cli_short %} will use an authentication token found in environment variables. The following are checked in order of precedence: `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`. This method is most suitable for headless use such as automation.
Supported token types include {% data variables.product.pat_v2_plural %} (v2 PATs) with the "Copilot Requests" permission, OAuth tokens from the {% data variables.product.prodname_copilot_short %} CLI app, and OAuth tokens from the {% data variables.product.prodname_cli %} (`gh`) app. Classic {% data variables.product.pat_generic_plural %} (`ghp_`) are not supported.
**Examples:**
```shell
# Authenticate with github.com
copilot login
# Authenticate with GitHub Enterprise Cloud (data residency)
copilot login --host https://example.ghe.com
# Use a fine-grained PAT via environment variable
COPILOT_GITHUB_TOKEN=github_pat_... copilot
```
### Using `copilot completion`
The command `copilot completion SHELL` outputs a script for the specified shell (bash, zsh, or fish).
By sourcing this script (or writing it to your shell's completion directory) you can enable tab completion in your terminal for `copilot` subcommands, command options, and known value choices for command options.
#### Usage examples
Bash (current session only):
```bash copy
source <(copilot completion bash)
```
Bash (persistent, Linux):
```bash copy
copilot completion bash | sudo tee /etc/bash_completion.d/copilot
```
Zsh — write the output to a directory on your $fpath. Restart the shell after running this command:
```shell copy
copilot completion zsh > "${fpath[1]}/_copilot"
```
Fish:
```shell copy
copilot completion fish > ~/.config/fish/completions/copilot.fish
```
### Using `copilot plugins list`
Run `copilot plugins list` to inspect every plugin, MCP server, skill, instruction source, and language server discovered for the current working directory. Output is grouped by kind, then by configuration scope (user, repository, organization, plugin-contributed, built-in, or unknown).
```bash
# List everything for the current workspace
copilot plugins list
# Only MCP servers and skills
copilot plugins list --kind mcp --kind skill
# Only user-scoped resources, as JSON
copilot plugins list --scope user --json
```
| Option | Description |
|-----------------------|------------------------------------------------------------------------------------|
| `--kind KINDS` | Filter by kind. Repeatable or comma-separated: `mcp`, `skill`, `instruction`, `plugin`, `lsp`. |
| `--scope SCOPES` | Filter by configuration scope. Repeatable or comma-separated. |
| `--json` | Emit machine-readable JSON instead of grouped text. |
| `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. |
Custom agents and session-scoped hooks aren't covered by `copilot plugins list`; both require a live session.
### `copilot plugins enable` / `copilot plugins disable`
Enable or disable a plugin, MCP server, or skill by name. The change persists to configuration and applies to future sessions.
```bash
# Disable an MCP server
copilot plugins disable github --mcp
# Enable a skill
copilot plugins enable my-skill --skill
# Enable a plugin (default kind)
copilot plugins enable spark@copilot-plugins
```
| Option | Description |
|------------------------|------------------------------------------------------------------------------------|
| `--plugin` | Target a plugin (default). |
| `--mcp` | Target an MCP server. |
| `--skill` | Target a skill. |
| `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. |
Instructions are session-scoped only and can't be toggled with these commands. Language servers, agents, and hooks are managed elsewhere.
### `copilot plugins remove`
Uninstall a plugin, remove an MCP server, or delete a skill by name.
```bash
# Remove an MCP server
copilot plugins remove github --mcp
# Delete a personal or project skill
copilot plugins remove my-skill --skill
# Uninstall a plugin (default kind)
copilot plugins remove spark@copilot-plugins
```
| Option | Description |
|------------------------|------------------------------------------------------------------------------------|
| `--plugin` | Remove a plugin (default). |
| `--mcp` | Remove an MCP server. |
| `--skill` | Remove a personal or project skill. |
| `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. |
With `--skill`, pass either a skill name or the path to a custom skill directory you added. A skill name deletes that skill's files; a custom directory path only unregisters the directory and leaves its files on disk. Only personal and project skills you added can be deleted—skills provided by a plugin or the builtin set can't be removed this way (disable them instead). Instruction sources are discovered from disk and can't be removed here.
## Global shortcuts in the interactive interface
| Shortcut | Purpose |
|-------------------------------------|---------------------------------------|
| `@ FILENAME` | Include file contents in the context. |
| `# NUMBER` | Include a {% data variables.product.github %} issue or pull request in the context. |
| `! COMMAND` | Execute a command in your local shell, bypassing {% data variables.product.prodname_copilot_short %}. Enter `!` alone on an empty prompt to enter shell mode for running multiple shell commands in sequence. Press Esc or Ctrl+C on an empty prompt to exit shell mode. |
| `?` | Open quick help (on an empty prompt). Press again to dismiss and insert a literal `?`. |
| Esc | Cancel the current operation. Press twice to interrupt the running turn, or to stop background agents when the main agent is idle. |
| Ctrl+C | Cancel operation / clear input. Press twice to exit. |
| Ctrl+D | Shutdown. |
| Ctrl+G | Edit the prompt in an external editor (`$EDITOR`). |
| Ctrl+L | Clear the screen. |
| Ctrl+Enter or Ctrl+Q | Queue a message to send while the agent is busy. |
| Ctrl+R | Reverse search through command history. |
| Ctrl+V | Paste from clipboard as an attachment. |
| Ctrl+X then `/` | After you have started typing a prompt, this allows you to run a slash command—for example, if you want to change the model without having to retype your prompt. |
| Ctrl+X then `e` | Edit the prompt in an external editor (`$EDITOR`). |
| Ctrl+X then `b` | Promote the running task or shell command to the background. |
| Ctrl+X then `o` | Open the most recent link from the timeline. |
| Ctrl+Z | Suspend the process to the background (Unix). |
| Shift+Enter or Option+Enter (Mac) / Alt+Enter (Windows/Linux) | Insert a newline in the input. |
| Shift+Tab | Cycle between standard, plan, and autopilot mode. |
## Timeline shortcuts in the interactive interface
| Shortcut | Purpose |
|------------------------------|---------------------------------------|
| Ctrl+F | Open timeline search. |
| Ctrl+O | While there is nothing in the prompt input, this expands recent items in {% data variables.product.prodname_copilot_short %}'s response timeline to show more details. |
| Ctrl+E | While there is nothing in the prompt input, this expands all items in {% data variables.product.prodname_copilot_short %}'s response timeline. |
| Ctrl+T | Expand/collapse display of reasoning in responses. |
| Page Up/Page Down | Scroll the timeline up or down by one page. |
## Session picker shortcuts
When the session picker is open (opened via `/resume` or `--continue`):
| Shortcut | Purpose |
|----------|---------|
| ↑/↓ | Move selection up or down. |
| Enter | Open the selected session. |
| `s` | Cycle the sort order: relevance → created → name → last used. |
| Tab | Switch between the local and remote tabs. |
| `d` | Delete the selected session. |
| Esc | Close the picker. |
Sessions sort by the following modes:
| Mode | Description |
|------|-------------|
| `relevance` | Scores sessions by match to the current working directory (default). |
| `last used` | Most recently modified sessions first. |
| `created` | Most recently created sessions first. |
| `name` | Alphabetical by session name; unnamed sessions sort to the end. |
Sessions already open in another window float to the top in all non-relevance sort modes. When no working-directory context is available, the `relevance` mode is skipped.
## Diff mode shortcuts
When diff mode is open (entered via `/diff`):
| Shortcut | Purpose |
|----------|---------|
| ↑ / `k` | Move selection up one line. |
| ↓ / `j` | Move selection down one line. |
| ← / `h` | Jump to the previous file. |
| → / `l` | Jump to the next file. |
| Home / `g` | Jump to the first line. |
| End / `G` | Jump to the last line. |
| Page Up | Scroll up one page. |
| Page Down | Scroll down one page. |
| Ctrl+U | Scroll up half a page. |
| Ctrl+D | Scroll down half a page. |
| `Click` | Select the clicked diff line (requires mouse support). |
| Mouse scroll | Scroll up or down. |
| Alt/Option+scroll | Scroll one line at a time for fine-grained control. |
| `c` | Add or edit a comment on the selected line. |
| `s` | Show comments summary (when comments exist). |
| `b` | Toggle between unstaged changes and branch diff. |
| `w` | Toggle hiding whitespace-only changes. |
| Enter | Submit all comments (when comments exist). |
| `r` | Refresh the diff (remote sessions only). |
| Esc / Ctrl+C | Exit diff mode. |
## Navigation shortcuts in the interactive interface
| Shortcut | Purpose |
|-------------------------------------|----------------------------------------------|
| Ctrl+A | Move to beginning of the line (when typing). |
| Ctrl+B | Move to the previous character. |
| Ctrl+E | Move to end of the line (when typing). |
| Ctrl+F | Move to the next character. |
| Ctrl+H | Delete the previous character. |
| Ctrl+K | Delete from cursor to end of the line. If the cursor is at the end of the line, delete the line break. |
| Ctrl+U | Delete from cursor to beginning of the line. |
| Ctrl+W | Delete the previous word. |
| Home | Move to the start of the current visual line. |
| End | Move to the end of the current visual line. |
| Ctrl+Home | Move to the start of the text. |
| Ctrl+End | Move to the end of the text. |
| Alt+←/→ (Windows/Linux)
Option+←/→ (Mac) | Move the cursor by a word. |
| ↑/↓ | Navigate the command history. |
| Tab / Ctrl+Y | Accept the current inline completion suggestion. |
## Slash commands in the interactive interface
These are the slash commands you can use from within an interactive CLI session. A subset of these slash commands is available to clients that use the CLI via its ACP server. For more information, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/acp-server).
| Command | Purpose |
|-----------------------------------------------------|---------|
| `/add-dir PATH` | Add a directory to the allowed list for file access. |
| `/after [DELAY PROMPT]`, `/after` | Schedule a non-recurring prompt, skill, or schedulable slash command for the current session (for example, `/after 30m remind me the time` or `/after 1h /chronicle standup`). With no arguments the schedule manager is displayed. {% data reusables.copilot.experimental %} |
| `/agent` | Browse and select from available agents (if any). See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-custom-agents). |
| `/app` | Launch the {% data variables.copilot.github_copilot_app %}, or show the download URL if the app is not installed. |
| `/ask QUESTION` | Ask a quick side question without adding to the conversation history. |
| `/allow-all [on\|off\|show]`, `/yolo [on\|off\|show]` | Enable all permissions (tools, paths, and URLs). |
| `/changelog [summarize] [VERSION\|last N\|since VERSION]`, `/release-notes [summarize] [VERSION\|last N\|since VERSION]` | Display the CLI changelog. Optionally specify a version, a count of recent releases, or a starting version. Add the keyword `summarize` for an AI-generated summary. |
| `/chronicle ` | Session history tools and insights. The `skills` subcommands draft, review, and track the status of repository skill proposals generated from observed usage. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/chronicle). |
| `/clear [PROMPT]`, `/new [PROMPT]`, `/reset [PROMPT]` | Start a new conversation. |
| `/clikit [COMPONENT]` | Preview CLI business components (for example, quota info). |
| `/compact [FOCUS-INSTRUCTIONS]` | Summarize the conversation history to reduce context window usage. Optionally provide focus instructions to steer the summary—for example, `/compact focus on the auth module`. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/context-management#compaction). |
| `/context` | Show the context window token usage and visualization. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/context-management#checking-your-context-usage). |
| `/copy` | Copy the last response to the clipboard. |
| `/cwd`, `/cd [PATH]` | Change the working directory or display the current directory. |
| `/delegate [PROMPT]` | Delegate changes to a remote repository with an AI-generated pull request. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/delegate-tasks-to-cca). |
| `/diff` | Review changes in the current directory; auto-switches to branch diff when the working tree is clean (experimental). |
| `/downgrade VERSION` | Download and restart into a specific CLI version. Available for team accounts. |
| `/env` | Show loaded environment details (instructions, MCP servers, skills, agents, hooks, plugins, LSPs, extensions). |
| `/every [INTERVAL PROMPT]`, `/every` | Schedule a recurring prompt, skill, or schedulable slash command for the current session (for example, `/every 1h run tests` or `/every 1d /chronicle standup`). With no arguments the schedule manager is displayed. {% data reusables.copilot.experimental %} |
| `/exit`, `/quit` | Exit the CLI. |
| `/extensions [manage\|mode]`, `/extension` | Manage CLI extensions. |
| `/experimental [on\|off\|show]` | Toggle, set, or show experimental features. |
| `/feedback`, `/bug` | Provide feedback about the CLI. |
| `/fleet [PROMPT]` | Enable parallel subagent execution of parts of a task. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/fleet). |
| `/help` | Show the help for interactive commands. |
| `/ide` | Connect to an IDE workspace. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/connecting-vs-code#managing-the-connection-with-the-ide-slash-command). |
| `/init` | Initialize {% data variables.product.prodname_copilot_short %} custom instructions and agentic features for this repository. See [Project initialization for {% data variables.product.prodname_copilot_short %}](#project-initialization-for-copilot). |
| `/instructions` | View and toggle custom instruction files. |
| `/keep-alive [on\|off\|busy\|DURATION]`, `/caffeinate [on\|off\|busy\|DURATION]` | Prevent the machine from going to sleep: while a CLI session is active, while the agent is busy, or for a defined length of time. Accepts durations like `30`, `30m`, `2h`, `1d` (bare numbers default to minutes). |
| `/limits` | Open the interactive response limits dialog. |
| `/limits set max-ai-credits VALUE` | Set a soft maximum for AI Credits allowed per response. Response limits are soft limits that reset for each user message. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/set-session-limit). |
| `/limits unset [max-ai-credits\|all]` | Remove a specific response limit, or all response limits. |
| `/list-dirs` | Display all of the directories for which file access has been allowed. |
| `/login` | Log in to {% data variables.product.prodname_copilot_short %}. |
| `/logout` | Log out of {% data variables.product.prodname_copilot_short %}. |
| `/lsp [show\|test\|reload\|logs\|help] [SERVER-NAME]` | Manage the language server configuration. The `logs` subcommand opens the live LSP services log panel. |
| `/mcp [list\|show\|add\|edit\|delete\|disable\|enable\|auth\|reload\|search] [SERVER-NAME]` | Manage the MCP server configuration. `list` (alias `ls`) prints a plain-text list of configured servers with connection status and live state, and is read-only, so it can run while the agent is busy processing a turn; all other subcommands are blocked until the turn finishes. Sandboxed local servers show a `connected (sandboxed)` status. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers#managing-mcp-servers). |
| `/model [--repo\|--local] [MODEL]`, `/models` | Select the AI model you want to use, or choose **Auto**. `--repo`/`--local` pins the default model in repository settings instead of the current session. Press Tab on a model with a long-context variant to toggle its Context column between the default and long-context window. See [AUTOTITLE](/copilot/concepts/models/auto-model-selection). |
| `/permissions [show\|reset]` | View or clear in-memory tool and path approvals for the current session. |
| `/plan [PROMPT]` | Create an implementation plan before coding. |
| `/plugin [marketplace\|install\|uninstall\|update\|list] [ARGS...]` | Manage plugins and plugin marketplaces. `list` (alias `ls`, including bare `/plugin`) is read-only and can run while the agent is busy processing a turn; all other subcommands are blocked until the turn finishes. See [AUTOTITLE](/copilot/concepts/agents/about-plugins). |
| `/pr [view\|create\|fix\|auto\|automerge]` | Manage pull requests for the current branch. `auto` drives the pull request to green and stops; `automerge` (alias: `agentmerge`) drives the pull request to green and merges it. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests). |
| `/refine TEXT` | Rewrite a roughly composed prompt into a clear one for review. Run with no arguments (via Ctrl+X then `/refine`) to clean up the current input box. Can be particularly useful for prompts entered by speaking. |
| `/remote [on\|off]` | Show the remote control status (if no argument provided), enable remote steering (`on`), or end the remote connection (`off`). See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely). |
| `/rename [NAME]` | Rename the current session (auto-generates a name if omitted; alias for `/session rename`). |
| `/research TOPIC` | Run a deep research investigation using {% data variables.product.github %} search and web sources. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/research). |
| `/reset-allowed-tools` | Reset the list of allowed tools. |
| `/restart` | Restart the CLI, preserving the current session. |
| `/resume [SESSION-ID]`, `/continue [SESSION-ID]` | Switch to a different session by choosing from a list (optionally specify a session ID). |
| `/review [PROMPT]` | Run the code review agent to analyze changes. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review). |
| `/rubber-duck [PROMPT]` | Consult the rubber duck agent for a second opinion on plans, code, and tests. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/rubber-duck). |
| `/sandbox [enable\|disable]` | Enable, disable, or configure OS-level sandboxing that restricts filesystem and network access for shell commands, MCP/LSP servers, and built-in file/web tools. Run `/sandbox` with no arguments to open the policy dialog. |
| `/search [QUERY]`, `/find [QUERY]` | Search the conversation timeline. {% data reusables.copilot.experimental %} |
| `/security-review [PROMPT]` | Run a focused security review of active local code changes and return prioritized vulnerability findings with remediation suggestions. This command is not a full repository security audit. |
| `/session [info\|checkpoints [n]\|files\|plan\|rename [NAME]\|cleanup\|prune\|delete [ID]\|delete-all]`, `/sessions [info\|checkpoints [n]\|files\|plan\|rename [NAME]\|cleanup\|prune\|delete [ID]\|delete-all]` | Show session information and manage sessions. The `info` subcommand shows session details including the session link (when available). Subcommands: `info`, `checkpoints`, `files`, `plan`, `rename`, `cleanup`, `prune`, `delete`, `delete-all`. |
| `/settings [--repo\|--local] [show KEY\|KEY\|KEY VALUE]`,
`/config [--repo\|--local] [show KEY\|KEY\|KEY VALUE]` | Open the settings dialog, open it focused on a specific setting (`KEY`), set a setting inline (`KEY VALUE`), or display a setting's current value (`show KEY`). The dialog shows **User**, **Repo**, and **Repo (local)** tabs—switch with Tab/Shift+Tab; a setting overridden in another scope shows a badge naming which scope wins. Add `--repo` or `--local` to target `.github/copilot/settings.json` or `.github/copilot/settings.local.json` instead of the user settings file—for example, `/settings --repo model gpt-5.2`. Only [repo-overridable keys](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#repository-settings-githubcopilotsettingsjson) can be set this way. Rows governed by an active organization or MDM managed policy render read-only with a `(managed)` tag. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/change-settings). |
| `/share [link\|off\|file\|html\|gist\|research] [...]`, `/export [...]` | Share the current session. With no subcommand, generates a shareable {% data variables.product.github %} link when you're logged in and synced (falls back to Markdown file export otherwise). `off` stops sharing. `link` is an explicit alias for the default link flow; `link off` stops link sharing. `file [session\|research] [PATH]` exports to a Markdown file. `html [session\|research] [PATH]` exports to an HTML file. `gist [session\|research]` creates a {% data variables.product.github %} gist. `research [PATH]` exports the research report. |
| `/skills [list\|info\|add\|remove\|reload] [ARGS...]` | Manage skills for enhanced capabilities. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-skills). |
| `/statusline`, `/footer` | Configure which items appear in the status line. |
| `/subagents`, `/agents` | Configure default and per-agent subagent models. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings). |
| `/tasks` | View and manage tasks (subagents and shell commands). |
| `/terminal-setup` | Configure the terminal for multiline input support (Shift+Enter and Ctrl+Enter). |
| `/theme [default\|github\|dim\|high-contrast\|colorblind]` | View or set the color mode. |
| `/tuikit [colors\|icons\|select\|tabbar]` | Preview TUIkit design-system components and color tokens. |
| `/undo`, `/rewind` | Rewind the last turn and revert file changes. File tracking is done via the tool layer and does not require Git. |
| `/update`, `/upgrade` | Update the CLI to the latest version. |
| `/usage` | Display session usage metrics and statistics, including per-model token totals. |
| `/user [show\|list\|switch]` | Manage the current {% data variables.product.github %} user. |
| `/version` | Display version information and check for updates. |
| `/voice [on\|off\|models\|devices]` | Toggle voice mode, browse available voice models, or choose the input device (microphone). |
| `/fork [NAME]`, `/branch [NAME]` | Fork the current session into a new session, optionally with a name. {% data reusables.copilot.experimental %} |
| `/worktree [branch\|task]` | Create a new Git worktree off `HEAD` and switch to it, leaving uncommitted changes behind in the current worktree. Pass a branch name, a task description (multiline supported, used as the opening prompt in the new worktree), or omit the argument to auto-generate a branch name from the conversation. Requires a Git repository. {% data reusables.copilot.experimental %} |
| `/move [branch\|task]` | Move uncommitted changes into a new Git worktree and switch to it. Pass a branch name, a task description (multiline supported, used as the opening prompt in the new worktree), or omit the argument to auto-generate a branch name from the conversation. Requires a Git repository. {% data reusables.copilot.experimental %} |
For a complete list of available slash commands enter `/help` in the CLI's interactive interface.
## Command-line options
| Option | Purpose |
|------------------------------------|------------------------------------------|
| `--add-dir=PATH` | Add a directory to the allowed list for file access (can be used multiple times). |
| `--add-github-mcp-tool=TOOL` | Add a tool to enable for the {% data variables.product.github %} MCP server, instead of the default CLI subset (can be used multiple times). Use `*` for all tools. |
| `--add-github-mcp-toolset=TOOLSET` | Add a toolset to enable for the {% data variables.product.github %} MCP server, instead of the default CLI subset (can be used multiple times). Use `all` for all toolsets. |
| `--additional-mcp-config=JSON` | Add an MCP server for this session only. The server configuration can be supplied as a JSON string or a file path (prefix with `@`). Augments the configuration from `~/.copilot/mcp-config.json`. Overrides any installed MCP server configuration with the same name. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers). |
| `--agent=AGENT` | Specify a {% data variables.copilot.copilot_custom_agent_short %} to use. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-custom-agents). |
| `--allow-all` | Enable all permissions (equivalent to `--allow-all-tools --allow-all-paths --allow-all-urls`). |
| `--allow-all-mcp-server-instructions` | Include initialization instructions from all MCP servers in the system prompt. By default, only allowlisted server instructions are included up front; other servers' instructions are retrieved on demand. |
| `--allow-all-paths` | Disable file path verification and allow access to any path. |
| `--allow-all-tools` | Allow all tools to run automatically without confirmation. Required when using the CLI programmatically (env: `COPILOT_ALLOW_ALL`). |
| `--allow-all-urls` | Allow access to all URLs without confirmation. |
| `--allow-tool=TOOL ...` | Tools the CLI has permission to use. Will not prompt for permission. For multiple tools, use a quoted, comma-separated list. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools#allowing-or-denying-permission-for-specific-tools). |
| `--allow-url=URL ...` | Allow access to specific URLs or domains. For multiple URLs, use a quoted, comma-separated list. |
| `--acp` | Start as Agent Client Protocol server. |
| `--attachment PATH` | Attach a file to the initial prompt (can be used multiple times). Image files are accepted, but sending them successfully requires the selected model and organization policy to allow vision input. |
| `--autopilot` | Enable autopilot continuation—the agent keeps working until `task_complete` is called, then returns to interactive mode. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/autopilot). |
| `--available-tools=TOOL ...` | Only these tools will be available to the model. For multiple tools, use a quoted, comma-separated list. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools). |
| `--banner`, `--no-banner` | Show or hide the startup banner. |
| `--bash-env` | Enable `BASH_ENV` support for bash shells. |
| `-C DIRECTORY` | Change working directory before doing anything else. |
| `--connect[=SESSION-ID]` | Connect directly to a remote session (optionally specify a session ID or task ID). Conflicts with `--resume` and `--continue`. |
| `--context TIER`. | Set the context window tier for tiered-pricing models (overrides the persisted setting and is honored in fresh interactive sessions). Choices: "default", "long_context". |
| `--config-dir=DIRECTORY` | This option for setting the configuration directory is deprecated. Use the `COPILOT_HOME` environment variable instead. |
| `--continue` | Resume the most recent session in the current working directory, falling back to the globally most recent session. Conflicts with `--resume`. |
| `--deny-tool=TOOL ...` | Tools the CLI does not have permission to use. Will not prompt for permission. For multiple tools, use a quoted, comma-separated list. |
| `--deny-url=URL ...` | Deny access to specific URLs or domains, takes precedence over `--allow-url`. For multiple URLs, use a quoted, comma-separated list. |
| `--disable-builtin-mcps` | Disable all built-in MCP servers (currently: `github-mcp-server`). |
| `--disable-mcp-server=SERVER-NAME` | Disable a specific MCP server (can be used multiple times). |
| `--disallow-temp-dir` | Prevent automatic access to the system temporary directory. |
| `--effort=LEVEL`, `--reasoning-effort=LEVEL` | Set the reasoning effort level (`low`, `medium`, `high`, `xhigh`, `max`). `max` is the highest-depth tier for Anthropic models. |
| `--enable-all-github-mcp-tools` | Enable all {% data variables.product.github %} MCP server tools, instead of the default CLI subset. Overrides the `--add-github-mcp-toolset` and `--add-github-mcp-tool` options. |
| `--enable-memory` | Enable memory in prompt mode (disabled by default). |
| `--enable-reasoning-summaries` | Request reasoning summaries for OpenAI models that support it. |
| `--excluded-tools=TOOL ...` | These tools will not be available to the model. For multiple tools, use a quoted, comma-separated list. |
| `--experimental` | Enable experimental features (use `--no-experimental` to disable). |
| `--extension-sdk-path DIRECTORY` | Override the bundled `@github/copilot-sdk` injected into extension subprocesses with a local `copilot-sdk/` folder. Invalid paths fall back to the bundled SDK. |
| `-h`, `--help` | Display help. |
| `-i PROMPT`, `--interactive=PROMPT` | Start an interactive session and automatically execute this prompt. |
| `--log-dir=DIRECTORY` | Set the log file directory (default: `~/.copilot/logs/`). |
| `--log-level=LEVEL` | Set the log level (choices: `none`, `error`, `warning`, `info`, `debug`, `all`, `default`). |
| `--max-ai-credits=CREDITS` | Set a soft maximum for AI Credits allowed for each response. The limit resets per user message and can be adjusted mid-session with `/limits`. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/set-session-limit). |
| `--max-autopilot-continues=COUNT` | Maximum number of continuation messages in autopilot mode (default: unlimited). Must be a non-negative integer; malformed values (`NaN`, negative, or fractional) are rejected. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/autopilot). |
| `--mode=MODE` | Set the initial agent mode (choices: `interactive`, `plan`, `autopilot`). Cannot be combined with `--autopilot` or `--plan`. |
| `--model=MODEL` | Set the AI model you want to use. Pass `auto` as the value to let {% data variables.product.prodname_copilot_short %} pick the best available model automatically. See [AUTOTITLE](/copilot/concepts/models/auto-model-selection). |
| `--mouse[=VALUE]` | Enable or disable mouse support in the interactive interface. VALUE can be `on` (default) or `off`. When enabled, the CLI captures mouse events—scroll wheel, clicks, and so on—to navigate its own interface, such as scrolling the timeline or clicking tabs. When disabled, the terminal's native mouse behavior, such as text selection and scrollback, is preserved. When you set this option explicitly, the value is persisted to your configuration file. |
| `-n NAME`, `--name=NAME` | Set a name for the new session. Used by `--resume` and `/resume` to find sessions by name. |
| `--no-ask-user` | Disable the `ask_user` tool (the agent works autonomously without asking questions). |
| `--no-auto-update` | Disable downloading CLI updates automatically. |
| `--no-bash-env` | Disable `BASH_ENV` support for bash shells. |
| `--no-color` | Disable all color output. |
| `--no-custom-instructions` | Disable loading of custom instructions from `AGENTS.md` and related files. |
| `--no-experimental` | Disable experimental features. |
| `--no-mouse` | Disable mouse support. |
| `--no-remote` | Disable remote access for this session. |
| `--no-remote-export` | Disable exporting your session to {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_mobile %} (also disables remote control). |
| `--output-format=FORMAT` | FORMAT can be `text` (default) or `json` (outputs JSONL: one JSON object per line). |
| `-p PROMPT`, `--prompt=PROMPT` | Execute a prompt programmatically (exits after completion). The exit summary includes a `copilot --resume=SESSION-ID` hint for continuing the session. See [AUTOTITLE](/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically). |
| `--plan` | Start in plan mode. Shorthand for `--mode plan`. Cannot be combined with `--mode` or `--autopilot`. |
| `--plain-diff` | Disable rich diff rendering (syntax highlighting via the diff tool specified by your Git config). |
| `--plugin-dir=DIRECTORY` | Load a plugin from a local directory (can be used multiple times). |
| `--remote` | Enable remote access to this session from {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_mobile %}. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely). |
| `--remote-export` | Export your session to {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_mobile %} (read-only; does not enable remote control). |
| `-r`, `--resume[=VALUE]` | Resume a previous interactive session by choosing from a list. Optionally specify a session ID, ID prefix, or session name. Name matching is exact and case-insensitive; falls back to the auto-generated summary when no explicit name matches. Conflicts with `--continue`. |
| `-s`, `--silent` | Output only the agent response (without usage statistics), useful for scripting with `-p`. |
| `--screen-reader` | Enable screen reader optimizations. |
| `--secret-env-vars=VAR ...` | Redact an environment variable from shell and MCP server environments (can be used multiple times). For multiple variables, use a quoted, comma-separated list. The values in the `GITHUB_TOKEN` and `COPILOT_GITHUB_TOKEN` environment variables are redacted from output by default. |
| `--session-id ID` | Use an exact session or task ID when you do not want `--resume`'s broader matching by ID prefix or session name. If the ID matches an existing session or task, that session or task is resumed. If nothing matches, a new session is created only when the value is a valid UUID. Names and ID prefixes do not create new sessions. Do not combine this option with other session-selection or session-starting options such as `--resume`, `--continue`, or `--connect`, because they compete to decide which session to open or create. |
| `--sandbox` | Enable the OS-level shell sandbox for this session only, without changing your saved sandbox setting. Useful with `-p`. {% data reusables.copilot.experimental %} |
| `--no-sandbox` | Disable the OS-level shell sandbox for this session only, without changing your saved sandbox setting. {% data reusables.copilot.experimental %} |
| `--share=PATH` | Share a session to a Markdown file after completion of a programmatic session (default path: `./copilot-session-.md`). |
| `--share-gist` | Share a session to a secret {% data variables.product.github %} gist after completion of a programmatic session. |
| `--stream=MODE` | Enable or disable streaming mode, which displays {% data variables.product.prodname_copilot_short %}'s response progressively as it is generated rather than waiting for the full response to arrive (mode choices: `on` or `off`, default: `on`).
| `-v`, `--version` | Show version information. |
| `-w`, `--worktree[=NAME]` | Create or reuse an isolated Git worktree under `.worktrees/` and start the session inside it. `NAME` is optional—omit it to auto-generate a branch name. Conflicts with `--resume`, `--continue`, and `--connect`. {% data reusables.copilot.experimental %} |
| `--yolo` | Enable all permissions (equivalent to `--allow-all`). |
For a complete list of commands and options, run `copilot help`.
> [!NOTE]
> The `--remote`, `--no-remote`, `--remote-export`, `--no-remote-export`, and `--connect` options require the remote sessions feature to be available on your account.
You can use `--remote` with `--resume ` to resume a remote task locally. This works even when the task was originally created outside a Git repository.
> [!NOTE]
> When `permissions.disableBypassPermissionsMode` is set to `"disable"`, all allow-all flags (`--allow-all-tools`, `--allow-all-paths`, `--allow-all-urls`, `--allow-all`, `--yolo`) are suppressed at startup and cannot be used to grant elevated permissions.
Three sources can set this restriction, in increasing order of permanence:
| Source | Scope | Cleared by account switch? |
|--------|-------|---------------------------|
| User settings (`~/.copilot/settings.json`) | Machine | No — applies to all accounts |
| Managed settings (server-fetched per account) | Account | Yes — cleared when switching to a different account that does not disable bypass mode |
| MDM policy (plist/registry/file) | Device | Never — device-level policy that cannot be overridden by account switches |
For MDM configuration details, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#mdm-managed-settings).
## Supported models
Use `--model=MODEL` or the `COPILOT_MODEL` environment variable to select the AI model. Pass `auto` to let {% data variables.product.prodname_copilot_short %} pick the best available model automatically.
| Model | Best for |
|-------|----------|
| `claude-sonnet-4.6` | General-purpose coding (default) |
| `gpt-5.4` | Complex reasoning tasks |
| `claude-haiku-4.5` | Fast, lightweight operations |
| `gpt-5.3-codex` | Code-focused tasks |
| `gemini-3.1-pro-preview` | Google Gemini reasoning |
| `gemini-3.5-flash` | Fast Google Gemini responses |
| `mai-code-1-flash` | Fast, adaptive coding tasks |
You can also switch models during an interactive session using the `/model` slash command.
## Tool availability values
The `--available-tools` and `--excluded-tools` options support these values:
### Shell tools
| Tool name | Description |
|---|---|
| `bash` / `powershell` | Execute commands |
| `list_bash` / `list_powershell` | List active shell sessions |
| `read_bash` / `read_powershell` | Read output from a shell session |
| `stop_bash` / `stop_powershell` | Terminate a shell session |
| `write_bash` / `write_powershell` | Send input to a shell session |
### File operation tools
| Tool name | Description |
|---|---|
| `apply_patch` | Apply patches (used by some models instead of `edit`/`create`) |
| `create` | Create new files |
| `edit` | Edit files via string replacement |
| `view` | Read files or directories |
### Agent and task delegation tools
| Tool name | Description |
|---|---|
| `list_agents` | List available agents |
| `read_agent` | Check background agent status |
| `task` | Run subagents |
| `write_agent` | Send a message to a running agent |
### Other tools
| Tool name | Description |
|---|---|
| `ask_user` | Ask the user a question |
| `glob` | Find files matching patterns |
| `grep` (or `rg`) | Search for text in files |
| `skill` | Invoke custom skills |
| `web_fetch` | Fetch and parse web content |
## Tool permission patterns
The `--allow-tool` and `--deny-tool` options accept permission patterns in the format `Kind(argument)`. The argument is optional—omitting it matches all tools of that kind.
| Kind | Description | Example patterns |
|------|-------------|-----------------|
| `memory` | Storing facts to agent memory | `memory` |
| `read` | File or directory reads | `read`, `read(.env)` |
| `shell` | Shell command execution | `shell(git push)`, `shell(git:*)`, `shell` |
| `url` | URL access via web-fetch or shell | `url(github.com)`, `url(https://*.api.com)` |
| `write` | File creation or modification | `write`, `write(src/*.ts)` |
| SERVER-NAME | MCP server tool invocation | `MyMCP(create_issue)`, `MyMCP` |
For `shell` rules, the `:*` suffix matches the command stem followed by a space, preventing partial matches. For example, `shell(git:*)` matches `git push` and `git pull` but does not match `gitea`.
Deny rules always take precedence over allow rules, even when `--allow-all` is set.
```shell
# Allow all git commands except git push
copilot --allow-tool='shell(git:*)' --deny-tool='shell(git push)'
# Allow a specific MCP server tool
copilot --allow-tool='MyMCP(create_issue)'
# Allow all tools from a server
copilot --allow-tool='MyMCP'
# Deny writes to a specific path (exact or trailing-path-segment match; no glob support yet)
copilot --deny-tool='write(secret.txt)'
```
`--deny-tool='write(PATH)'` scopes the denial to that path—other writes are unaffected. The match resolves symlinks and `.`/`..` segments, and is case-insensitive on macOS and Windows.
## Environment variables
| Variable | Description |
|----------|-------------|
| `COPILOT_ALLOW_ALL` | Set to `true` to allow all permissions automatically (equivalent to `--allow-all`). |
| `COPILOT_AUTO_UPDATE` | Set to `false` to disable automatic updates. |
| `COPILOT_CACHE_HOME` | Override the cache directory (used for marketplace caches, auto-update packages, and other ephemeral data). See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#changing-the-location-of-the-configuration-directory) for platform defaults. |
| `COPILOT_COMPUTER_USE_LINUX` | Set to opt in to the `computer-use` MCP server on Linux distributions that support it. The `computer-use` server is not available on Alpine Linux (musl libc). |
| `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` | Comma-separated list of additional directories for custom instructions. |
| `COPILOT_EDITOR` | Editor command for interactive editing (checked after `$VISUAL` and `$EDITOR`). Defaults to `vi` if none are set. |
| `COPILOT_ENABLE_HTTP2` | Set to `1` or `true` to opt into HTTP/2 transport. HTTP/1.1 is the default. |
| `COPILOT_GH_HOST` |{% data variables.product.github %} hostname for {% data variables.copilot.copilot_cli_short %} only, overriding `GH_HOST`. Use when `GH_HOST` targets {% data variables.product.prodname_ghe_server %} but {% data variables.product.prodname_copilot_short %} needs to authenticate against {% data variables.product.prodname_dotcom_the_website %} or a {% data variables.product.prodname_ghe_cloud %} hostname. |
| `COPILOT_GITHUB_TOKEN` | Authentication token. Takes precedence over `GH_TOKEN` and `GITHUB_TOKEN`. |
| `COPILOT_HOME` | Override the configuration and state directory. Default: `$HOME/.copilot`. |
| `COPILOT_LARGE_OUTPUT_THRESHOLD_BYTES` | Maximum UTF-8 byte size for tool output returned directly to the model. Default: `20480` (20 KiB). See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/context-management#managing-large-tool-output). |
| `COPILOT_MODEL` | Set the AI model. |
| `COPILOT_PROMPT_FRAME` | Set to `1` to enable the decorative UI frame around the input prompt, or `0` to disable it. Overrides the `PROMPT_FRAME` experimental feature flag for the current session. |
| `COPILOT_SKILLS_DIRS` | Comma-separated list of additional directories for skills. |
| `COPILOT_STRIP_REASONING_ON_RESUME` | Set to `0` or `false` to keep BYOK reasoning tokens across a session resume instead of stripping them. Defaults to stripping them. |
| `COPILOT_SUBAGENT_MAX_CONCURRENT` | Maximum concurrent subagents per session (default: `32`, range: `1`–`256`). |
| `COPILOT_SUBAGENT_MAX_DEPTH` | Maximum subagent nesting depth (default: `4`, range: `1`–`128`). |
| `COPILOT_TASK_WAIT_TIMEOUT_SECONDS` | Maximum seconds `-p` (and `-p --autopilot`) waits for pending background agents or shell commands to finish before exiting (default: `600`; `0` exits immediately without waiting). |
| `GH_HOST` | {% data variables.product.github %} hostname for both {% data variables.product.prodname_cli %} and {% data variables.copilot.copilot_cli_short %} (default: `github.com`). Set to your {% data variables.product.prodname_ghe_cloud %} with data residency hostname. Override with `COPILOT_GH_HOST` for {% data variables.copilot.copilot_cli_short %} only. |
| `GH_TOKEN` | Authentication token. Takes precedence over `GITHUB_TOKEN`. |
| `GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS` | Set to `true` to load project extensions and allow extension management tools in prompt mode (`-p`). Disabled by default to prevent running repository-controlled extension code without interactive trust. |
| `GITHUB_COPILOT_PROMPT_MODE_REPO_HOOKS` | Set to `true` to load repository hooks in prompt mode (`-p`). Repository hooks also load automatically when the folder is already trusted or `COPILOT_ALLOW_ALL` is set. |
| `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP` | Set to `true` to load workspace MCP sources in prompt mode (`-p`). Disabled by default to prevent starting repository-controlled MCP servers without interactive trust. |
| `GITHUB_TOKEN` | Authentication token. |
| `PLAIN_DIFF` | Set to `true` to disable rich diff rendering. |
| `USE_BUILTIN_RIPGREP` | Set to `false` to use the system ripgrep instead of the bundled version. |
## Configuration file settings
For detailed information about configuration file settings—including the full list of user settings, repository settings, local settings, and how they cascade—see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings).
> [!NOTE]
> User settings were previously stored in `~/.copilot/config.json`. Existing user-editable settings in that location are automatically migrated to `~/.copilot/settings.json` on startup.
## Project initialization for {% data variables.product.prodname_copilot_short %}
When you use the command `copilot init`, or the slash command `/init` within an interactive session, {% data variables.product.prodname_copilot_short %} analyzes your codebase and writes or updates a `.github/copilot-instructions.md` file in the repository. This custom instructions file contains project-specific guidance that will improve future CLI sessions.
You will typically use `copilot init`, or `/init`, when you start a new project, or when you start using {% data variables.copilot.copilot_cli_short %} in an existing repository.
The `copilot-instructions.md` file that's created or updated typically documents:
* Build, test, and lint commands.
* High-level architecture.
* Codebase-specific conventions.
If the file already exists, {% data variables.product.prodname_copilot_short %} suggests improvements which you can choose to apply or reject.
The CLI looks for the `copilot-instructions.md` file on startup, and if it's missing, it displays the message:
> 💡 No copilot instructions found. Run /init to generate a copilot-instructions.md file for this project.
If you don't want to create this file, you can permanently hide this startup message for the current repository by using the `/init suppress` slash command.
For more information, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions).
### Custom instructions locations
{% data variables.copilot.copilot_cli_short %} loads custom instructions from these locations simultaneously (all are merged):
| Location | Notes |
|----------|-------|
| `CLAUDE.md` | In Git root and cwd |
| `GEMINI.md` | In Git root and cwd |
| `AGENTS.md` | In Git root and cwd |
| `.github/instructions/**/*.instructions.md` | In Git root and cwd |
| `.github/copilot-instructions.md` | In Git root and cwd |
| `$HOME/.copilot/copilot-instructions.md` | — |
| `$HOME/.copilot/instructions/**/*.instructions.md` | — |
| `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` | Additional directories via environment variable. |
### Custom instructions imports
Instruction files support `@path` imports. Prefix a line with `@` followed by a path to inline the contents of another file. Paths can be relative to the instruction file's directory or absolute. Imports are resolved recursively, up to a depth limit, with cycle and size guards. This is supported in `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`.
## Hooks reference
For detailed information about hooks—including hook configuration formats, hook events, input payloads, and decision control—see [AUTOTITLE](/copilot/reference/hooks-reference).
## MCP server configuration
MCP servers provide additional tools to the CLI agent. Configure persistent servers in `~/.copilot/mcp-config.json`. Use `--additional-mcp-config` to add servers for a single session.
Local (stdio) servers that spawn inside the sandbox (see the `/sandbox` slash command) show a `connected (sandboxed)` status in `copilot mcp list` and `/mcp list`, since remote (HTTP/SSE) servers are never sandboxed. {% data reusables.copilot.experimental %}
### `copilot mcp` subcommand
Use `copilot mcp` to manage MCP server configurations from the command line without starting an interactive session.
| Subcommand | Description |
|------------|-------------|
| `list [--json]` | List all configured MCP servers grouped by source, including plugin-provided servers. |
| `get [--json]` | Show configuration and tools for a specific server. For plugin-provided servers, also shows the source plugin name and version. |
| `add ` | Add a server to the user configuration. Writes to `~/.copilot/mcp-config.json`. |
| `remove ` | Remove a user-level server. Workspace servers must be edited in their configuration files directly. |
**`copilot mcp add` options:**
| Option | Description |
|--------|-------------|
| `-- [args...]` | Command and arguments for local (stdio) servers. |
| `--url ` | URL for remote servers. |
| `--type ` | Transport type: `local`, `stdio`, `http`, or `sse`. |
| `--env KEY=VALUE` | Environment variable (repeatable). |
| `--header KEY=VALUE` | HTTP header for remote servers (repeatable). |
| `--tools ` | Tool filter: `"*"` for all, a comma-separated list, or `""` for none. |
| `--timeout ` | Timeout in milliseconds. |
| `--json` | Output added configuration as JSON. |
| `--show-secrets` | Show full environment variable and header values. |
> [!CAUTION]
> `--show-secrets` can print sensitive environment variable and header values to your terminal or logs. Only use this option in trusted environments, and avoid copying, pasting, or otherwise capturing the output in shared logs or history.
### Transport types
| Type | Description | Required fields |
|------|-------------|----------------|
| `local` / `stdio` | Local process communicating via stdin/stdout. | `command`, `args` |
| `http` | Remote server using streamable HTTP transport. | `url` |
| `sse` | Remote server using Server-Sent Events transport. | `url` |
### Local server configuration fields
| Field | Required | Description |
|-------|----------|-------------|
| `command` | Yes | Command to start the server. |
| `args` | Yes | Command arguments (array). |
| `tools` | Yes | Tools to enable: `["*"]` for all, or a list of specific tool names. |
| `env` | No | Environment variables. Supports `$VAR`, `${VAR}`, and `${VAR:-default}` expansion. |
| `cwd` | No | Working directory for the server. |
| `timeout` | No | Tool call timeout in milliseconds. |
| `type` | No | `"local"` or `"stdio"`. Default: `"local"`. |
| `deferTools` | No | `"auto"` (default) or `"never"`. Set to `"never"` to keep this server's tools always visible even when tool search is active. |
### Private npm registry
Use `--registry` in the `args` array to pull a package from a private npm registry—for example, Artifactory or a {% data variables.product.github %} Packages feed:
```json
{
"mcpServers": {
"my-internal-server": {
"command": "npx",
"args": [
"--registry", "https://npm.pkg.github.com",
"@my-org/internal-mcp-server"
],
"tools": ["*"]
}
}
}
```
The `--registry` flag and other npm configuration flags (`--userconfig`, `--globalconfig`, `--prefix`, `--cache`, `--node-options`, `--workspace`, `-w`) are treated as value-consuming arguments when computing the server's identity fingerprint. This ensures enterprise allowlist checks and registry verification work correctly when these flags appear before the package name.
### Remote server configuration fields
| Field | Required | Description |
|-------|----------|-------------|
| `type` | Yes | `"http"` or `"sse"`. |
| `url` | Yes | Server URL. |
| `tools` | Yes | Tools to enable. |
| `headers` | No | HTTP headers. Supports variable expansion. |
| `oauthClientId` | No | Static OAuth client ID (skips dynamic registration). |
| `oauthPublicClient` | No | Whether the OAuth client is public. Default: `true`. Set to `false` for confidential clients with a stored secret. |
| `oauthGrantType` | No | OAuth grant type: `"authorization_code"` (default, browser-based flow) or `"client_credentials"` (fully headless, no browser or callback). |
| `oidc` | No | Enable OIDC token injection. When `true`, the CLI injects OIDC tokens for any `GITHUB_COPILOT_OIDC_MCP_TOKEN` or `GITHUB_COPILOT_OIDC_MCP_TOKEN_` variable referenced in the server's `env` block (local servers), or sends the token as a `Bearer` `Authorization` header (remote servers). For local servers, prefer suffixed variants (for example, `${GITHUB_COPILOT_OIDC_MCP_TOKEN_MY_SVC}`) to assign a unique variable name per server. |
| `timeout` | No | Tool call timeout in milliseconds. |
| `deferTools` | No | `"auto"` (default) or `"never"`. Set to `"never"` to keep this server's tools always visible even when tool search is active. |
### OAuth re-authentication
Remote MCP servers that use OAuth may show a `needs-auth` status when a token expires or when a different account is required. Use `/mcp auth ` to trigger a fresh OAuth flow. This opens a browser authentication prompt, allowing you to sign in or switch accounts. After completing the flow, the server reconnects automatically.
### Headless OAuth (`client_credentials` grant)
For CI or cron use cases where no browser is available, set `oauthGrantType: "client_credentials"`. This requires:
* `oauthClientId`—the static client ID issued by the MCP provider.
* `oauthPublicClient: false`—the client is confidential.
* A `client_secret` stored in the system keychain (configured once via the `/mcp` UI or by writing to the OAuth credential store).
When configured, the CLI skips the browser, callback server, PKCE, and dynamic client registration entirely. On every 401, it posts `grant_type=client_credentials` directly to the server's discovered token endpoint.
```json
{
"mcpServers": {
"headless-api": {
"type": "http",
"url": "https://api.example.com/mcp",
"tools": ["*"],
"oauthClientId": "YOUR-CLIENT-ID",
"oauthPublicClient": false,
"oauthGrantType": "client_credentials"
}
}
}
```
### Filter mapping
Control how MCP tool output is processed using the `filterMapping` field in a server's configuration.
| Mode | Description |
|------|-------------|
| `none` | No filtering. |
| `markdown` | Format output as Markdown. |
| `hidden_characters` | Remove hidden or control characters. Default. |
### Built-in MCP servers
The CLI includes built-in MCP servers that are available without additional setup.
| Server | Description |
|--------|-------------|
| `github-mcp-server` | {% data variables.product.github %} API integration: issues, pull requests, labels, commits, code search, and {% data variables.product.prodname_actions %}. |
| `playwright` | Browser automation: navigate, click, type, screenshot, and form handling. |
| `fetch` | HTTP requests via the `fetch` tool. |
| `time` | Time utilities: `get_current_time` and `convert_time`. |
| `computer-use` | Screen capture and mouse/keyboard automation. Not available on Alpine Linux (musl libc). Set `COPILOT_COMPUTER_USE_LINUX` to opt in on other Linux distributions where it is available. |
Use `--disable-builtin-mcps` to disable all built-in servers, or `--disable-mcp-server SERVER-NAME` to disable a specific one.
#### {% data variables.product.github %} MCP server tools
The `github-mcp-server` provides the following tools.
| Tools | Description |
|-------|-------------|
| `get_file_contents`, `search_code` | Browse repository files. |
| `list_issues`, `issue_read`, `search_issues` | Issue tracking. |
| `get_pull_request`, `list_pull_requests`, `get_pull_request_files` | Pull requests. |
| `list_commits`, `get_commit` | Commit history. |
| `list_workflow_runs`, `get_workflow_run_logs` | {% data variables.product.prodname_actions %}. |
| `get_label`, `list_label`, `label_write` | Label management. |
### MCP server naming
Server names can contain any printable characters, including spaces, Unicode characters, and punctuation. Control characters (U+0000–U+001F, U+007F) and the closing brace (`}`) are not allowed. Server names are used as prefixes for tool names—for example, a server named `my-server` produces tool names like `my-server-fetch`, and a server named `My Server` produces `My Server-fetch`.
### MCP tool name sanitization
MCP server names and tool names are sanitized before being sent to the model. Characters that are invalid in tool names (anything other than `a-z`, `A-Z`, `0-9`, `-`, `_`) are replaced with `-`. Unicode characters are Punycode-encoded. The `@` symbol is also replaced with `-` to avoid conflicts with Punycode encoding.
The combined name (`serverName-toolName`) is capped at 64 characters. When truncation would create a name collision, a numeric suffix is appended (for example, `my-server-tool2`, `my-server-tool3`) to ensure uniqueness.
### MCP server trust levels
MCP servers are loaded from multiple sources, each with a different trust level.
| Source | Trust level | Review required |
|--------|-------------|----------------|
| Built-in | High | No |
| Repository (`.github/mcp.json`) | Medium | Recommended |
| Workspace (`.mcp.json`) | Medium | Recommended |
| User config (`~/.copilot/mcp-config.json`) | User-defined | User responsibility |
| Remote servers | Low | Always |
All MCP tool invocations require explicit permission. This applies even to read-only operations on external services.
### MCP server loading priority
MCP servers from different sources are merged in priority order (highest first). When servers share a name, the higher-priority source takes precedence.
1. `--additional-mcp-config` flag (highest)
1. Plugin-provided servers
1. Workspace servers—`.mcp.json` and `.github/mcp.json` loaded from the working directory upward to the Git root; requires the folder to be trusted
1. `~/.copilot/mcp-config.json` (lowest)
> [!NOTE]
> Workspace MCP servers (`.mcp.json` and `.github/mcp.json`) are loaded in both interactive and SDK server-mode sessions, provided the working directory is trusted. For more information about folder trust, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools).
### Enterprise MCP allowlist
{% data variables.product.prodname_enterprise %} organizations can enforce an allowlist of permitted MCP servers. When active, the CLI evaluates each non-default server against the enterprise policy before connecting.
When a {% data variables.product.prodname_enterprise %} registry policy is detected (or the `MCP_ENTERPRISE_ALLOWLIST` experimental feature flag is enabled), the CLI:
1. Computes a fingerprint for each configured non-default server based on its command, arguments, and remote URL.
1. Sends the fingerprints to the enterprise allowlist evaluate endpoint.
1. Allows only servers whose fingerprints are approved; all others are blocked with a message naming the enterprise.
This check is fail-closed: if the evaluate endpoint is unreachable or returns an error, non-default servers are blocked until the policy can be verified.
When a server is blocked by an enterprise allowlist, the CLI displays:
```text
MCP server "SERVER-NAME" was blocked by your enterprise "ENTERPRISE-NAME".
Contact your enterprise administrator to add this server to the allowlist.
```
Built-in default servers are always exempt from allowlist enforcement.
### Migrating from `.vscode/mcp.json`
If your project uses `.vscode/mcp.json` (VS Code's MCP configuration format), migrate to `.mcp.json` for {% data variables.copilot.copilot_cli %}. The migration remaps the `servers` key to `mcpServers`.
**POSIX shells (bash, zsh, fish, and others):**
```shell
jq '{mcpServers: .servers}' .vscode/mcp.json > .mcp.json
```
Requires [`jq`](https://jqlang.github.io/jq/).
**PowerShell:**
```powershell
pwsh -NoProfile -Command "`$json = Get-Content '.vscode/mcp.json' -Raw | ConvertFrom-Json; `$content = ([pscustomobject]@{ mcpServers = `$json.servers } | ConvertTo-Json -Depth 100); [System.IO.File]::WriteAllText('.mcp.json', `$content, (New-Object System.Text.UTF8Encoding `$false))"
```
On Windows, replace `pwsh` with `powershell` if you are using Windows PowerShell instead of PowerShell Core.
### Stdio server output
The MCP stdio transport reserves stdout exclusively for newline-delimited JSON-RPC frames. The CLI automatically filters out any non-JSON lines—plain-text logs, exception stack traces, or whitespace-only lines—before passing output to the protocol parser.
Write all diagnostic output to **stderr**, not stdout. A server that writes logs or error messages to stdout can trigger a parse-error feedback loop that stalls the initialization handshake; the filter prevents this by silently dropping non-JSON frames.
Lines longer than 1 MB bypass the structural check and are forwarded as-is, to avoid splitting or dropping oversized but valid protocol frames (for example, a large `tools/list` response).
## Skills reference
Skills are Markdown files that extend what the CLI can do. Each skill lives in its own directory containing a `SKILL.md` file. When invoked (via `/SKILL-NAME` or automatically by the agent), the skill's content is injected into the conversation.
### Skill frontmatter fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Unique identifier for the skill. Letters, numbers, and hyphens only. Max 64 characters. |
| `description` | string | Yes | What the skill does and when to use it. Max 1024 characters. |
| `argument-hint` | string | No | Freeform hint describing expected arguments, shown in the skill picker (for example, `"[target] [mode]"`). |
| `allowed-tools` | string or string[] | No | Comma-separated list or YAML array of tools that are automatically allowed when the skill is active. Use `"*"` for all tools. |
| `user-invocable` | boolean | No | Whether users can invoke the skill with `/SKILL-NAME`. Default: `true`. |
| `disable-model-invocation` | boolean | No | Prevent the agent from automatically invoking this skill. Default: `false`. |
### Skill locations
Skills are loaded from these locations in priority order (first found wins for duplicate names).
| Location | Scope | Description |
|----------|-------|-------------|
| `.github/skills/` | Project | Project-specific skills. |
| `.agents/skills/` | Project | Alternative project location. |
| `.claude/skills/` | Project | Claude-compatible location. |
| Parent `.github/skills/` | Inherited | Monorepo parent directory support. |
| `~/.copilot/skills/` | Personal | Personal skills for all projects. |
| `~/.agents/skills/` | Personal | Agent skills shared across all projects. |
| Plugin directories | Plugin | Skills from installed plugins. |
| `COPILOT_SKILLS_DIRS` | Custom | Additional directories (comma-separated). |
| (bundled with CLI) | Built-in | Skills shipped with the CLI. Lowest priority—overridable by any other source. |
| (org/enterprise) | Remote | Skills hosted by your organization or enterprise, projected via the AHP relay. Content is fetched on demand when the skill is invoked. |
Remote skills are projected alongside local skills and follow the same name-based priority when a local skill has the same name.
When two plugins provide skills with the same name, both coexist using plugin-qualified invocation names such as `/my-plugin/search` and `/other-plugin/search`. The bare name routes to the higher-priority plugin. This applies to skills only; commands keep the standard tier-based deduplication, where the higher-priority source wins.
### Commands (alternative skill format)
Commands are an alternative to skills stored as individual `.md` files in `.claude/commands/`. The command name is derived from the filename. Command files use a simplified format (no `name` field required) and support `argument-hint`, `description`, `allowed-tools`, and `disable-model-invocation`. Commands have lower priority than skills with the same name.
## Custom agents reference
Custom agents are specialized AI agents defined in Markdown files. The filename (minus extension) becomes the agent ID. Use `.agent.md` or `.md` as the file extension.
### Built-in agents
| Agent | Default model | Description |
|-------|--------------|-------------|
| `code-review` | claude-sonnet-4.5 | High signal-to-noise code review. Analyzes diffs for bugs, security issues, and logic errors. Will not modify code. |
| `explore` | claude-haiku-4.5 | Fast codebase exploration. Searches files, reads code, and answers questions. Returns focused answers under 300 words. Safe to run in parallel. |
| `general-purpose` | claude-sonnet-4.5 | Full-capability agent for complex multi-step tasks. Runs in a separate context window. |
| `research` | claude-haiku-4.5 | Executes thorough searches based on instructions. Searches {% data variables.product.github %} repositories, fetches files, verifies claims, and reports detailed findings with citations. |
| `rubber-duck` | complementary model | Use a complementary model to provide a constructive critique of proposals, designs, implementations, or tests. Identifies weak points and suggests improvements. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/rubber-duck). |
| `security-review` | claude-sonnet-4.5 | Security-focused code review. Analyzes changes for high-confidence vulnerabilities across 11 categories. Only flags issues with >80% confidence of exploitability. Reports severity and confidence scores. Will not modify code. |
| `task` | claude-haiku-4.5 | Command execution (tests, builds, lints). Returns brief summary on success, full output on failure. |
### Custom agent frontmatter fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `description` | string | Yes | Description shown in the agent list and `task` tool. |
| `infer` | boolean | No | Allow auto-delegation by the main agent. Default: `true`. |
| `mcp-servers` | object | No | MCP servers to connect. Uses the same schema as `~/.copilot/mcp-config.json`. |
| `model` | string | No | AI model for this agent. When unset, inherits the outer agent's model. When the session model is set to `Auto` (server-selected), subagents always inherit the resolved session model regardless of this field. |
| `name` | string | No | Display name. Defaults to the filename. |
| `tools` | string[] | No | Tools available to the agent. Default: `["*"]` (all tools). |
### Custom agent locations
| Scope | Location |
|-------|----------|
| Project | `.github/agents/` or `.claude/agents/` |
| User | `~/.copilot/agents/` |
| Plugin | `/agents/` |
For project-scoped agents, the CLI walks upward from your current working directory to the Git root, loading `.github/agents/` and `.claude/agents/` directories at each ancestor level. This means each package or subdirectory in a monorepo can contribute its own agents. When multiple `.github/agents/` directories exist in the path, all are loaded, with the deepest directory taking highest priority. The `.github/agents/` convention takes precedence over `.claude/agents/` at the same level. User-level agents have lower priority than project-level agents. Plugin agents have the lowest priority.
### Agent communication
Use `list_agents` and `write_agent` inside custom agents to inspect nearby agents and coordinate work in a multi-agent session.
#### Relation labels in `list_agents`
Relation labels identify how visible agents relate to the current agent. Labels appear when a subagent runs inside a parent session with shared sibling communication enabled.
| Label | Meaning | Use it to |
|-------|---------|-----------|
| `"self"` | The current agent | Confirm which entry represents the active agent |
| `"sibling"` | An agent launched by the same parent | Coordinate with peer agents through `write_agent` |
| `"child"` | An agent launched by the current agent | Track follow-up work delegated from the current agent |
#### Scoped listing
Use `scope` on `list_agents` to narrow the list before choosing targets.
| `scope` value | Returns | Use it to |
|---------------|---------|-----------|
| omitted | Nearby agents in the current context | See the default working set for the current workflow |
| `"siblings"` | Only sibling agents | Find peer agents launched by the same parent |
| `"children"` | Only child agents of the current agent | Review work delegated from the current agent |
| `"all"` | All visible agents | Inspect the full session tree without using it for coordination |
In single-agent sessions, the default view centers on child agents. In multi-agent sessions, the default view shows the immediate local context instead of the entire tree.
```text
list_agents(scope="siblings")
list_agents(scope="children")
list_agents(scope="all")
```
#### Scoped messaging
Use `scope` on `write_agent` to broadcast one message to multiple related agents.
Use scoped messaging only from a subagent running inside a parent session with shared sibling communication enabled. In top-level sessions, target agents with explicit `agent_id` values instead.
| `scope` value | Sends to | Use it to |
|---------------|----------|-----------|
| `"siblings"` | All visible sibling agents | Coordinate peer work in a shared session |
| `"children"` | All child agents of the current agent | Send the same follow-up to delegated work |
If a scope matches too many agents, `write_agent` returns an error and asks for explicit `agent_id` values from `list_agents` instead.
```text
write_agent(scope="children", message="Re-check your findings against the updated schema.")
write_agent(scope="siblings", message="Post status when your current check completes.")
write_agent(agent_id="explore-auth", message="Focus on token refresh flow and report only confirmed issues.")
```
### Subagent limits
The CLI enforces depth and concurrency limits to prevent runaway agent spawning.
| Limit | Default | Max |
|-------|---------|-----|
| Max depth | `6` | `256` |
| Max concurrent | plan-based | `32` |
**Depth** counts how many agents are nested within one another. When the depth limit is reached, the innermost agent cannot spawn further subagents. **Concurrency** counts how many subagents are running simultaneously across the entire session tree. When the limit is reached, new subagent requests are rejected until an active agent completes.
The default concurrency limit depends on your {% data variables.product.prodname_copilot_short %} plan:
| Plan | Max concurrent |
|------|---------------|
| Free / Education | `2` |
| Pro / Pro+ | `4` |
| Max | `8` |
| Business | `16` |
| Enterprise | `32` |
| Usage-based billing | `32` |
Usage-based billing users can override these limits with the `subagents.maxConcurrency` and `subagents.maxDepth` settings:
```json
{
"subagents": {
"maxConcurrency": 16,
"maxDepth": 10
}
}
```
Values outside the valid range are clamped: `maxConcurrency` is capped at `32`, and `maxDepth` is capped at `256`. These settings are ignored for plans that don't use usage-based billing. See [Configuration file settings](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings).
## Sidekick agents
Sidekick agents run automatically in the background and publish context into the session inbox. They respond to session events rather than being explicitly invoked.
Add a `sidekick:` block to any agent definition to make it a sidekick agent:
```yaml
---
name: Context Gatherer
description: Gathers relevant context when the working directory changes
sidekick:
triggers:
- session.context_changed
- event: user.message
limit: 1
behavior: persistent
maxSendsPerTurn: 2
---
Gather useful context about the current repository and working directory.
Summarize recent changes and any relevant project structure.
```
### Sidekick triggers
Each entry in `triggers` is either a bare event-name string, which fires an unlimited number of times, or an object with `event` and an optional `limit`.
| Event | Description |
|-------|-------------|
| `user.message` | Fires on every user message. |
| `session.context_changed` | Fires when the working directory, repository, or branch changes (for example, after `cd` or switching Git branches). |
| Trigger field | Type | Default | Description |
|----------------|------|---------|-------------|
| `event` | `string` | Required | Session event type that launches this agent. |
| `limit` | `number` | Unlimited | Maximum number of times this trigger may fire per session. Must be a positive integer when set. |
### Sidekick configuration fields
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `triggers` | `string[]` or object[] | Required | Session event types that launch this agent. At least one trigger is required. |
| `behavior` | `string` | `"restart"` | `"restart"`: cancel any prior run and start fresh on each trigger. `"persistent"`: keep the same long-lived run alive and deliver new messages into the existing loop instead of relaunching. |
| `maxSendsPerTurn` | `number` | `1` | Maximum inbox sends allowed per trigger. In `"persistent"` mode, each delivered user message resets this budget. |
The `"restart"` behavior is suited to stateless context-gathering agents. The `"persistent"` behavior is suited to agents that accumulate state across turns.
## Permission approval responses
When the CLI prompts for permission to execute an operation, you can respond with the following keys.
| Key | Effect |
|-----|--------|
| `y` | Allow this specific request once. |
| `n` | Deny this specific request once. |
| `!` | Allow all similar requests for the rest of the session. |
| `#` | Deny all similar requests for the rest of the session. |
| `?` | Show detailed information about the request. |
When the full dialog is shown, you can also choose from these options:
| Option | Scope | Persistence |
|--------|-------|-------------|
| Once | Single use | None |
| This location | Until manually cleared | Saved to disk per location |
| Always | Permanent | Config file |
The **This location** option appears when the CLI can determine a location key (Git root or current directory). It persists the approval to disk so the same permission is automatically granted the next time you work in that directory without prompting again.
Use `/permissions reset` to clear in-memory approvals for the current session.
## Security
### Plan mode
`/plan` starts a read-only analysis session that prevents write operations and shell command execution while allowing full codebase exploration. Mutating tool calls—editor writes, `apply_patch` to non-plan files, mutating shell commands, and pull request creation—are hard-blocked at the tool layer, not just discouraged by the system prompt. Subagents spawned from a plan-mode session inherit the same restriction. Reads and writes to the plan file itself are still allowed.
### Command safety analysis
Shell commands are analyzed before execution to identify potentially dangerous patterns:
* File deletion (`rm -rf`)
* System modifications (`sudo`, `chmod 777`)
* Network exfiltration (`curl` with sensitive paths)
* Credential access (reading `.env`, SSH keys)
* Inline environment variable assignments that override dangerous variables (for example, `PATH=...`, `LD_PRELOAD=...`)
High-risk commands display additional warnings and require explicit confirmation.
#### Environment variable denylist
The CLI blocks inline assignment of environment variables that can be exploited to execute arbitrary code even in otherwise read-only commands. Blocked categories include:
| Category | Examples |
|----------|----------|
| Dynamic-linker injection | `LD_*`, `DYLD_*` (all prefixes) |
| Git indexed config overrides | `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_*`, `GIT_CONFIG_VALUE_*` (all `GIT_CONFIG_` prefixes) |
| Git external program hooks | `GIT_EXTERNAL_DIFF`, `GIT_PROXY_COMMAND` |
| Git config file overrides | `GIT_CONFIG`, `GIT_CONFIG_GLOBAL`, `GIT_CONFIG_SYSTEM` |
| Shell PATH and startup files | `PATH`, `BASH_ENV`, `ENV` |
| Existing blocked vars | `PAGER`, `GIT_PAGER`, `GIT_EDITOR`, `VISUAL`, `EDITOR`, `GIT_SSH`, `GIT_SSH_COMMAND`, `GIT_ASKPASS`, `BROWSER`, `GH_BROWSER` |
### `web_fetch` SSRF protection
The `web_fetch` tool enforces server-side request forgery (SSRF) protections before making any HTTP request:
* **Protocol allowlist**: Only `http://` and `https://` URLs are permitted. `file://` and other schemes are rejected.
* **IP blocklist**: Requests to loopback addresses (`127.x.x.x`, `::1`), RFC-1918 private ranges (`10.x`, `172.16–31.x`, `192.168.x`), and cloud metadata endpoints (for example, `169.254.169.254`) are blocked by IP-literal check and DNS pre-resolution.
* **No automatic redirects**: `3xx` redirects are not followed automatically. The redirect target URL is re-validated against the same IP blocklist before following.
To allow `web_fetch` to reach `localhost` during development—for example, for a local docs server—set the following environment variable:
```bash
export COPILOT_WEB_FETCH_ALLOW_LOCALHOST=1
```
## OpenTelemetry monitoring
{% data variables.copilot.copilot_cli_short %} can export traces and metrics via [OpenTelemetry](https://opentelemetry.io/) (OTel), giving you visibility into agent interactions, LLM calls, tool executions, and token usage. All signal names and attributes follow the [OTel GenAI Semantic Conventions](https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai/).
OTel is off by default with zero overhead. It activates when any of the following conditions are met:
* `COPILOT_OTEL_ENABLED=true`
* `OTEL_EXPORTER_OTLP_ENDPOINT` is set
* `COPILOT_OTEL_FILE_EXPORTER_PATH` is set
OTel configuration can also be set in {% data variables.product.prodname_vscode_shortname %}, or in an enterprise-wide `{% data variables.copilot.managed_setting_file %}` file. See [Enable OTel monitoring](https://code.visualstudio.com/docs/agents/guides/monitoring-agents#_enable-otel-monitoring) in the {% data variables.product.prodname_vscode_shortname %} documentation and [AUTOTITLE](/copilot/reference/enterprise-managed-settings-reference).
### OTel environment variables
| Variable | Default | Description |
|----------|---------|-------------|
| `COPILOT_OTEL_ENABLED` | `false` | Explicitly enable OTel. Not required if `OTEL_EXPORTER_OTLP_ENDPOINT` is set. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OTLP endpoint URL. Setting this automatically enables OTel. |
| `COPILOT_OTEL_EXPORTER_TYPE` | `otlp-http` | Exporter type: `otlp-http` or `file`. Auto-selects `file` when `COPILOT_OTEL_FILE_EXPORTER_PATH` is set. |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/json` | OTLP HTTP wire protocol: `http/json` or `http/protobuf`. Only applies to the `otlp-http` exporter. |
| `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | — | Override `OTEL_EXPORTER_OTLP_PROTOCOL` for traces only. |
| `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | — | Override `OTEL_EXPORTER_OTLP_PROTOCOL` for metrics only. |
| `OTEL_SERVICE_NAME` | `github-copilot` | Service name in resource attributes. |
| `OTEL_RESOURCE_ATTRIBUTES` | — | Extra resource attributes as comma-separated `key=value` pairs. Use percent-encoding for special characters. |
| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `false` | Capture full prompt and response content. See [Content capture](#content-capture). |
| `OTEL_LOG_LEVEL` | — | OTel diagnostic log level: `NONE`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `VERBOSE`, `ALL`. |
| `COPILOT_OTEL_FILE_EXPORTER_PATH` | — | Write all signals to this file as JSON-lines. Setting this automatically enables OTel. |
| `COPILOT_OTEL_SOURCE_NAME` | `github.copilot` | Instrumentation scope name for tracer and meter. |
| `OTEL_EXPORTER_OTLP_HEADERS` | — | Auth headers for the OTLP exporter (for example, `Authorization=Bearer token`). |
### Traces
The runtime emits a hierarchical span tree for each agent interaction. Each tree contains an `invoke_agent` root span, with `chat` and `execute_tool` child spans.
#### `invoke_agent` span attributes
Wraps the entire agent invocation: all LLM calls and tool executions for one user message.
* **Top-level sessions** use span kind `CLIENT` (remote service invocation) with `server.address` and `server.port`.
* **Subagent invocations** (for example, explore, task) use span kind `INTERNAL` (in-process) without server attributes.
| Attribute | Description | Span kind |
|-----------|-------------|-----------|
| `gen_ai.operation.name` | `invoke_agent` | Both |
| `gen_ai.provider.name` | Provider (for example, `github`, `anthropic`) | Both |
| `gen_ai.agent.id` | Stable agent-definition identifier when known; top-level default uses `github.copilot.default` | Both |
| `gen_ai.agent.name` | Agent name (when available) | Both |
| `gen_ai.agent.description` | Agent description (when available) | Both |
| `gen_ai.agent.version` | Agent definition version when known; otherwise runtime version | Both |
| `gen_ai.conversation.id` | Session identifier | Both |
| `enduser.pseudo.id` | Pseudonymous Copilot user identifier from `analytics_tracking_id` when available | Both |
| `gen_ai.request.model` | Requested model | Both |
| `gen_ai.response.finish_reasons` | `["stop"]` or `["error"]` | Both |
| `gen_ai.usage.input_tokens` | Total input tokens (all turns) | Both |
| `gen_ai.usage.output_tokens` | Total output tokens (all turns) | Both |
| `gen_ai.usage.cache_read.input_tokens` | Cached input tokens read | Both |
| `gen_ai.usage.cache_creation.input_tokens` | Cached input tokens created | Both |
| `github.copilot.turn_count` | Number of LLM round-trips | Both |
| `github.copilot.cost` | Monetary cost | Both |
| `github.copilot.aiu` | AI units consumed | Both |
| `server.address` | Server hostname | `CLIENT` only |
| `server.port` | Server port | `CLIENT` only |
| `error.type` | Error class name (on error) | Both |
| `gen_ai.input.messages` | Full input messages as JSON (content capture only) | Both |
| `gen_ai.output.messages` | Full output messages as JSON (content capture only) | Both |
| `gen_ai.system_instructions` | System prompt content as JSON (content capture only) | Both |
| `gen_ai.tool.definitions` | Tool schemas as JSON (content capture only) | Both |
#### `chat` span attributes
One span per LLM request. Span kind: `CLIENT`.
| Attribute | Description |
|-----------|-------------|
| `gen_ai.operation.name` | `chat` |
| `gen_ai.provider.name` | Provider name |
| `gen_ai.request.model` | Requested model |
| `gen_ai.request.stream` | Whether streaming mode was used (streaming only) |
| `gen_ai.conversation.id` | Session identifier |
| `gen_ai.response.finish_reasons` | Stop reasons |
| `gen_ai.response.id` | Response ID |
| `gen_ai.response.model` | Resolved model |
| `gen_ai.response.time_to_first_chunk` | Time to first streaming chunk, in seconds (streaming only) |
| `gen_ai.usage.cache_creation.input_tokens` | Cached tokens created |
| `gen_ai.usage.cache_read.input_tokens` | Cached tokens read |
| `gen_ai.usage.input_tokens` | Input tokens this turn |
| `gen_ai.usage.output_tokens` | Output tokens this turn |
| `github.copilot.cost` | Turn cost |
| `github.copilot.aiu` | AI units consumed this turn |
| `github.copilot.server_duration` | Server-side duration |
| `github.copilot.initiator` | Request initiator |
| `github.copilot.turn_id` | Turn identifier |
| `github.copilot.interaction_id` | Interaction identifier |
| `server.address` | Server hostname |
| `server.port` | Server port |
| `error.type` | Error class name (on error) |
| `gen_ai.input.messages` | Full prompt messages as JSON (content capture only) |
| `gen_ai.output.messages` | Full response messages as JSON (content capture only) |
| `gen_ai.system_instructions` | System prompt content as JSON (content capture only) |
#### `execute_tool` span attributes
One span per tool call. Span kind: `INTERNAL`.
| Attribute | Description |
|-----------|-------------|
| `gen_ai.operation.name` | `execute_tool` |
| `gen_ai.provider.name` | Provider name (when available) |
| `gen_ai.tool.name` | Tool name (for example, `readFile`) |
| `gen_ai.tool.type` | `function` |
| `gen_ai.tool.call.id` | Tool call identifier |
| `gen_ai.tool.description` | Tool description |
| `error.type` | Error class name (on error) |
| `gen_ai.tool.call.arguments` | Tool input arguments as JSON (content capture only) |
| `gen_ai.tool.call.result` | Tool output as JSON (content capture only) |
### Metrics
#### GenAI convention metrics
| Metric | Type | Unit | Description |
|--------|------|------|-------------|
| `gen_ai.client.operation.duration` | Histogram | s | LLM API call and agent invocation duration |
| `gen_ai.client.token.usage` | Histogram | tokens | Token counts by type (`input`/`output`) |
| `gen_ai.client.operation.time_to_first_chunk` | Histogram | s | Time to receive first streaming chunk |
| `gen_ai.client.operation.time_per_output_chunk` | Histogram | s | Inter-chunk latency after first chunk |
#### Vendor-specific metrics
| Metric | Type | Unit | Description |
|--------|------|------|-------------|
| `github.copilot.tool.call.count` | Counter | calls | Tool invocations by `gen_ai.tool.name` and `success` |
| `github.copilot.tool.call.duration` | Histogram | s | Tool execution latency by `gen_ai.tool.name` |
| `github.copilot.agent.turn.count` | Histogram | turns | LLM round-trips per agent invocation |
| `github.copilot.mcp.server.connection.count` | Counter | attempts | Completed MCP server connection attempts by transport and outcome |
| `github.copilot.code.lines_added` | Counter | lines | Lines added by file-editing tools, recorded in real time |
| `github.copilot.code.lines_removed` | Counter | lines | Lines removed by file-editing tools, recorded in real time |
### Span events
Lifecycle events recorded on the active `chat` or `invoke_agent` span.
| Event | Description | Key attributes |
|-------|-------------|----------------|
| `github.copilot.hook.start` | A hook began executing | `github.copilot.hook.type`, `github.copilot.hook.invocation_id` |
| `github.copilot.hook.end` | A hook completed successfully | `github.copilot.hook.type`, `github.copilot.hook.invocation_id` |
| `github.copilot.hook.error` | A hook failed | `github.copilot.hook.type`, `github.copilot.hook.invocation_id`, `github.copilot.hook.error_message` |
| `github.copilot.session.truncation` | Conversation history was truncated | `github.copilot.token_limit`, `github.copilot.pre_tokens`, `github.copilot.post_tokens`, `github.copilot.pre_messages`, `github.copilot.post_messages`, `github.copilot.tokens_removed`, `github.copilot.messages_removed`, `github.copilot.performed_by` |
| `github.copilot.session.compaction_start` | History compaction began | None |
| `github.copilot.session.compaction_complete` | History compaction completed | `github.copilot.success`, `github.copilot.pre_tokens`, `github.copilot.post_tokens`, `github.copilot.tokens_removed`, `github.copilot.messages_removed`, `github.copilot.message` (content capture only) |
| `github.copilot.skill.invoked` | A skill was invoked | `github.copilot.skill.name`, `github.copilot.skill.path`, `github.copilot.skill.plugin_name`, `github.copilot.skill.plugin_version` |
| `github.copilot.session.shutdown` | Session is shutting down | `github.copilot.shutdown_type`, `github.copilot.total_premium_requests`, `github.copilot.lines_added`, `github.copilot.lines_removed`, `github.copilot.files_modified_count` |
| `github.copilot.session.abort` | User cancelled the current operation | `github.copilot.abort_reason` |
| `exception` | Session error | `github.copilot.error_type`, `github.copilot.error_status_code`, `github.copilot.error_provider_call_id` |
### Resource attributes
All signals carry these resource attributes.
| Attribute | Value |
|-----------|-------|
| `service.name` | `github-copilot` (configurable via `OTEL_SERVICE_NAME`) |
| `service.version` | Runtime version |
### Content capture
By default, no prompt content, responses, or tool arguments are captured—only metadata like model names, token counts, and durations. To capture full content, set `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true`.
> [!WARNING]
> Content capture may include sensitive information such as code, file contents, and user prompts. Only enable this in trusted environments.
When content capture is enabled, the following attributes are populated.
| Attribute | Content |
|-----------|---------|
| `gen_ai.input.messages` | Full prompt messages (JSON) |
| `gen_ai.output.messages` | Full response messages (JSON) |
| `gen_ai.system_instructions` | System prompt content (JSON) |
| `gen_ai.tool.definitions` | Tool schemas (JSON) |
| `gen_ai.tool.call.arguments` | Tool input arguments |
| `gen_ai.tool.call.result` | Tool output |
## Further reading
* [AUTOTITLE](/copilot/how-tos/copilot-cli)
* [AUTOTITLE](/copilot/reference/hooks-reference)
* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference)
* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-programmatic-reference)
* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference)