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).
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.
# 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
# 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
# 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
# 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
# All permissions — no confirmations, no restrictions
copilot --yolo
# Equivalent to:
copilot --allow-all-tools --allow-all-paths --allow-all-urls
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
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.
# 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
# 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
# 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
When running in interactive mode, use /help to see all available commands. Key ones:
| Command | Description |
|---|---|
/agent | Browse and select custom agents |
/skills | Manage skills (list, enable/disable, add, reload, info, remove) |
/mcp | Manage MCP server configuration |
/plugin | Manage plugins and marketplaces |
/init | Initialize Copilot instructions for the repo |
/instructions | View and toggle custom instruction files |
| Command | Description |
|---|---|
/resume [id] | Switch to a different session |
/rename | Rename current session |
/context | Show context window token usage |
/usage | Display session usage metrics |
/session | Show session info and workspace summary |
/compact | Summarize history to reduce context usage |
/share | Share session to file or gist |
/clear | Clear conversation history |
| Command | Description |
|---|---|
/diff | Review changes in current directory |
/review | Run code review agent |
/plan | Create an implementation plan before coding |
/ide | Connect to an IDE workspace |
/lsp | Manage language server configuration |
| Command | Description |
|---|---|
/model | Select AI model |
/fleet | Enable fleet mode for parallel subagent execution |
/tasks | View and manage background tasks (subagents + shell sessions) |
| Command | Description |
|---|---|
/allow-all | Enable all permissions |
/add-dir | Add directory to allowed list |
/list-dirs | Show all allowed directories |
/cwd | Change or show working directory |
/reset-allowed-tools | Reset allowed tools list |
For creating custom agents (.agent.md), managing skills, installing plugins, configuring MCP servers, and setting up custom instructions:
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
# 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.
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.
Configure ~/.copilot/config.json to skip safety prompts for sandbox workspaces:
{
"trusted_folders": ["/workspace"]
}
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
Base image: docker/sandbox-templates:copilot. See Custom templates to build your own.
Config lives in ~/.copilot/config.json (override with XDG_CONFIG_HOME).
Key settings (discover all with cat ~/.copilot/config.json or copilot help config):
| Setting | Default | Description |
|---|---|---|
model | — | Default AI model |
auto_update | true | Auto-download updates |
banner | "once" | Banner display frequency |
beep | true | Beep on attention needed |
include_coauthor | true | Add Co-authored-by to commits |
trusted_folders | [] | Pre-approved directories |
allowed_urls | [] | Pre-approved URLs |
denied_urls | [] | Blocked URLs |
streamer_mode | false | Hide model names and quota |
parallel_tool_execution | true | Run tools in parallel |
alt_screen | false | Use alternate screen buffer |
experimental | false | Enable experimental features |
Run copilot help environment for the full list. Key ones:
| Variable | Description |
|---|---|
COPILOT_MODEL | Override default model |
COPILOT_ALLOW_ALL | Set "true" for full auto mode |
COPILOT_AUTO_UPDATE | Set "false" to disable auto-update |
COPILOT_CUSTOM_INSTRUCTIONS_DIRS | Comma-separated extra instruction directories |
COPILOT_EDITOR / VISUAL / EDITOR | Editor for interactive editing (e.g., plan) |
XDG_CONFIG_HOME | Override config directory (default: ~/.copilot) |
XDG_STATE_HOME | Override state directory (default: ~/.copilot) |
USE_BUILTIN_RIPGREP | Set "false" to use system ripgrep |
PLAIN_DIFF | Set "true" to disable rich diffs |
For programmatic control via the @github/copilot-sdk package (JSON-RPC, sessions, streaming events):
# 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
# In interactive mode
/fleet
# Copilot spawns multiple subagents working in parallel
/tasks # Monitor them
# In interactive mode — push session to GitHub for background execution
/delegate complete the API integration tests
# Or prefix with &
& complete the API integration tests
# Process multiple files
for f in src/*.ts; do
copilot -p "Review $f for security issues" -s --allow-all >> reviews.md
done
@ file paths — Reference files in prompts: Explain @src/auth.ts! shell — Run shell commands directly: !git statusEsc — Stop current operation while thinkingShift+Tab — Toggle plan mode (plan before coding)/compact — When context gets long, summarize to free up spacecopilot --config-dir ./project-copilot-config for project-specific settingsFor 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