# GitHub Copilot CLI

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.

Schema: 1.0 · Data: ee5de863c30bdbe4fe7dd3e07c7e22ea9bf4ab2248dbc7c35cdbf60bc28be1db

## Configuration

### MCP

Status: 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).

- global: `~/.copilot/mcp-config.json` (json) — key: mcpServers — Or $COPILOT_HOME/mcp-config.json when COPILOT_HOME is set.
- project: `.mcp.json` (json) — key: mcpServers — Workspace servers; takes precedence over user-level definitions on name conflicts.
- project: `.github/mcp.json` (json) — key: mcpServers — Repository-level alternative to .mcp.json.
- `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[] — User-level tool selection (optional in project configs): ["*"] 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.
- transports: stdio, http, sse
- auth: oauth, headers, env-secrets, oidc
- Tools: supported
- Sampling: supported — Sampling requests require approval; persist per server via the mcp-sampling approval kind in permissions-config.json.
- Elicitation: supported — Elicitation dialogs surface as CLI notifications (notification_type elicitation_dialog).
- Project files accept mcpServers or a bare server-name map. They use strict JSON, not JSONC.
- When both project files exist in one directory, .mcp.json wins. add-mcp 2.3.1 creates .mcp.json or reuses an existing .github/mcp.json.
- A .mcp.json shared with Claude Code represents the same servers for both clients; editing or removing entries affects both.
- 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.

Local and remote servers
```json
{
  "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
```bash
copilot mcp add context7 -- npx -y @upstash/context7-mcp
copilot mcp add --transport http notion https://mcp.notion.com/mcp

```

Source: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers
Checked: 2026-09-07

### Skills

Status: 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.

- project: `.github/skills/<name>/SKILL.md` (markdown)
- project: `.agents/skills/<name>/SKILL.md` (markdown) — Cross-agent project location.
- project: `.claude/skills/<name>/SKILL.md` (markdown) — Claude-compatible project location.
- global: `~/.copilot/skills/<name>/SKILL.md` (markdown) — Personal skills for all projects; additional directories via the skillDirectories setting or COPILOT_SKILLS_DIRS.
- global: `~/.agents/skills/<name>/SKILL.md` (markdown) — Cross-agent personal location.
- `name`: string (required) — Unique identifier. Letters, numbers, and hyphens only; max 64 characters; typically matches the skill directory name.
- `description`: string (required) — 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.
- invocation: /skill-name
- 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).

Skill that runs a script
```markdown
---
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.

```

Source: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills
Checked: 2026-07-12

### Rules

Status: 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.

- project: `.github/copilot-instructions.md` (markdown) — Repository-wide instructions.
- project: `.github/instructions/**/*.instructions.md` (markdown) — Path-specific instructions with applyTo frontmatter globs.
- project: `AGENTS.md` (markdown) — Cross-agent instructions file.
- global: `~/.copilot/copilot-instructions.md` (markdown) — Personal custom instructions applied to all sessions.
- global: `~/.copilot/instructions/*.instructions.md` (markdown) — Additional personal instruction files, organizable by topic.
- `applyTo`: string — Glob pattern(s), comma-separated, selecting the files the instructions apply to (path-specific .instructions.md files).
- 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).

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

```

Source: https://docs.github.com/en/copilot/reference/custom-instructions-support
Checked: 2026-07-12

### Hooks

Status: 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.

- project: `.github/hooks/*.json` (json) — key: hooks
- global: `~/.copilot/hooks/*.json` (json) — key: hooks — Or $COPILOT_HOME/hooks/ when COPILOT_HOME is set.
- project: `.github/copilot/settings.json` (json) — key: hooks — Inline hooks block; .github/copilot/settings.local.json for personal, gitignored hooks.
- global: `~/.copilot/settings.json` (json) — key: hooks — Inline user-level hook definitions.
- enterprise: `/etc/github-copilot/policy.d/*.json` (json) — key: hooks — Machine-wide policy hooks installed by administrators (Linux/macOS; Windows uses ProgramData or the registry). Must be root-owned on POSIX.
- `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).
- events: sessionStart, sessionEnd, userPromptSubmitted, preToolUse, postToolUse, postToolUseFailure, permissionRequest, notification, agentStop, subagentStart, subagentStop, errorOccurred, preCompact
- 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.

Log tool use and block on stop
```json
{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "matcher": "bash|edit",
        "bash": "./scripts/log-tool.sh",
        "timeoutSec": 10
      }
    ],
    "sessionStart": [
      { "type": "prompt", "prompt": "/instructions" }
    ]
  }
}

```

Source: https://docs.github.com/en/copilot/reference/hooks-reference
Checked: 2026-07-12

### Commands

Status: 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.

- project: `.claude/commands/<name>.md` (markdown) — Claude-compatible simplified skill format.
- `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.
- invocation: /command-name
- 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.
Source: https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference
Checked: 2026-07-12

### Settings

Status: 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.

- global: `~/.copilot/settings.json` (jsonc) — Global user defaults for all repositories; manage via the /settings command.
- project: `.github/copilot/settings.json` (json) — Shared repository configuration (committed); limited to a small supported key set.
- project: `.github/copilot/settings.local.json` (json) — Personal overrides (gitignored); same schema as the repository file, takes precedence over it.
- enterprise: `/Library/Application Support/GitHubCopilot/managed-settings.json` (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.
- `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. Values: disable
- `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.
- 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.

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

```

Source: https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference
Checked: 2026-07-12

## Search, browser & identification

Not researched. Unknown does not mean unsupported.