GitHub Copilot CLI

CLI

GitHub

GitHub Copilot's terminal coding agent — configured through the ~/.copilot directory (settings.json, mcp-config.json, skills/, hooks/) plus repository-level files like AGENTS.md, .github/copilot/settings.json, and .mcp.json.

Website Docs

MCP

Supported

MCP servers are configured under the mcpServers key in ~/.copilot/mcp-config.json (user level) or in workspace .mcp.json / .github/mcp.json files, or managed with /mcp and copilot mcp commands. Supports stdio, Streamable HTTP, and legacy SSE with OAuth (including headless client_credentials).

Verified 2026-07-12Docs

Transportsstdiohttpsse

Authoauthheadersenv-secretsoidc

Config files

Path	Scope	Format	Key
`~/.copilot/mcp-config.json` Or $COPILOT_HOME/mcp-config.json when COPILOT_HOME is set.	Global	json	mcpServers
`.mcp.json` Workspace servers; takes precedence over user-level definitions on name conflicts.	Project	json	mcpServers
`.github/mcp.json` Repository-level alternative to .mcp.json.	Project	json	mcpServers

Fields

Field	Type	Description
`type`	"local" \| "stdio" \| "http" \| "sse"	Transport. local and stdio are equivalent; defaults to local for command servers.
`command`	string	Command to start a local server.
`args`	string[]	Arguments passed to the command.
`tools`*	string[]	Tools to enable: ["*"] for all, or a list of tool names.
`env`	record<string, string>	Environment variables for local servers. Supports $VAR, ${VAR}, and ${VAR:-default} expansion.
`cwd`	string	Working directory for a local server.
`url`	string	Server URL for remote (http/sse) servers.
`headers`	record<string, string>	HTTP headers for remote servers; supports variable expansion.
`timeout`	number	Tool call timeout in milliseconds.
`oauthClientId`	string	Static OAuth client ID (skips dynamic client registration).
`oauthGrantType`	"authorization_code" \| "client_credentials"	OAuth grant type. client_credentials enables fully headless auth (no browser) with oauthPublicClient: false and a keychain-stored client secret.
`oidc`	boolean	Inject GitHub OIDC tokens into the server's env (local) or as a Bearer Authorization header (remote).
`deferTools`	"auto" \| "never"	Set to never to keep the server's tools always visible when tool search (deferred tool loading) is active.

Capabilities

ToolsSupported

SamplingSupported

ElicitationSupported

Examples

Local and remote servers

{
  "mcpServers": {
    "playwright": {
      "type": "local",
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {},
      "tools": ["*"]
    },
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": { "CONTEXT7_API_KEY": "YOUR-API-KEY" },
      "tools": ["*"]
    }
  }
}

Add servers from the terminal

copilot mcp add context7 -- npx -y @upstash/context7-mcp
copilot mcp add --transport http notion https://mcp.notion.com/mcp

•Loading priority: --additional-mcp-config flag > plugin-provided servers > workspace .mcp.json / .github/mcp.json (loaded from the working directory up to the Git root; requires folder trust) > ~/.copilot/mcp-config.json.
•Built-in servers: github-mcp-server, playwright, fetch, time, and (opt-in) computer-use. Disable with --disable-builtin-mcps or --disable-mcp-server.
•To migrate from VS Code's .vscode/mcp.json, remap the servers key to mcpServers in .mcp.json.
•All MCP tool invocations require explicit permission; approvals persist in ~/.copilot/permissions-config.json.
•GitHub Enterprise organizations can enforce a fail-closed MCP server allowlist.
•Use /mcp auth <server> to re-run the OAuth flow for remote servers.

Skills

Supported

SKILL.md Agent Skills (open standard) loaded from project and personal skill folders, invoked automatically by the agent or manually as /skill-name. Managed with /skills and copilot skill commands.

Verified 2026-07-12Docs

Invoke/skill-name

Config files

