You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/copilot/reference/cli-command-reference.md
+321-2Lines changed: 321 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,6 +19,8 @@ contentType: reference
19
19
|`copilot init`| Initialize {% data variables.product.prodname_copilot_short %} custom instructions for this repository. |
20
20
|`copilot update`| Download and install the latest version. |
21
21
|`copilot version`| Display version information and check for updates. |
22
+
|`copilot login`| Authenticate with {% data variables.product.prodname_copilot_short %} via the OAuth device flow. Accepts `--host HOST` to specify the {% data variables.product.github %} host URL (default: `https://github.com`). |
23
+
|`copilot logout`| Sign out of {% data variables.product.github %} and remove stored credentials. |
22
24
|`copilot plugin`| Manage plugins and plugin marketplaces. |
| ctrl+o | While there is nothing in the prompt input, this expands recent items in {% data variables.product.prodname_copilot_short %}'s response timeline to show more details. |
41
44
| ctrl+e | While there is nothing in the prompt input, this expands all items in {% data variables.product.prodname_copilot_short %}'s response timeline. |
45
+
| ctrl+t | Expand/collapse display of reasoning in responses. |
42
46
43
47
## Navigation shortcuts in the interactive interface
| <kbd>Ctrl</kbd>+<kbd>A</kbd> | Move to beginning of the line (when typing). |
52
+
| <kbd>Ctrl</kbd>+<kbd>B</kbd> | Move to the previous character. |
48
53
| <kbd>Ctrl</kbd>+<kbd>E</kbd> | Move to end of the line (when typing). |
54
+
| <kbd>Ctrl</kbd>+<kbd>F</kbd> | Move to the next character. |
49
55
| <kbd>Ctrl</kbd>+<kbd>H</kbd> | Delete the previous character. |
50
-
| <kbd>Ctrl</kbd>+<kbd>W</kbd> | Delete the previous word. |
51
-
| <kbd>Ctrl</kbd>+<kbd>U</kbd> | Delete from cursor to beginning of the line. |
52
56
| <kbd>Ctrl</kbd>+<kbd>K</kbd> | Delete from cursor to end of the line. |
57
+
| <kbd>Ctrl</kbd>+<kbd>U</kbd> | Delete from cursor to beginning of the line. |
58
+
| <kbd>Ctrl</kbd>+<kbd>W</kbd> | Delete the previous word. |
59
+
| <kbd>Home</kbd> | Move to the start of the current line. |
60
+
| <kbd>End</kbd> | Move to the end of the current line. |
61
+
| <kbd>Ctrl</kbd>+<kbd>Home</kbd> | Move to the start of the text. |
62
+
| <kbd>Ctrl</kbd>+<kbd>End</kbd> | Move to the end of the text. |
53
63
| <kbd>Meta</kbd>+<kbd>←</kbd>/<kbd>→</kbd> | Move the cursor by a word. |
54
64
| <kbd>↑</kbd>/<kbd>↓</kbd> | Navigate the command history. |
55
65
@@ -153,3 +163,312 @@ For a complete list of available slash commands enter `/help` in the CLI's inter
153
163
|`--yolo`| Enable all permissions (equivalent to `--allow-all`). |
154
164
155
165
For a complete list of commands and options, run `copilot help`.
166
+
167
+
## Tool permission patterns
168
+
169
+
The `--allow-tool` and `--deny-tool` options accept permission patterns in the format `Kind(argument)`. The argument is optional—omitting it matches all tools of that kind.
|`write`| File creation or modification |`write`, `write(src/*.ts)`|
175
+
|`read`| File or directory reads |`read`, `read(.env)`|
176
+
| SERVER-NAME | MCP server tool invocation |`MyMCP(create_issue)`, `MyMCP`|
177
+
|`url`| URL access via web-fetch or shell |`url(github.com)`, `url(https://*.api.com)`|
178
+
|`memory`| Storing facts to agent memory |`memory`|
179
+
180
+
For `shell` rules, the `:*` suffix matches the command stem followed by a space, preventing partial matches. For example, `shell(git:*)` matches `git push` and `git pull` but does not match `gitea`.
181
+
182
+
Deny rules always take precedence over allow rules, even when `--allow-all` is set.
|`COPILOT_ALLOW_ALL`| Set to `true` to allow all permissions automatically (equivalent to `--allow-all`). |
201
+
|`COPILOT_AUTO_UPDATE`| Set to `false` to disable automatic updates. |
202
+
|`COPILOT_CUSTOM_INSTRUCTIONS_DIRS`| Comma-separated list of additional directories for custom instructions. |
203
+
|`COPILOT_SKILLS_DIRS`| Comma-separated list of additional directories for skills. |
204
+
|`COPILOT_EDITOR`| Editor command for interactive editing (checked after `$VISUAL` and `$EDITOR`). Defaults to `vi` if none are set. |
205
+
|`COPILOT_GITHUB_TOKEN`| Authentication token. Takes precedence over `GH_TOKEN` and `GITHUB_TOKEN`. |
206
+
|`GH_TOKEN`| Authentication token. Takes precedence over `GITHUB_TOKEN`. |
207
+
|`GITHUB_TOKEN`| Authentication token. |
208
+
|`XDG_CONFIG_HOME`| Override the configuration directory. Default: `$HOME/.copilot`. |
209
+
|`XDG_STATE_HOME`| Override the state directory. Default: `$HOME/.copilot`. |
210
+
|`USE_BUILTIN_RIPGREP`| Set to `false` to use the system ripgrep instead of the bundled version. |
211
+
|`PLAIN_DIFF`| Set to `true` to disable rich diff rendering. |
212
+
|`COLORFGBG`| Fallback for dark/light terminal background detection. |
213
+
|`COPILOT_CLI_ENABLED_FEATURE_FLAGS`| Comma-separated list of feature flags to enable (for example, `"SOME_FEATURE,SOME_OTHER_FEATURE"`). |
214
+
215
+
## Configuration file settings
216
+
217
+
User settings are stored in `~/.copilot/config.json`. Project-level settings can be placed in `.copilot/settings.json` (committed to the repository) or `.copilot/settings.local.json` (personal overrides—add to `.gitignore`). Settings cascade from user to project to local, with more specific scopes overriding more general ones. Command-line flags and environment variables always take the highest precedence.
218
+
219
+
| Key | Type | Default | Description |
220
+
|-----|------|---------|-------------|
221
+
|`allowed_urls`|`string[]`|`[]`| URLs or domains allowed without prompting. |
222
+
|`alt_screen`|`boolean`|`false`| Use the terminal alternate screen buffer. |
|`model`|`string`| varies | AI model to use (see the `/model` command). |
235
+
|`reasoning_effort`|`"low"`\|`"medium"`\|`"high"`\|`"xhigh"`|`"medium"`| Reasoning effort level for extended thinking. Higher levels use more compute. |
236
+
|`render_markdown`|`boolean`|`true`| Render Markdown in terminal output. |
|`store_token_plaintext`|`boolean`|`false`| Store authentication tokens in plaintext in the config file when no system keychain is available. |
240
+
|`streamer_mode`|`boolean`|`false`| Hide preview model names and quota details (useful when recording). |
241
+
|`theme`|`"auto"`\|`"dark"`\|`"light"`|`"auto"`| Terminal color theme. |
242
+
|`trusted_folders`|`string[]`|`[]`| Folders with pre-granted file access. |
243
+
|`update_terminal_title`|`boolean`|`true`| Show the current intent in the terminal title. |
244
+
245
+
## Hooks reference
246
+
247
+
Hooks are external commands that execute at specific lifecycle points during a session, enabling custom automation, security controls, and integrations. Hook configuration files are loaded automatically from `.github/hooks/*.json` in your repository.
248
+
249
+
### Hook configuration format
250
+
251
+
Hook configuration files use JSON format with version `1`:
252
+
253
+
```json
254
+
{
255
+
"version": 1,
256
+
"hooks": {
257
+
"preToolUse": [
258
+
{
259
+
"type": "command",
260
+
"bash": "your-bash-command",
261
+
"powershell": "your-powershell-command",
262
+
"cwd": "optional/working/directory",
263
+
"env": { "VAR": "value" },
264
+
"timeoutSec": 30
265
+
}
266
+
]
267
+
}
268
+
}
269
+
```
270
+
271
+
| Field | Type | Required | Description |
272
+
|-------|------|----------|-------------|
273
+
|`type`|`"command"`| Yes | Must be `"command"`. |
274
+
|`bash`| string | One of `bash`/`powershell`| Shell command for Unix. |
275
+
|`powershell`| string | One of `bash`/`powershell`| Shell command for Windows. |
276
+
|`cwd`| string | No | Working directory for the command (relative to repository root or absolute). |
277
+
|`env`| object | No | Environment variables to set (supports variable expansion). |
278
+
|`timeoutSec`| number | No | Timeout in seconds. Default: `30`. |
279
+
280
+
### Hook events
281
+
282
+
| Event | Fires when | Output processed |
283
+
|-------|-----------|-----------------|
284
+
|`sessionStart`| A new or resumed session begins. | No |
285
+
|`sessionEnd`| The session terminates. | No |
286
+
|`userPromptSubmitted`| The user submits a prompt. | No |
287
+
|`preToolUse`| Before each tool executes. | Yes — can allow, deny, or modify. |
288
+
|`postToolUse`| After each tool completes. | No |
289
+
|`agentStop`| The main agent finishes a turn. | Yes — can block and force continuation. |
290
+
|`subagentStop`| A subagent completes. | Yes — can block and force continuation. |
291
+
|`errorOccurred`| An error occurs during execution. | No |
292
+
293
+
### `preToolUse` decision control
294
+
295
+
The `preToolUse` hook can control tool execution by writing a JSON object to stdout.
If multiple hooks of the same type are configured, they execute in order. For `preToolUse`, if any hook returns `"deny"`, the tool is blocked. Hook failures (non-zero exit codes or timeouts) are logged and skipped—they never block agent execution.
325
+
326
+
## MCP server configuration
327
+
328
+
MCP servers provide additional tools to the CLI agent. Configure persistent servers in `~/.copilot/mcp-config.json`. Use `--additional-mcp-config` to add servers for a single session.
329
+
330
+
### Transport types
331
+
332
+
| Type | Description | Required fields |
333
+
|------|-------------|----------------|
334
+
|`local` / `stdio`| Local process communicating via stdin/stdout. |`command`, `args`|
335
+
|`http`| Remote server using streamable HTTP transport. |`url`|
336
+
|`sse`| Remote server using Server-Sent Events transport. |`url`|
337
+
338
+
### Local server configuration fields
339
+
340
+
| Field | Required | Description |
341
+
|-------|----------|-------------|
342
+
|`command`| Yes | Command to start the server. |
343
+
|`args`| Yes | Command arguments (array). |
344
+
|`tools`| Yes | Tools to enable: `["*"]` for all, or a list of specific tool names. |
345
+
|`env`| No | Environment variables. Supports `$VAR`, `${VAR}`, and `${VAR:-default}` expansion. |
346
+
|`cwd`| No | Working directory for the server. |
347
+
|`timeout`| No | Tool call timeout in milliseconds. |
348
+
|`type`| No |`"local"` or `"stdio"`. Default: `"local"`. |
349
+
350
+
### Remote server configuration fields
351
+
352
+
| Field | Required | Description |
353
+
|-------|----------|-------------|
354
+
|`type`| Yes |`"http"` or `"sse"`. |
355
+
|`url`| Yes | Server URL. |
356
+
|`tools`| Yes | Tools to enable. |
357
+
|`headers`| No | HTTP headers. Supports variable expansion. |
358
+
|`oauthClientId`| No | Static OAuth client ID (skips dynamic registration). |
359
+
|`oauthPublicClient`| No | Whether the OAuth client is public. Default: `true`. |
360
+
|`timeout`| No | Tool call timeout in milliseconds. |
361
+
362
+
### Filter mapping
363
+
364
+
Control how MCP tool output is processed using the `filterMapping` field in a server's configuration.
365
+
366
+
| Mode | Description |
367
+
|------|-------------|
368
+
|`none`| No filtering. |
369
+
|`markdown`| Format output as Markdown. |
370
+
|`hidden_characters`| Remove hidden or control characters. Default. |
371
+
372
+
### Built-in MCP servers
373
+
374
+
The CLI includes built-in MCP servers that are available without additional setup.
375
+
376
+
| Server | Description |
377
+
|--------|-------------|
378
+
|`github-mcp-server`| {% data variables.product.github %} API integration: issues, pull requests, commits, code search, and {% data variables.product.prodname_actions %}. |
379
+
|`playwright`| Browser automation: navigate, click, type, screenshot, and form handling. |
380
+
|`fetch`| HTTP requests via the `fetch` tool. |
381
+
|`time`| Time utilities: `get_current_time` and `convert_time`. |
382
+
383
+
Use `--disable-builtin-mcps` to disable all built-in servers, or `--disable-mcp-server SERVER-NAME` to disable a specific one.
384
+
385
+
## Skills reference
386
+
387
+
Skills are Markdown files that extend what the CLI can do. Each skill lives in its own directory containing a `SKILL.md` file. When invoked (via `/SKILL-NAME` or automatically by the agent), the skill's content is injected into the conversation.
388
+
389
+
### Skill frontmatter fields
390
+
391
+
| Field | Type | Required | Description |
392
+
|-------|------|----------|-------------|
393
+
|`name`| string | Yes | Unique identifier for the skill. Letters, numbers, and hyphens only. Max 64 characters. |
394
+
|`description`| string | Yes | What the skill does and when to use it. Max 1024 characters. |
395
+
|`allowed-tools`| string or string[]| No | Comma-separated list or YAML array of tools that are automatically allowed when the skill is active. Use `"*"` for all tools. |
396
+
|`user-invocable`| boolean | No | Whether users can invoke the skill with `/SKILL-NAME`. Default: `true`. |
397
+
|`disable-model-invocation`| boolean | No | Prevent the agent from automatically invoking this skill. Default: `false`. |
398
+
399
+
### Skill locations
400
+
401
+
Skills are loaded from these locations in priority order (first found wins for duplicate names).
Commands are an alternative to skills stored as individual `.md` files in `.claude/commands/`. The command name is derived from the filename. Command files use a simplified format (no `name` field required) and support `description`, `allowed-tools`, and `disable-model-invocation`. Commands have lower priority than skills with the same name.
417
+
418
+
## Custom agents reference
419
+
420
+
Custom agents are specialized AI agents defined in Markdown files. The filename (minus extension) becomes the agent ID. Use `.agent.md` or `.md` as the file extension.
421
+
422
+
### Built-in agents
423
+
424
+
| Agent | Default model | Description |
425
+
|-------|--------------|-------------|
426
+
|`explore`| claude-haiku-4.5 | Fast codebase exploration. Searches files, reads code, and answers questions. Returns focused answers under 300 words. Safe to run in parallel. |
427
+
|`task`| claude-haiku-4.5 | Command execution (tests, builds, lints). Returns brief summary on success, full output on failure. |
428
+
|`code-review`| claude-sonnet-4.5 | High signal-to-noise code review. Analyzes diffs for bugs, security issues, and logic errors. |
429
+
|`general-purpose`| claude-sonnet-4.5 | Full-capability agent for complex multi-step tasks. Runs in a separate context window. |
430
+
431
+
### Custom agent frontmatter fields
432
+
433
+
| Field | Type | Required | Description |
434
+
|-------|------|----------|-------------|
435
+
|`name`| string | No | Display name. Defaults to the filename. |
436
+
|`description`| string | Yes | Description shown in the agent list and `task` tool. |
437
+
|`model`| string | No | AI model for this agent. When unset, inherits the outer agent's model. |
438
+
|`tools`| string[]| No | Tools available to the agent. Default: `["*"]` (all tools). |
439
+
|`mcp-servers`| object | No | MCP servers to connect. Uses the same schema as `~/.copilot/mcp-config.json`. |
440
+
|`infer`| boolean | No | Allow auto-delegation by the main agent. Default: `true`. |
441
+
442
+
### Custom agent locations
443
+
444
+
| Scope | Location |
445
+
|-------|----------|
446
+
| Project |`.github/agents/` or `.claude/agents/`|
447
+
| User |`~/.copilot/agents/` or `~/.claude/agents/`|
448
+
| Plugin |`<plugin>/agents/`|
449
+
450
+
Project-level agents take precedence over user-level agents. Plugin agents have the lowest priority.
451
+
452
+
## Permission approval responses
453
+
454
+
When the CLI prompts for permission to execute an operation, you can respond with the following keys.
455
+
456
+
| Key | Effect |
457
+
|-----|--------|
458
+
|`y`| Allow this specific request once. |
459
+
|`n`| Deny this specific request once. |
460
+
|`!`| Allow all similar requests for the rest of the session. |
461
+
|`#`| Deny all similar requests for the rest of the session. |
462
+
|`?`| Show detailed information about the request. |
463
+
464
+
Session approvals reset when you run `/clear` or start a new session.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments