Copilot CLI Handbook

Last updated on April 3, 2026 at 4:30 PM EDT

Custom instructions, commands, permissions, agents, hooks, configuration, and MCP for GitHub Copilot CLI

Instruction Files

Copilot CLI can load repository, path-specific, agent, and local instructions from several official file locations. How-to: custom instructions

Common instruction locations

AGENTS.md in the repository root, the current working directory, or directories listed in COPILOT_CUSTOM_INSTRUCTIONS_DIRS. How-to: custom instructions
.github/copilot-instructions.md for repository-wide instructions. How-to: custom instructions
.github/instructions/**/*.instructions.md for path-specific instructions. How-to: custom instructions
$HOME/.copilot/copilot-instructions.md for local personal instructions. How-to: custom instructions
COPILOT_CUSTOM_INSTRUCTIONS_DIRS to add extra directories where Copilot CLI looks for AGENTS.md and .github/instructions/**/*.instructions.md. How-to: custom instructions

Useful commands and flags

/init — Initialize Copilot custom instructions and agentic features for the repository. Docs: slash commands
copilot init — Initialize Copilot custom instructions for the current repository. Docs: CLI commands
--no-custom-instructions — Start without loading AGENTS.md and related instruction files. Docs: CLI options

Interactive Commands

/clear — Abandon the current session and clear history while keeping configured MCP servers available in the new session. /new — Start a fresh conversation (keeps the old session backgrounded). Both accept an optional prompt to begin the new session. Docs: slash commands Release: v1.0.11 Release: v1.0.12 Blog: slash commands
/resume [SESSION-ID] — Resume a previous session. Docs: slash commands
/undo — Undo the last turn and revert any file changes it made. Release: v1.0.10
/rewind — Open a timeline picker to roll back to any point in conversation history (also double-Esc). Release: v1.0.13
/session [checkpoints [n]|files|plan|rename NAME] — Show session information and a workspace summary. Docs: slash commands
/rename NAME — Rename the current session. Docs: slash commands
/compact — Summarize history to reduce context usage. Docs: slash commands
/context — Show context window usage. Docs: slash commands
/cwd, /cd [PATH] — Show or change the working directory. Docs: slash commands Blog: slash commands
/add-dir PATH — Add a directory to the allowed file-access list. Docs: slash commands Blog: slash commands
/list-dirs — Show directories that already have file access. Docs: slash commands Blog: slash commands
/exit, /quit — Exit the CLI. Docs: slash commands

Planning, review, and collaboration

/diff — Review changes in the current directory. Docs: slash commands
/review [PROMPT] — Run the code review agent against your changes. Docs: slash commands
/plan [PROMPT] — Draft an implementation plan before editing. Docs: slash commands
/delegate [PROMPT] — Delegate work to a remote repository with an AI-generated pull request. Docs: slash commands How-to: CLI agents Blog: slash commands Blog: terminal workflows
/share [file|gist|html] [PATH] — Export the session to Markdown, a secret gist, or a self-contained interactive HTML file. Docs: slash commands Release: v1.0.15 Blog: slash commands
/changelog — Browse release notes from inside the CLI. Release: v1.0.5
/pr — Create or inspect pull requests, fix CI failures, address review feedback, and resolve merge conflicts. Release: v1.0.5

Agents, models, skills, and extensions

/agent — Choose from available agents. Docs: slash commands How-to: custom agents
/fleet [PROMPT] — Run parts of a task in parallel with subagents. Docs: slash commands How-to: /fleet
/tasks — Inspect background tasks and subagent work created in the current session. How-to: /fleet
/model, /models [MODEL] — View or change the active model. Docs: slash commands Blog: slash commands
/skills [list|info|add|remove|reload] [ARGS...] — Manage skills. Docs: slash commands
/plugin [marketplace|install|uninstall|update|list] [ARGS...] — Manage plugins and plugin marketplaces. Docs: slash commands
/extensions — View, enable, and disable CLI extensions. Release: v1.0.5

Tools, account, and setup

