copilot-cli

name: copilot-cli description: "Use the GitHub Copilot CLI for agentic coding, session management, custom agents, skills, plugins, SDK integration, and Ralph Wiggum loops. Use when: (1) running Copilot CLI sessions interactively or non-interactively, (2) managing custom agents and skills, (3) configuring MCP servers and plugins, (4) integrating with the Copilot SDK programmatically, (5) orchestrating multi-agent workflows, (6) setting up long-running autonomous coding loops (Ralph Wiggum pattern). NOT for: the old gh copilot extension (that's deprecated), simple file edits (just edit directly), or GitHub API operations (use gh CLI)."

GitHub Copilot CLI

The standalone copilot CLI — an agentic coding assistant that runs in your terminal. Supports sessions, custom agents, skills, plugins, MCP servers, and a TypeScript SDK for programmatic control.

Installation & Auth

# Install globally
npm install -g @github/copilot

# Authenticate (opens browser for device flow)
copilot login

# Check version
copilot --version

Auth tokens (precedence order): COPILOT_GITHUB_TOKEN > GH_TOKEN > GITHUB_TOKEN > stored credentials from copilot login

Core Usage Patterns

Interactive Mode (default)

# Start interactive session in current directory
copilot

# Start with a specific model
copilot --model claude-sonnet-4.6

# Start with a custom agent
copilot --agent code-reviewer

# Resume most recent session
copilot --continue

# Resume a specific session
copilot --resume <session-id>

# Resume with session picker
copilot --resume

Non-Interactive Mode (scripting)

# One-shot prompt — exits after completion
copilot -p "Fix the bug in main.js" --allow-all-tools

# Silent output (agent response only, no stats)
copilot -p "Explain this error" -s

# Share session to markdown after completion
copilot -p "Refactor auth module" --allow-all --share

# Share to GitHub gist
copilot -p "Review this code" --allow-all --share-gist

Auto-Execute Mode

# Start interactive and auto-execute a prompt
copilot -i "Fix the failing tests"

# Autopilot mode — agent continues without waiting for input
copilot --autopilot --allow-all
copilot --autopilot --max-autopilot-continues 10 --allow-all

Full Auto (YOLO)

# All permissions — no confirmations, no restrictions
copilot --yolo
# Equivalent to:
copilot --allow-all-tools --allow-all-paths --allow-all-urls

Available Models

Set via --model, /model command, COPILOT_MODEL env, or model in config.

# List available models (check --help for current choices)
copilot --help 2>&1 | grep -A1 'model <model>'

# Or in interactive mode
/model

Permissions System

Copilot CLI has granular permission controls. Run copilot help permissions for full details. By default, it prompts for confirmation on file writes, shell commands, and URL access.

Tool Permissions

# Allow specific tools without prompting
copilot --allow-tool 'shell(git:*)'           # All git commands
copilot --allow-tool 'write'                   # All file writes
copilot --allow-tool 'shell(npm:*)'            # All npm commands
copilot --allow-tool 'MyMCP(tool_name)'        # Specific MCP tool
copilot --allow-tool 'MyMCP'                   # All tools from an MCP server

# Deny specific tools (overrides allow)
copilot --deny-tool 'shell(git push)'          # Block git push
copilot --deny-tool 'shell(rm:*)'              # Block rm commands

# Control which tools the model can even see
copilot --available-tools shell write read      # Only these tools exist
copilot --excluded-tools shell                  # Everything except shell

# Allow all tools
copilot --allow-all-tools

Path Permissions

# Add directories to allowed list
copilot --add-dir ~/other-project
copilot --add-dir /tmp --add-dir ~/workspace

# Allow any path
copilot --allow-all-paths

# Block temp dir access
copilot --disallow-temp-dir

URL Permissions

# Allow specific domains (defaults to https://)
copilot --allow-url github.com
copilot --allow-url '*.github.com'

# Deny specific domains (overrides allow)
copilot --deny-url https://malicious-site.com

# Allow all URLs
copilot --allow-all-urls

Interactive Commands

When running in interactive mode, use /help to see all available commands. Key ones:

Agent & Customization

Session Management

Code & Review

Multi-Agent

Permissions (runtime)

Custom Agents, Skills, Plugins & MCP

For creating custom agents (.agent.md), managing skills, installing plugins, configuring MCP servers, and setting up custom instructions:

📄 authoring/GUIDE.md

Docker Sandboxes

Run Copilot in an isolated Docker sandbox — recommended for --yolo / Ralph Wiggum loops where the agent has unrestricted tool access.

Official docs: Docker Sandboxes for Copilot

Quick Start

# Create and run a sandbox for a project directory
docker sandbox run copilot ~/my-project

# Or from within the project directory
cd ~/my-project
docker sandbox run copilot

The workspace is mounted at /workspace inside the sandbox by default.

Authentication

The sandbox daemon doesn't inherit shell env vars. Set your token globally in your shell config:

# ~/.bashrc or ~/.zshrc
export GH_TOKEN=ghp_xxxxx
# or: export GITHUB_TOKEN=ghp_xxxxx

Then: source ~/.zshrc, restart Docker Desktop, and create the sandbox.

Trusted Folders

Configure ~/.copilot/config.json to skip safety prompts for sandbox workspaces:

{
  "trusted_folders": ["/workspace"]
}

Pass Options at Runtime

Use -- separator to pass CLI flags through to Copilot inside the sandbox:

# Run with --yolo (no confirmations)
docker sandbox run <sandbox-name> -- --yolo

# Run with a specific model
docker sandbox run <sandbox-name> -- --model claude-sonnet-4.6

Custom Templates

Base image: docker/sandbox-templates:copilot. See Custom templates to build your own.

Configuration

Config lives in ~/.copilot/config.json (override with XDG_CONFIG_HOME).

Key settings (discover all with cat ~/.copilot/config.json or copilot help config):

Environment Variables

Run copilot help environment for the full list. Key ones:

SDK Integration (TypeScript)

For programmatic control via the @github/copilot-sdk package (JSON-RPC, sessions, streaming events):

📄 sdk/GUIDE.md

Orchestration Patterns

Multi-Model Comparison

# Run same prompt across models, compare output
copilot --model gpt-5.3-codex -p "Implement X" -s --share ./codex-result.md
copilot --model claude-sonnet-4.6 -p "Implement X" -s --share ./claude-result.md

Fleet Mode (parallel subagents)

# In interactive mode
/fleet
# Copilot spawns multiple subagents working in parallel
/tasks  # Monitor them

Delegation to Copilot Coding Agent

# In interactive mode — push session to GitHub for background execution
/delegate complete the API integration tests

# Or prefix with &
& complete the API integration tests

Non-Interactive Batch

# Process multiple files
for f in src/*.ts; do
  copilot -p "Review $f for security issues" -s --allow-all >> reviews.md
done

Tips

• @ file paths — Reference files in prompts: Explain @src/auth.ts
• ! shell — Run shell commands directly: !git status
• Esc — Stop current operation while thinking
• Shift+Tab — Toggle plan mode (plan before coding)
• Steer while thinking — Send follow-up messages while agent is working
• /compact — When context gets long, summarize to free up space
• Config dir override — copilot --config-dir ./project-copilot-config for project-specific settings

Ralph Wiggum Loop (Long-Running Autonomous Coding)

For setting up autonomous coding loops that run indefinitely with fresh context each iteration, see the detailed guide:

📄 ralph-wiggum/GUIDE.md — full pattern, templates, loop script, and orchestration options

Based on @GeoffreyHuntley's Ralph Wiggum technique.