Path	Scope	Format	Key
`.github/skills/<name>/SKILL.md`	Project	markdown	—
`.agents/skills/<name>/SKILL.md` Cross-agent project location.	Project	markdown	—
`.claude/skills/<name>/SKILL.md` Claude-compatible project location.	Project	markdown	—
`~/.copilot/skills/<name>/SKILL.md` Personal skills for all projects; additional directories via the skillDirectories setting or COPILOT_SKILLS_DIRS.	Global	markdown	—
`~/.agents/skills/<name>/SKILL.md` Cross-agent personal location.	Global	markdown	—

Fields

Field	Type	Description
`name`*	string	Unique identifier. Letters, numbers, and hyphens only; max 64 characters; typically matches the skill directory name.
`description`*	string	What the skill does and when to use it. Max 1024 characters.
`argument-hint`	string	Freeform hint describing expected arguments, shown in the skill picker.
`allowed-tools`	string \| string[]	Tools automatically allowed while the skill is active. Use "*" for all tools.
`user-invocable`	boolean	Whether users can invoke the skill with /SKILL-NAME. Default true.
`disable-model-invocation`	boolean	Prevent the agent from automatically invoking this skill. Default false.
`license`	string	License that applies to this skill.

Examples

Skill that runs a script

---
name: image-convert
description: Converts SVG images to PNG format. Use when asked to convert SVG files.
allowed-tools: shell
---

When asked to convert an SVG to PNG, run the `convert-svg-to-png.sh` script
from this skill's base directory, passing the input SVG file path as the
first argument.

•Location priority (first found wins for duplicate names): .github/skills > .agents/skills > .claude/skills > parent .github/skills (monorepo) > ~/.copilot/skills > ~/.agents/skills > plugin skills > COPILOT_SKILLS_DIRS > bundled > remote org/enterprise skills.
•Skills can bundle scripts and other files; everything in the skill directory is discovered when the skill is invoked.
•Manage with /skills list|info|add|remove|reload in a session or copilot skill from the terminal; disable via disabledSkills in settings.json.
•Pre-approving shell/bash in allowed-tools removes the confirmation step for terminal commands — only do this for fully trusted skills.
•Individual .md files in .claude/commands/ act as a simplified alternative skill format (see the commands surface).

Rules

Supported

Custom instructions from the repository (.github/copilot-instructions.md, .github/instructions/**/*.instructions.md, AGENTS.md) plus personal instructions in ~/.copilot (copilot-instructions.md and instructions/*.instructions.md) applied to every session.

Verified 2026-07-12Docs

Config files

Path	Scope	Format	Key
`.github/copilot-instructions.md` Repository-wide instructions.	Project	markdown	—
`.github/instructions/*/.instructions.md` Path-specific instructions with applyTo frontmatter globs.	Project	markdown	—
`AGENTS.md` Cross-agent instructions file.	Project	markdown	—
`~/.copilot/copilot-instructions.md` Personal custom instructions applied to all sessions.	Global	markdown	—
`~/.copilot/instructions/*.instructions.md` Additional personal instruction files, organizable by topic.	Global	markdown	—

Fields

Field	Type	Description
`applyTo`	string	Glob pattern(s), comma-separated, selecting the files the instructions apply to (path-specific .instructions.md files).

Examples

Path-specific instructions

---
applyTo: "**/*.ts,**/*.tsx"
---
# TypeScript standards
- Use TypeScript for all new code
- Prefer immutable data (const, readonly)

•copilot init (or /init in a session) generates or improves the repository's copilot-instructions.md, documenting build/test/lint commands, architecture, and conventions.
•/instructions lets you view and toggle custom instruction files in a session.
•Personal instruction files in ~/.copilot apply to all sessions regardless of project (see the CLI configuration directory reference).

Hooks

Supported

Versioned JSON hook files run command, HTTP, or prompt handlers at lifecycle events on the local machine. Sources are combined in order: policy, repository .github/hooks, user ~/.copilot/hooks, inline hooks blocks in settings files, and plugins.

Verified 2026-07-12Docs

EventssessionStartsessionEnduserPromptSubmittedpreToolUsepostToolUsepostToolUseFailurepermissionRequestnotificationagentStopsubagentStartsubagentStoperrorOccurredpreCompact

Config files

Path	Scope	Format	Key
`.github/hooks/*.json`	Project	json	hooks
`~/.copilot/hooks/*.json` Or $COPILOT_HOME/hooks/ when COPILOT_HOME is set.	Global	json	hooks
`.github/copilot/settings.json` Inline hooks block; .github/copilot/settings.local.json for personal, gitignored hooks.	Project	json	hooks
`~/.copilot/settings.json` Inline user-level hook definitions.	Global	json	hooks
`/etc/github-copilot/policy.d/*.json` Machine-wide policy hooks installed by administrators (Linux/macOS; Windows uses ProgramData or the registry). Must be root-owned on POSIX.	Enterprise	json	hooks

Fields

Field	Type	Description
`type`	"command" \| "http" \| "prompt"	Handler type. Defaults to command. prompt is only valid on sessionStart.
`bash`	string	Shell command for Unix (command hooks).
`powershell`	string	Shell command for Windows (command hooks).
`command`	string	Cross-platform fallback command, used when bash/powershell are absent.
`cwd`	string	Working directory (relative to the repository root or absolute).
`env`	record<string, string>	Environment variables to set (supports variable expansion).
`timeoutSec`	number	Timeout in seconds. Default 30. timeout is accepted as an alias.
`matcher`	string	Optional regex (anchored ^(?:PATTERN)$) filtering by tool name, notification type, agent name, or compaction trigger, depending on the event.
`url`	string	Target URL for http hooks. https required except localhost with COPILOT_HOOK_ALLOW_LOCALHOST=1.
`headers`	record<string, string>	Request headers for http hooks; allowedEnvVars whitelists env vars expandable inside header values.
`prompt`	string	Text or slash command auto-submitted by a prompt hook (sessionStart only).

Examples

Log tool use and block on stop

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "matcher": "bash|edit",
        "bash": "./scripts/log-tool.sh",
        "timeoutSec": 10
      }
    ],
    "sessionStart": [
      { "type": "prompt", "prompt": "/instructions" }
    ]
  }
}

•Files use { "version": 1, "hooks": { ... } }. camelCase event names deliver camelCase payloads; PascalCase names (e.g. PreToolUse) deliver VS Code/Claude-compatible snake_case payloads with Claude matcher semantics.
•Cross-tool .claude/settings.json and .claude/settings.local.json hooks in the repository are also read.
•preToolUse can return permissionDecision allow/deny/ask and modifiedArgs; permissionRequest can short-circuit the whole permission flow; postToolUse can modify the tool result or inject additionalContext; agentStop/subagentStop can block and force another turn.
•Command preToolUse hooks are fail-closed (crash/timeout denies the tool); HTTP preToolUse hooks are fail-open.
•Prompt hooks (sessionStart only) auto-submit text or a slash command in new interactive sessions.
•Policy hooks in /etc/github-copilot/policy.d/*.json (or the Windows registry/ProgramData equivalents) are machine-wide, load first, and cannot be disabled by disableAllHooks.
•Set disableAllHooks in settings to keep hook config on disk but stop it from running.

Commands

Partial

No native .prompt.md prompt files (GitHub's cheat sheet marks prompt files unsupported for Copilot CLI), but Claude-compatible command files in .claude/commands/ are read as an alternative skill format, and plugins can contribute command directories.

Verified 2026-07-12Docs

Invoke/command-name

Config files

Path	Scope	Format	Key
`.claude/commands/<name>.md` Claude-compatible simplified skill format.	Project	markdown	—

Fields

Field	Type	Description
`description`	string	What the command does.
`argument-hint`	string	Hint describing expected arguments.
`allowed-tools`	string \| string[]	Tools automatically allowed while the command runs.
`disable-model-invocation`	boolean	Prevent the agent from automatically invoking the command.

•Commands are individual .md files in .claude/commands/; the command name is derived from the filename and no name frontmatter field is required.
•Commands have lower priority than skills with the same name — skills are the primary mechanism for user-invocable workflows (invoked as /skill-name).
•Plugins can contribute command directories via the commands field in plugin.json (see the CLI plugin reference).
•Built-in slash commands (/init, /mcp, /skills, /review, ...) are separate and not user-defined.

Settings

Supported

Layered settings: ~/.copilot/settings.json (user), .github/copilot/settings.json (repository, limited key set), .github/copilot/settings.local.json (personal overrides), and MDM managed settings. Edit via /settings or directly.

Verified 2026-07-12Docs

Config files

Path	Scope	Format	Key
`~/.copilot/settings.json` Global user defaults for all repositories; manage via the /settings command.	Global	jsonc	—
`.github/copilot/settings.json` Shared repository configuration (committed); limited to a small supported key set.	Project	json	—
`.github/copilot/settings.local.json` Personal overrides (gitignored); same schema as the repository file, takes precedence over it.	Project	json	—
`/Library/Application Support/GitHubCopilot/managed-settings.json` MDM managed settings (macOS file source; Linux uses /etc/github-copilot/managed-settings.json, Windows uses registry or %ProgramFiles%). Supported keys: enabledPlugins, extraKnownMarketplaces, model, permissions, strictKnownMarketplaces.	Enterprise	json	—

Fields

Field	Type	Description
`model`	string	AI model to use; "auto" lets Copilot pick. Managed by the /model command.
`effortLevel`	"low" \| "medium" \| "high" \| "xhigh"	Reasoning effort level for extended thinking. Default medium.
`hooks`	object	Inline hook definitions keyed by event name (same schema as .github/hooks/*.json files).
`disableAllHooks`	boolean	Disable all repository- and user-level hooks. Default false.
`disabledMcpServers`	string[]	MCP server names to configure but not start.
`disabledSkills`	string[]	Skill names to discover but not load.
`skillDirectories`	string[]	Additional directories to search for skills (besides ~/.copilot/skills/).
`enabledPlugins`	record<string, boolean>	Declarative plugin auto-install, keyed by plugin spec. Also read by the Copilot cloud agent at the repository level.
`allowedUrls`	string[]	URLs or domains allowed without prompting (supports wildcard subdomains like *.github.com).
`deniedUrls`	string[]	URLs or domains always denied; deny rules take precedence over allow rules.
`askUser`	boolean	Allow the agent to ask clarifying questions. Set false for fully autonomous operation. Default true.
`permissions.disableBypassPermissionsMode`	string	When "disable", all allow-all flags (--allow-all-tools, --yolo, ...) are suppressed. An MDM value of "disable" always wins.
`subagents.agents`	record<string, object>	Per-subagent model configuration (model, effortLevel, contextTier), keyed by agent name.
`includeCoAuthoredBy`	boolean	Add a Co-authored-by trailer to git commits made by the agent. Default true.
`mergeStrategy`	"rebase" \| "merge"	Conflict resolution strategy for /pr fix conflicts. Also supported at the repository level.

Examples

~/.copilot/settings.json

{
  "model": "auto",
  "effortLevel": "high",
  "askUser": true,
  "allowedUrls": ["*.github.com"],
  "disabledSkills": ["computer-use-demo"],
  "hooks": {
    "postToolUse": [
      { "type": "command", "bash": "./scripts/log-tool.sh" }
    ]
  }
}

•Precedence (later overrides earlier): built-in defaults > MDM managed settings > user settings > repository settings > local settings > environment variables > command-line flags.
•~/.copilot/settings.json supports JSON with comments (JSONC); user-editable settings migrated here from the legacy config.json, which now holds only internal application state.
•Only companyAnnouncements, disableAllHooks, enabledPlugins, extraKnownMarketplaces, hooks, and mergeStrategy are honored at the repository level; other keys are silently ignored.
•The CLI also reads .claude/settings.json and .claude/settings.local.json for the shared cross-tool subset of repository settings.
•Set COPILOT_HOME to relocate the entire ~/.copilot configuration directory.
•Saved tool/directory approvals live separately in ~/.copilot/permissions-config.json, keyed by repository location.