/allow-all, /yolo — Enable all permissions for tools, paths, and URLs. Supports on, off, and show subcommands to enable, disable, or check allow-all mode. Docs: slash commands Release: v1.0.12
/reset-allowed-tools — Clear previously granted tool approvals. Release: v1.0.3 Blog: slash commands
/mcp [show|add|edit|delete|disable|enable|auth] [SERVER-NAME] — Manage MCP servers; /mcp auth re-authenticates OAuth servers with account switching. Docs: slash commands Release: v1.0.15 Blog: slash commands
/lsp [show|test|reload|help] [SERVER-NAME] — Manage language server configuration. Docs: slash commands
/ide — Connect to an IDE workspace. Docs: slash commands
/terminal-setup — Configure multiline terminal input support. Docs: slash commands
/login, /logout — Sign in or out. Docs: slash commands
/user [show|list|switch] — Manage the current GitHub account. Docs: slash commands Blog: slash commands
/help, /feedback, /usage, /update, /theme, /experimental — Session help, reporting, usage, updates, UI, and feature toggles. Docs: slash commands Blog: slash commands
/version — Display the CLI version and check for updates from inside the session. Release: v1.0.5

Keyboard shortcuts

@ FILENAME — Include file contents in the prompt context. Docs: shortcuts
! COMMAND — Run a shell command directly. Docs: shortcuts
Ctrl + X then / — Run a slash command after you already started typing. Docs: shortcuts
Shift + Tab — Cycle between standard, plan, and autopilot mode. Docs: shortcuts
Ctrl + O, Ctrl + E, Ctrl + T — Expand recent timeline items, expand all, or toggle reasoning display. Docs: timeline shortcuts
Ctrl + G — Edit the prompt in an external editor. Docs: navigation shortcuts
Ctrl + Y — In plan mode, open the most recent research report when no plan exists yet. Release: v1.0.12
Ctrl + L, Ctrl + C, Ctrl + D — Clear the screen, cancel the current operation, or shut down. Docs: shortcuts

Command-Line Commands and Flags

Core commands

copilot — Launch the interactive interface. Docs: CLI commands
copilot help [topic] — Show help for config, commands, environment, logging, or permissions. Docs: CLI commands
copilot init — Initialize custom instructions for the current repository. Docs: CLI commands
copilot update — Download and install the latest version. Docs: CLI commands
copilot version — Show version information and check for updates. Docs: CLI commands
copilot login, copilot logout — Authenticate or remove credentials. Docs: CLI commands
copilot plugin — Manage plugins and plugin marketplaces outside the interactive session. Docs: CLI commands

Automation and session control

echo "PROMPT" | copilot — Pipe a prompt into Copilot CLI for scripting and automation. How-to: programmatic use
-p, --prompt=PROMPT — Run a prompt programmatically and exit after completion. Docs: CLI options Blog: terminal workflows Blog: idea to PR
-i, --interactive=PROMPT — Start an interactive session and run an initial prompt. Docs: CLI options
--continue — Resume the most recent session. Docs: CLI options
--resume=SESSION-ID — Resume a specific session. Docs: CLI options
--agent=AGENT — Pick a custom agent up front. Docs: CLI options
--autopilot — Let Copilot continue autonomously in prompt mode. Docs: CLI options
--max-autopilot-continues=COUNT — Cap autonomous follow-up turns. Docs: CLI options
--reasoning-effort=LEVEL, --effort=LEVEL — Set reasoning depth (low, medium, high, xhigh). Docs: CLI options
--output-format=text|json — Return plain text or JSONL output. Docs: CLI options
--share=PATH, --share-gist — Export a programmatic session after it finishes. Docs: CLI options
-s, --silent — Suppress usage statistics and print only the answer. Docs: CLI options How-to: programmatic use
--no-ask-user — Disable the ask-user tool for fully autonomous runs. Docs: CLI options How-to: programmatic use

Permissions and safety

--allow-all, --yolo — Approve all tools, paths, and URLs. Docs: CLI options
--allow-all-tools, --allow-all-paths, --allow-all-urls — Approve one permission category at a time. Docs: CLI options Blog: terminal workflows
--allow-tool=TOOL, --deny-tool=TOOL — Pre-allow or pre-deny tool patterns. Docs: CLI options
--allow-url=URL, --deny-url=URL — Control URL access. Docs: CLI options
--available-tools=TOOL, --excluded-tools=TOOL — Reduce the tool surface available to the model. Docs: CLI options
--disallow-temp-dir — Block automatic access to the system temp directory. Docs: CLI options

UI, output, and logging

--model=MODEL — Select the model. Docs: CLI options
--banner — Show the startup banner. Docs: CLI options
--plain-diff — Disable rich diff rendering. Docs: CLI options
--screen-reader — Enable screen-reader optimizations. Docs: CLI options
--stream=on|off — Turn streaming output on or off. Docs: CLI options
--secret-env-vars=VAR — Redact extra environment variables in output. Docs: CLI options
--config-dir=PATH — Override the config directory. Docs: CLI options
--bash-env, --no-bash-env — Control BASH_ENV sourcing. Docs: CLI options
--experimental, --no-experimental — Toggle experimental features. Docs: CLI options
--log-dir=DIRECTORY, --log-level=LEVEL — Control CLI logging. Docs: CLI options
--no-auto-update — Disable automatic updates. Docs: CLI options

MCP and tooling flags

--acp — Start an Agent Client Protocol server. Docs: CLI options
--additional-mcp-config=JSON|@path — Add MCP servers for the current session only. Docs: CLI options
--disable-builtin-mcps — Disable built-in MCP servers. Docs: CLI options
--disable-mcp-server=SERVER-NAME — Disable a specific MCP server. Docs: CLI options
--enable-all-github-mcp-tools — Enable the full GitHub MCP tool surface. Docs: CLI options
--add-github-mcp-toolset=TOOLSET, --add-github-mcp-tool=TOOL — Expand the GitHub MCP subset. Docs: CLI options

Permission Prompts and Tool Rules

When Copilot CLI asks for permission, these one-key responses are available. Docs: permission approvals

y — Allow once. Docs: permission approvals
n — Deny once. Docs: permission approvals
! — Allow similar requests for the rest of the session. Docs: permission approvals
# — Deny similar requests for the rest of the session. Docs: permission approvals
? — Show more detail about the request. Docs: permission approvals

Tool rules use the Kind(argument) pattern. Deny rules always override allow rules. Docs: tool rules

# Allow all git commands except git push
copilot --allow-tool='shell(git:*)' --deny-tool='shell(git push)'

# Allow one MCP tool
copilot --allow-tool='MyMCP(create_issue)'

# Allow all tools from one MCP server
copilot --allow-tool='MyMCP'

Examples adapted from the command reference. Docs: tool rules

Configuration Files

Settings cascade from broader scopes to narrower scopes. Command-line flags and environment variables always win. Docs: config settings

~/.copilot/config.json — User-wide defaults. Docs: config settings
.github/copilot/settings.json — Repository-wide shared settings. Docs: config settings
.github/copilot/settings.local.json — Local personal overrides that should not be committed. Docs: config settings
.claude/settings.json — Additional repository config source (loaded alongside .github/copilot/settings.json). Release: v1.0.12
.claude/settings.local.json — Additional local config source (loaded alongside .github/copilot/settings.local.json). Release: v1.0.12

Common user settings

model — Default model selection. Docs: user settings
theme — auto, dark, or light. Docs: user settings
reasoning_effort — low, medium, high, or xhigh. Docs: user settings
experimental — Enable experimental features by default. Docs: user settings
trusted_folders — Pre-granted file access. Docs: user settings
allowed_urls, denied_urls — URL allowlists and blocklists. Docs: user settings
screen_reader — Screen-reader mode. Docs: user settings
stream — Streaming responses. Docs: user settings
auto_update — Automatic updates. Docs: user settings
bash_env — BASH_ENV support. Docs: user settings

Repository-level settings

Repository settings support shared plugin behavior and startup messaging. Docs: repo settings

enabledPlugins — Declarative plugin auto-install for the repository. Docs: repo settings
extraKnownMarketplaces — Additional plugin marketplaces available in the repository. Docs: repo settings
companyAnnouncements — Shared startup messages for repository users. Docs: repo settings

Hooks

