Copilot CLI Guide

Copilot CLI Guide

Quick reference for GitHub Copilot CLI — the terminal-native AI coding agent.

When to use this skill

• User asks about Copilot CLI features or capabilities
• User needs help with slash commands or keyboard shortcuts
• User wants to understand modes (interactive, plan, autopilot)
• User asks about context management or session handling

Getting Started

# Install (macOS/Linux)
curl -fsSL https://gh.io/copilot-install | bash

# Install (Homebrew)
brew install copilot-cli

# Install (npm, cross-platform)
npm install -g @github/copilot

# Install (Windows)
winget install GitHub.Copilot

# Launch
copilot

Keyboard Shortcuts

Global

Timeline

Editing

Slash Commands

Agent & Customization

Models & Subagents

Code & Review

Permissions

Session

Help & Feedback

Other

Modes

Standard Mode (default)

Standard chat mode. Copilot asks for approval before modifying files or executing tools unless permissions allow them.

Plan Mode

Press Shift+Tab to enter plan mode. Copilot creates an implementation plan before writing any code. Great for complex tasks.

Autopilot Mode (experimental)

Copilot continues working on tasks until completion with less manual intervention. Enable with --mode autopilot, --autopilot, or by cycling modes with Shift+Tab.

Context Management

Include files

Use @ followed by a relative path to include file contents:

Explain @config/ci/ci-required-checks.yml
Fix the bug in @src/app.js

Manage context window

/context    # Visual overview of token usage
/usage      # Detailed session statistics
/compact    # Compress conversation history

Copilot CLI automatically compresses history when approaching 95% of the token limit.

Working with directories

/add-dir /path/to/directory    # Add trusted directory
/cwd /path/to/directory        # Change working directory
/list-dirs                     # Show allowed directories

Session Management

# Resume previous session
/resume

# Resume most recent session from terminal
copilot --continue

# Start with a specific agent
copilot --agent=my-agent --prompt "Do something"

Built-in Agents

Use built-in agents before creating a custom project agent when the task matches their purpose.

MCP Servers

Built-in MCP servers include GitHub, Playwright, fetch, and time. Additional MCP servers can be configured at repository, workspace, user, agent, or one-session scope.

/mcp show               # Show configured MCP servers
/mcp add                # Add a new MCP server interactively
copilot mcp list        # List servers from the shell
copilot mcp add NAME -- COMMAND ARGS...

Common config locations:

• .github/mcp.json for repository-level MCP config
• .mcp.json for workspace MCP config
• ~/.copilot/mcp-config.json for user-level MCP config
• --additional-mcp-config for a single session

Advanced MCP considerations:

• Use /mcp auth SERVER-NAME when a remote OAuth server needs re-authentication.
• Use filterMapping to control how MCP output is cleaned or formatted before it reaches the model.
• Use OIDC only when the server is designed to receive Copilot-issued identity tokens.
• Expect enterprise allowlists to block non-default servers until approved by policy.
• Migrate VS Code .vscode/mcp.json to .mcp.json by remapping servers to mcpServers.

LSP Configuration

For enhanced code intelligence, configure language servers:

• User-level: ~/.copilot/lsp-config.json
• Repository-level: .github/lsp.json

{
  "lspServers": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "fileExtensions": {
        ".ts": "typescript",
        ".tsx": "typescript"
      }
    }
  }
}

Custom Instructions Locations

Copilot CLI reads instructions from these locations (in order):

1. CLAUDE.md (git root & cwd)
2. GEMINI.md (git root & cwd)
3. AGENTS.md (git root & cwd)
4. .github/instructions/**/*.instructions.md (git root & cwd)
5. .github/copilot-instructions.md
6. $HOME/.copilot/copilot-instructions.md
7. COPILOT_CUSTOM_INSTRUCTIONS_DIRS (additional directories via env var)

Path-specific instruction files require applyTo frontmatter and can include comma-separated glob patterns.

Useful CLI Flags

copilot --banner          # Show animated banner
copilot --experimental    # Enable experimental features
copilot --mode plan       # Start in plan mode
copilot --mode autopilot  # Start in autopilot mode
copilot --plan            # Shorthand for --mode plan
copilot --autopilot       # Enable autopilot in prompt mode
copilot --continue        # Resume most recent session
copilot --resume SESSION  # Resume specific session
copilot --agent=NAME      # Use specific agent
copilot --prompt "..."    # Start with a prompt
copilot --interactive "..." # Start interactive mode and run a prompt
copilot --allow-all       # Enable all permissions
copilot --yolo            # Alias for --allow-all
copilot --available-tools=read,grep,edit # Restrict tools available to the model
copilot --allow-tool='shell(git:*)'      # Pre-approve matching tool calls
copilot --deny-tool='shell(git push)'    # Deny matching tool calls
copilot --add-dir=/path/to/project       # Allow access to another directory
copilot --config-dir=/path/to/config     # Use a different config directory

Programmatic Usage

Use prompt mode for scripts, CI helpers, or repeatable local automation. In non-interactive contexts, provide explicit tool and path permissions so the run does not stop for approval prompts.

copilot --prompt "Update the changelog" --allow-tool=read,grep,edit --add-dir="$PWD"
copilot --prompt "Review this branch" --output-format=json --silent
copilot --prompt "Run the test task" --share=./copilot-session.md

Token environment variables are checked in this order: COPILOT_GITHUB_TOKEN, GH_TOKEN, then GITHUB_TOKEN. Prefer fine-grained tokens with the minimum required permissions for automation.

Permission Patterns

Permission flags accept broad tool names or structured patterns. Deny rules take precedence over allow rules.

copilot --allow-tool='shell(git:*)' --deny-tool='shell(git push)'
copilot --allow-url='https://github.com' --deny-url='https://example.com/private'
copilot --allow-tool='MyMCP(create_issue)'
copilot --allow-tool='MyMCP'

Common pattern kinds include read, write, shell, url, memory, and MCP server names.

OpenTelemetry Monitoring

Copilot CLI can export traces and metrics for agent turns, LLM requests, tool calls, token usage, and errors. Monitoring is off by default and activates when an OpenTelemetry endpoint or file exporter is configured.

export COPILOT_OTEL_ENABLED=true
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com/v1/traces
export OTEL_SERVICE_NAME=github-copilot

Do not enable full content capture in shared or untrusted environments. It may record prompts, code, tool arguments, and tool results.

Reference Documentation

• About Copilot CLI
• Using Copilot CLI
• CLI Best Practices
• CLI Command Reference
• CLI Programmatic Reference
• CLI Plugin Reference
• CLI Configuration Directory
• Custom Instructions
• Custom Agents
• Agent Skills
• MCP Servers