Hook configuration files live in .github/hooks/*.json in the current working directory. Docs: hooks reference How-to: hooks

What hooks can do

Run shell commands before or after tool use. Docs: hooks reference
Auto-submit a prompt or slash command when a session starts. Docs: prompt hooks
Allow, deny, ask for confirmation, or modify tool calls before they execute. Docs: pre-tool hooks
Block an agent or subagent from finishing and force another turn. Docs: agent-stop hooks

Main hook events

sessionStart, sessionEnd Docs: hook events
userPromptSubmitted Docs: hook events
preToolUse, postToolUse, postToolUseFailure Docs: hook events Release: v1.0.15
agentStop, subagentStop Docs: hook events
errorOccurred Docs: hook events
PermissionRequest — Allow scripts to programmatically approve or deny tool permission requests. Release: v1.0.16

Hook formats

Command hooks support bash, powershell, cwd, env, and timeoutSec. Docs: command hooks
Prompt hooks support a prompt string and can submit either plain text or a slash command. Docs: prompt hooks
preToolUse can return allow, deny, or ask, and can also replace tool arguments with modifiedArgs. Docs: pre-tool hooks
agentStop and subagentStop can return allow or block. Docs: agent-stop hooks

Useful recent hook updates

preCompact hooks can run before context compaction starts. Release: v1.0.5
Hooks can ask for confirmation before a tool runs. Docs: pre-tool hooks
Hook configuration files can omit the version field. Release: v1.0.5
Plugin hooks receive CLAUDE_PROJECT_DIR and CLAUDE_PLUGIN_DATA environment variables, and support {{project_dir}} and {{plugin_data_dir}} template variables in hook configurations. Release: v1.0.12

MCP Servers

Copilot CLI can load MCP servers from several places. Docs: MCP config

Configuration sources

~/.copilot/mcp-config.json Docs: MCP config
.github/mcp.json Docs: MCP trust
.mcp.json Docs: MCP trust
.vscode/mcp.json Docs: MCP trust
.devcontainer/devcontainer.json Docs: MCP trust

Built-in MCP servers

github-mcp-server — GitHub API actions such as issues, pull requests, commits, code search, and GitHub Actions. Docs: built-in MCP
playwright — Browser automation. Docs: built-in MCP
fetch — HTTP requests. Docs: built-in MCP
time — Time utilities. Docs: built-in MCP

Transport types

local / stdio — Launch a local process with command and args. Docs: MCP transport
http — Connect to a remote streamable HTTP server via url. Docs: MCP transport
sse — Connect to a remote Server-Sent Events server via url. Docs: MCP transport

Common fields

Local servers: command, args, tools, env, cwd, timeout, type. Docs: MCP local config
Remote servers: type, url, tools, headers, oauthClientId, oauthPublicClient, timeout. Docs: MCP remote config
filterMapping controls output filtering: hidden_characters (default), markdown, or none. Docs: MCP filter

Trust model

Built-in servers are high trust. Docs: MCP trust
Repository, workspace, and dev-container configs are medium trust. Docs: MCP trust
User config trust is your responsibility. Docs: MCP trust
Remote servers are low trust and should always be reviewed. Docs: MCP trust

All MCP tool calls still require explicit permission, including read-only calls against external services. Docs: MCP trust

Skills and Custom Agents

Skills

Skills are Markdown files that extend what Copilot CLI can do. Each skill lives in its own directory with a SKILL.md file. Docs: skills

Built-in skills are now included with the CLI, starting with guides for common tasks. Release: v1.0.17

Common skill locations:

.github/skills/ Docs: skill locations
.agents/skills/ Docs: skill locations
.claude/skills/ Docs: skill locations
Parent .github/skills/ directories in monorepos Docs: skill locations
~/.copilot/skills/ Docs: skill locations
~/.agents/skills/ — Personal skill directory, aligned with VS Code Copilot extension default. Release: v1.0.11
~/.claude/skills/ Docs: skill locations
Extra directories from COPILOT_SKILLS_DIRS Docs: skill locations

Useful frontmatter fields:

name Docs: skill frontmatter
description Docs: skill frontmatter
allowed-tools Docs: skill frontmatter
user-invocable Docs: skill frontmatter
disable-model-invocation Docs: skill frontmatter

Custom agents

Custom agents are specialized AI agents defined in Markdown files. You can browse them with /agent or select one up front with --agent=AGENT. Docs: custom agents Docs: slash commands Docs: CLI options

Built-in agents currently include:

Custom agent locations:

.github/agents/ or .claude/agents/ Docs: agent locations
~/.copilot/agents/ or ~/.claude/agents/ Docs: agent locations
Plugin-provided agents Docs: agent locations