{"meta":{"title":"GitHub Copilot CLI configuration directory","intro":"Find information about the ~/.copilot directory, where Copilot CLI stores configuration, session data, and customizations.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/copilot","title":"GitHub Copilot"},{"href":"/en/copilot/reference","title":"Reference"},{"href":"/en/copilot/reference/copilot-cli-reference","title":"Copilot CLI reference"},{"href":"/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference","title":"CLI configuration directory"}],"documentType":"article"},"body":"# GitHub Copilot CLI configuration directory\n\nFind information about the ~/.copilot directory, where Copilot CLI stores configuration, session data, and customizations.\n\nCopilot CLI stores its configuration, session history, logs, and customizations in a single directory on your machine. By default, this directory is `~/.copilot` (that is, `$HOME/.copilot`).\n\nThis article describes the contents of this directory and how you can use them.\n\n## Directory overview\n\nThe `~/.copilot` directory contains the following top-level items.\n\n| Path | Type | Description |\n| ------------------------- | --------- | ---------------------------------------------------------------------------------------------------- |\n| `agents/` | Directory | Personal custom agent definitions |\n| `config.json` | File | Automatically managed application state (authentication, installed plugins, and other internal data) |\n| `copilot-instructions.md` | File | Personal custom instructions (applied to all sessions) |\n| `extensions/` | Directory | Personal extensions loaded by the CLI |\n| `hooks/` | Directory | User-level hook scripts |\n| `ide/` | Directory | IDE integration state |\n| `installed-plugins/` | Directory | Installed plugin files |\n| `instructions/` | Directory | Additional personal `*.instructions.md` files |\n| `logs/` | Directory | Session log files |\n| `lsp-config.json` | File | User-level LSP server definitions |\n| `mcp-config.json` | File | User-level MCP server definitions |\n| `mcp-oauth-config/` | Directory | MCP OAuth token and registration fallback storage |\n| `mcp-secrets/` | Directory | Local fallback storage and index for MCP secret placeholders |\n| `permissions-config.json` | File | Saved tool and directory permissions per project |\n| `plugin-data/` | Directory | Persistent data for installed plugins |\n| `session-state/` | Directory | Session history and workspace data |\n| `command-history-state/` | Directory | Command history data |\n| `session-store.db` | File | SQLite database for cross-session data |\n| `settings.json` | File | Your personal configuration settings |\n| `skills/` | Directory | Personal custom skill definitions |\n\n> \\[!NOTE]\n> Not all of these items appear immediately. Some are created on demand the first time you use a particular feature—for example, `installed-plugins/` appears only after you install your first plugin.\n\n## User-editable files\n\nThe following files are designed to be edited by you directly, or managed through CLI commands.\n\n### `settings.json`\n\nThis is the primary configuration file for Copilot CLI. Within a session, you can use the interactive `/settings` command to change specific values, or run `/settings KEY VALUE` to set a single value. See [Changing settings with the \\`/settings\\` command](/en/copilot/how-tos/copilot-cli/customize-copilot/change-settings). Alternatively, you can edit the `settings.json` file directly in a text editor. The file supports JSON with comments (JSONC).\n\nBy default, this file is located in the `~/.copilot` directory, which is the user-level configuration directory. It contains global user-level defaults for all repositories. You can change the location of this directory by setting the `COPILOT_HOME` environment variable to a different path.\n\n> \\[!NOTE]\n> User-editable settings were originally stored in `config.json`. They have been moved to `settings.json`. Any user settings present in `config.json` on startup are automatically migrated to `settings.json`.\n\nIf `settings.json` fails to read, parse, or validate, Copilot CLI ignores the invalid values (recognized `config.json` values are still merged in) and shows a startup warning on the timeline directing you to the **Problems** tab of the `/settings` command. Open that tab to see the specific error, then fix the reported issue to restore the affected settings.\n\nIf `settings.json` contains a top-level key that isn't a recognized setting (for example, a typo), Copilot CLI lists it in the **Problems** tab of the `/settings` command instead of on the timeline or in stderr. The tab's label shows a count (for example, `Problems (2)`) when any configuration scope has an issue. `$schema` is tolerated and never reported.\n\nIf `~/.copilot/settings.json` is a symlink—for example, to sync settings through a dotfiles repository—writes from the `/settings` command follow the symlink and update its target instead of replacing the symlink with a regular file.\n\nFor the full list of settings and how they interact with repository-level configuration, see [Configuration file settings](#configuration-file-settings) later in this article.\n\n> \\[!TIP]\n> Run `copilot help config` in your terminal for a quick reference.\n\n### `copilot-instructions.md`\n\nPersonal custom instructions that apply to all your sessions, regardless of which project you're working in. This file works the same way as a repository-level `copilot-instructions.md` but applies globally.\n\nFor more information, see [Adding repository custom instructions for GitHub Copilot](/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions).\n\n### `instructions/`\n\nStore additional personal instruction files here as `*.instructions.md` files. These are loaded alongside `copilot-instructions.md` and apply to all your sessions. You can organize instructions by topic—for example, `~/.copilot/instructions/code-style.instructions.md`.\n\n### `mcp-config.json`\n\nDefines MCP (Model Context Protocol) servers available at the user level. These servers are available in all your sessions, regardless of which project directory you're in. Project-level MCP configurations (in `.mcp.json` or `.github/mcp.json`) take precedence over user-level definitions when server names conflict.\n\nFor more information, see [Adding MCP servers for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers).\n\n### `lsp-config.json`\n\nDefines Language Server Protocol (LSP) servers available at the user level. These servers provide language intelligence (diagnostics, completions, etc.) to the agent. Manage this file using the `/lsp` slash command, or edit it directly.\n\nFor more information, see [Adding LSP servers for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers).\n\n### `agents/`\n\nStore personal custom agent definitions here as `.agent.md` files. Agents placed in this directory are available in all your sessions. Project-level agents (in `.github/agents/`) take precedence over personal agents if they share the same name.\n\nFor more information, see [Creating and using custom agents for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli).\n\n### `skills/`\n\nStore personal custom skill definitions here. Each skill lives in a subdirectory containing a `SKILL.md` file—for example, `~/.copilot/skills/my-skill/SKILL.md`. Personal skills are available in all your sessions. Project-level skills take precedence over personal skills if they share the same name.\n\nFor more information, see [Adding agent skills for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills).\n\n### `hooks/`\n\nStore user-level hook scripts here. These hooks apply to all your sessions. You can also define hooks inline in your user configuration file (`~/.copilot/settings.json`) using the `hooks` key. Repository-level hooks (in `.github/hooks/`) are loaded alongside user-level hooks.\n\nFor more information, see [Using hooks with GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/use-hooks).\n\n### `extensions/`\n\nStore user-level extension files here. Extensions in this directory are available across sessions.\n\nYou can create files in this directory manually, or scaffold an extension and then edit the generated file.\n\n## Automatically managed files\n\nThe following items are managed by the CLI. You generally should not edit them manually.\n\n### `config.json`\n\nStores internal application state that is managed automatically by the CLI, including authentication data, installed plugin metadata, and other runtime information. You should not normally need to edit this file.\n\n> \\[!NOTE]\n> Earlier versions of Copilot CLI stored both user settings and application state in `config.json`. User-editable settings are now located in `settings.json`. Any user settings in `config.json` at startup are automatically migrated to `settings.json`. Application state fields—such as `loggedInUsers`, `installedPlugins`, `firstLaunchAt`, and `staff`—remain in `config.json` and are not migrated.\n\n### `permissions-config.json`\n\nStores your saved tool and directory permission decisions, organized by project location. When you approve a tool or grant access to a directory for the current location, the CLI records the decision here so you aren't prompted again in the same repository or directory.\n\n> \\[!NOTE]\n> If you want to reset permissions for a project, you can delete the relevant entry from this file. However, editing the file while a session is running may cause unexpected behavior. The CLI automatically removes entries whose location path no longer exists on disk.\n\n#### File location\n\nCopilot CLI resolves the file from the configuration directory.\n\n| Priority | Source | File used |\n| -------- | ------------------------ | --------------------------------------- |\n| 1 | `--config-dir=DIRECTORY` | `DIRECTORY/permissions-config.json` |\n| 2 | `COPILOT_HOME` | `$COPILOT_HOME/permissions-config.json` |\n| 3 | Default | `~/.copilot/permissions-config.json` |\n\nThe CLI uses only the first applicable configuration directory in this order. It doesn't also load `permissions-config.json` from the lower-priority locations.\n\nThe `--config-dir` option is a legacy option. Prefer `COPILOT_HOME` when you need to change the configuration directory.\n\nOn Windows, the default file is typically:\n\n```text\nC:\\Users\\YOUR-USER\\.copilot\\permissions-config.json\n```\n\nOlder builds used an extensionless file named `permissions-config`. If `permissions-config.json` doesn't exist but the extensionless file does, the CLI still honors the legacy file. Use `permissions-config.json` for new edits.\n\nPrevious XDG-based configuration locations are migrated to `~/.copilot` at startup when `COPILOT_HOME` isn't set.\n\n#### Location keys\n\nThe top-level `locations` object is keyed by an absolute path.\n\n* For a Git repository, use the Git root used for permission scoping.\n* Linked worktrees resolve to the main repository root, so they share permissions with the main worktree.\n* Submodules use their own working directory.\n* For a directory that isn't in a Git repository, use the normalized current working directory.\n\nThe key must match the location where Copilot CLI is running. If the key doesn't match, the saved approvals won't apply.\n\nThe CLI loads the matching location's approvals when a session starts and when the active working directory changes.\n\n#### Schema\n\nThe file must contain a JSON object.\n\n| Field | Type | Required | Default | Allowed values | Description |\n| --------------------------------------- | ---------------- | -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |\n| `locations` | Object | No | `{}` | Absolute path keys | Map of location keys to saved approvals. |\n| `locations.` | Object | No | `{}` | Any absolute location key | Saved approvals for one repository or directory. |\n| `locations..tool_approvals` | Array | No | `[]` | Approval objects | Tools approved for this location. |\n| `locations..allowed_directories` | Array of strings | No | `[]` | Absolute directory paths | Extra directories that the path gate can access for this location. Each directory must exist when the CLI applies the configuration. |\n| `locations..tool_approvals[].kind` | String | Yes | None | `commands`, `read`, `write`, `mcp`, `mcp-sampling`, `memory`, `custom-tool`, `extension-management`, `extension-permission-access` | Selects the approval type. |\n| `commandIdentifiers` | Array of strings | Yes, for `commands` | None | Command identifiers | Shell command identifiers to approve. |\n| `serverName` | String | Yes, for `mcp` and `mcp-sampling` | None | MCP server name | MCP server to approve. |\n| `toolName` | String or `null` | Yes, for `mcp` | None | MCP tool name, or `null` | MCP tool to approve. Use `null` to approve every tool on the server. |\n| `toolName` | String | Yes, for `custom-tool` | None | Custom tool name | Custom tool to approve by exact name. |\n| `operation` | String | No, for `extension-management` | Omitted | Extension operation name | Extension-management operation to approve. Omit this field to approve all extension-management operations. |\n| `extensionName` | String | Yes, for `extension-permission-access` | None | Extension name | Extension whose access to permission-gated capabilities is approved. |\n\n`permissions-config.json` doesn't support deny rules, \"ask\" rules, default modes, URL rules, tool filtering, or repository-local shared policy. For those behaviors, use command-line options such as `--deny-tool`, `--available-tools`, `--excluded-tools`, `--allow-url`, and `--deny-url`. Saved URL rules are stored in `settings.json`, not in `permissions-config.json`.\n\nUnknown fields aren't part of the schema. The CLI may ignore them, and later writes may remove them.\n\n#### Approval kinds\n\nEach item in `tool_approvals` must be one of the following objects.\n\n| `kind` | Required fields | Optional fields | Meaning |\n| ----------------------------- | ------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| `commands` | `commandIdentifiers` | None | Approves matching shell command identifiers. |\n| `read` | None | None | Approves read tool requests. Interactive CLI sessions already approve reads automatically, so this is usually unnecessary. |\n| `write` | None | None | Approves file creation and modification tool requests. A path prompt can still apply for paths outside the allowed directories. |\n| `mcp` | `serverName`, `toolName` | None | Approves one MCP tool, or every tool on the server when `toolName` is `null`. |\n| `mcp-sampling` | `serverName` | None | Approves MCP sampling requests for one server. |\n| `memory` | None | None | Approves memory write and vote requests. |\n| `custom-tool` | `toolName` | None | Approves a custom tool by exact name. |\n| `extension-management` | None | `operation` | Approves extension management. If `operation` is omitted, all extension-management operations match. |\n| `extension-permission-access` | `extensionName` | None | Approves an extension's access to permission-gated capabilities. |\n\nFor MCP approvals, `serverName` must match the configured MCP server name exactly. Use the raw server name from your MCP configuration, not a sanitized tool-name prefix.\n\n#### Shell command matching\n\n`permissions-config.json` doesn't support regular expressions or general glob patterns. String values are matched literally, except that a trailing `:*` in a shell `commandIdentifiers` value matches the text before `:*`, either by itself or followed by a space and more text. A plain `*` has no special meaning, so `git*` doesn't match `git status`.\n\n| Pattern | Matches | Doesn't match |\n| ------------ | ------------------------------------- | -------------------- |\n| `git status` | `git status` | `git status --short` |\n| `git:*` | `git`, `git status`, `git push` | `gitea` |\n| `gh pr:*` | `gh pr`, `gh pr view`, `gh pr create` | `gh repo view` |\n\n#### Directory matching\n\n`allowed_directories` entries allow Copilot CLI to access paths inside those directories without a separate path prompt. They don't approve the tool operation itself. For example, editing a file in an allowed directory can still require a `write` approval.\n\nEach `allowed_directories` entry must be an absolute, non-empty, accessible directory. The CLI resolves symlinks before comparing paths, blocks UNC network paths unless they are extended-length local paths, compares paths case-insensitively on Windows, and compares paths case-sensitively on other platforms. If an entry can't be applied, the CLI logs a warning and skips that entry.\n\n#### Examples\n\nAllow all Git subcommands and access an extra local directory:\n\n```json copy\n{\n \"locations\": {\n \"C:\\\\src\\\\my-repo\": {\n \"tool_approvals\": [\n {\n \"kind\": \"commands\",\n \"commandIdentifiers\": [\"git:*\"]\n }\n ],\n \"allowed_directories\": [\"C:\\\\src\\\\shared-docs\"]\n }\n }\n}\n```\n\nAllow selected commands while still asking before file writes:\n\n```json copy\n{\n \"locations\": {\n \"/Users/YOUR-USER/src/my-repo\": {\n \"tool_approvals\": [\n {\n \"kind\": \"commands\",\n \"commandIdentifiers\": [\n \"git status\",\n \"git diff\",\n \"git log\",\n \"npm test\",\n \"npm run build\"\n ]\n }\n ]\n }\n }\n}\n```\n\nApprove file writes and one MCP server for a repository:\n\n```json copy\n{\n \"locations\": {\n \"/home/YOUR-USER/src/my-repo\": {\n \"tool_approvals\": [\n {\n \"kind\": \"write\"\n },\n {\n \"kind\": \"mcp\",\n \"serverName\": \"github-mcp-server\",\n \"toolName\": null\n }\n ]\n }\n }\n}\n```\n\nApprove one MCP tool, memory writes, and extension permission access:\n\n```json copy\n{\n \"locations\": {\n \"C:\\\\src\\\\my-repo\": {\n \"tool_approvals\": [\n {\n \"kind\": \"mcp\",\n \"serverName\": \"github-mcp-server\",\n \"toolName\": \"search_code\"\n },\n {\n \"kind\": \"memory\"\n },\n {\n \"kind\": \"extension-permission-access\",\n \"extensionName\": \"my-extension\"\n }\n ]\n }\n }\n}\n```\n\n### `session-state/`\n\nContains session history data, organized by session ID in subdirectories. Each session directory stores an event log (`events.jsonl`) and workspace artifacts (plans, checkpoints, tracked files). This data enables session resume (`--resume` or `--continue`).\n\nDeleting files from this directory only removes local copies. If you have synced sessions to your GitHub account, the synced data is stored separately and is not affected by local file deletion. You can delete or hide synced sessions from GitHub.com. For more information, see [About GitHub Copilot CLI session data](/en/copilot/concepts/agents/copilot-cli/chronicle#managing-your-session-data).\n\n### `command-history-state/`\n\nContains command history data used for reverse search (Ctrl+R) and history navigation in the interactive interface. This directory is managed automatically and should not be edited.\n\n### `session-store.db`\n\nA SQLite database used by the CLI for cross-session data such as checkpoint indexing and search. This file is automatically managed and should not be edited.\n\nIf you delete this file, you can rebuild it using the `/chronicle reindex` command. Reindexing also syncs your session data to your account.\n\n### `logs/`\n\nContains log files for CLI sessions. Each session creates a log file named `process-{timestamp}-{pid}.log`. These files are useful for debugging issues.\n\nThe CLI may also create extension-specific logs under `logs/extensions/`.\n\nThis is separate from `~/.copilot/extensions/`, which stores user-authored extension code.\n\n> \\[!TIP]\n> To find the log file for your current session, enter `/session` in an interactive session. The output includes the full path to the log file, along with other session details such as the session ID, duration, and working directory.\n\n### `installed-plugins/`\n\nContains the files for plugins you have installed. Plugins installed from a marketplace are stored under `installed-plugins/{marketplace-name}/{plugin-name}/`. Directly installed plugins are stored under `installed-plugins/_direct/`. Manage plugins using the `copilot plugin` commands rather than editing this directory directly.\n\nFor more information, see [GitHub Copilot CLI plugin reference](/en/copilot/reference/copilot-cli-reference/cli-plugin-reference).\n\n### `plugin-data/`\n\nContains persistent data for installed plugins, organized by marketplace and plugin name. This data is managed by the plugins themselves and should not be edited manually.\n\n### `ide/`\n\nContains lock files and state for IDE integrations (for example, when Copilot CLI connects to Visual Studio Code). This directory is automatically managed.\n\n### `mcp-oauth-config/`\n\nContains MCP OAuth token, registration, and PKCE fallback files when keychain-backed storage is unavailable. This directory is automatically managed.\n\n### `mcp-secrets/`\n\nContains fallback file storage and an index for MCP secret placeholders when keychain-backed storage is unavailable. This directory is automatically managed.\n\n## Changing the location of the configuration directory\n\nTo override the default `~/.copilot` location, set the `COPILOT_HOME` environment variable to the path of the directory you want to use.\n\n```bash copy\nexport COPILOT_HOME=/path/to/my/copilot-config\n```\n\n### Things to be aware of\n\n* `COPILOT_HOME` replaces the entire `~/.copilot` path. The value you set should be the complete path to the directory you want to use for the configuration files and subdirectories.\n* Changing the directory means your existing configuration, session history, installed plugins, and saved permissions will not be found in the new location. Copy or move the contents of `~/.copilot` to the new location if you want to preserve them.\n* The **cache directory** (used for marketplace caches, auto-update packages, and other ephemeral data) follows platform conventions and is not affected by `COPILOT_HOME`. It is located at:\n\n * **macOS**: `~/Library/Caches/copilot`\n * **Linux**: `$XDG_CACHE_HOME/copilot` or `~/.cache/copilot`\n * **Windows**: `%LOCALAPPDATA%/copilot`\n\n To override the cache directory separately, set `COPILOT_CACHE_HOME`.\n\n## What you can safely delete\n\n| Item | Safe to delete? | Effect |\n| ------------------------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| `agents/`, `skills/`, `hooks/` | Not recommended | You will lose your personal customizations. Back up first. |\n| `config.json` | With caution | Resets application state including authentication. You will need to re-authenticate and the CLI will re-detect internal state on next launch. |\n| `copilot-instructions.md`, `instructions/` | Not recommended | You will lose your personal custom instructions. Back up first. |\n| `extensions/` | Not recommended | You will lose your personal extensions. Back up first. |\n| `installed-plugins/` | Not recommended | Use `copilot plugin uninstall` instead, to ensure plugin metadata in `config.json` remains accurate. |\n| `logs/` | Yes | Log files are re-created each session. Deleting them has no functional impact. |\n| `lsp-config.json` | Not recommended | You will lose your user-level LSP server definitions. Back up first. |\n| `mcp-config.json` | Not recommended | You will lose your user-level MCP server definitions. Back up first. |\n| `mcp-oauth-config/` | With caution | Clears local MCP OAuth fallback state. You may need to re-authenticate MCP servers. |\n| `mcp-secrets/` | With caution | Clears local MCP secret fallback state and mappings. Secret-backed MCP servers may need reconfiguration. |\n| `permissions-config.json` | With caution | Resets all saved permissions. The CLI will prompt you again for tool and directory approvals. |\n| `plugin-data/` | Yes | Plugin persistent data is re-created as needed. |\n| `session-state/` | With caution | Deleting removes session history. You will no longer be able to resume past sessions. |\n| `command-history-state/` | With caution | Deleting removes command history. You will no longer be able to search previous commands with Ctrl+R. |\n| `session-store.db` | With caution | Deleting removes cross-session data. The file is re-created automatically. |\n| `settings.json` | With caution | Resets all user preferences to defaults. You will need to reconfigure your settings. |\n\n## Configuration file settings\n\nSettings are applied in this order (later overrides earlier):\n\n\n\n1. Built-in defaults\n2. Mobile Device Management (MDM) managed settings\n3. User settings (`~/.copilot/settings.json`)\n4. Repository settings (`.github/copilot/settings.json`)\n5. Local settings (`.github/copilot/settings.local.json`)\n6. Environment variables\n7. Command-line flags\n\n\n\nMDM managed settings load at startup and merge with user settings as a policy baseline. For most keys, user settings can override that baseline. For `permissions.disableBypassPermissionsMode`, an MDM value of `\"disable\"` always wins. For more information, see [MDM managed settings](#mdm-managed-settings).\n\n| Scope | Location | Purpose |\n| ---------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| User | `~/.copilot/settings.json` | Global defaults for all repositories. Use the `COPILOT_HOME` environment variable to specify an alternative path. |\n| Repository | `.github/copilot/settings.json` | Shared repository configuration (committed to the repository). |\n| Local | `.github/copilot/settings.local.json` | Personal overrides (add this to `.gitignore`). |\n\nThe CLI also reads `.claude/settings.json` and `.claude/settings.local.json` for the shared cross-tool subset of repository settings (such as `companyAnnouncements`, `disableAllHooks`, `enabledPlugins`, `extraKnownMarketplaces`, and `hooks`).\n\n### User settings (`~/.copilot/settings.json`)\n\nThese settings apply across all your sessions and repositories. You can use the `/settings` slash command to run an interactive dialog, or use specific slash commands to update individual values, or edit this file directly.\n\n| Key | Type | Default | Description | |\n| ---------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |\n| `allowedUrls` | `string[]` | `[]` | URLs or domains allowed without prompting. Supports exact URLs, domain patterns, and wildcard subdomains (for example, `\"*.github.com\"`). | |\n| `askUser` | `boolean` | `true` | Allow the agent to ask clarifying questions. Set to `false` for fully autonomous operation. Can also be set with `--no-ask-user`. | |\n| `autoUpdate` | `boolean` | `true` | Automatically download CLI updates and update first-party plugins at the start of each session. | |\n| `autoUpdatesChannel` | `\"stable\"` \\| `\"prerelease\"` | `\"stable\"` | Update channel. Set to `\"prerelease\"` to receive pre-release updates. | |\n| `banner` | `\"always\"` \\| `\"once\"` \\| `\"never\"` | `\"once\"` | Animated banner display frequency. | |\n| `bashEnv` | `boolean` | `false` | Enable `BASH_ENV` support for bash shells. Can also be set with `--bash-env` or `--no-bash-env`. | |\n| `beep` | `boolean` | `true` | Play an audible beep when attention is required. | |\n| `beepOnSchedule` | `boolean` | `true` | Play an audible beep when a scheduled `/every` or `/after` run finishes. | |\n| `builtInAgents.rubberDuck` | `boolean` | `true` | Enable the rubber-duck subagent that provides adversarial feedback on agent plans. | |\n| `builtInAgents.rubberDuckAutoInvoke` | `boolean` | `false` | Include proactive prompting for automatic rubber-duck invocation. Set to `true` to opt into additional rubber-duck nudges during agent turns. | |\n| `colorMode` | `\"default\"` \\| `\"github\"` \\| `\"dim\"` \\| `\"high-contrast\"` \\| `\"colorblind\"` | `\"github\"` | Deprecated alias for `theme`. Prefer `theme`. | |\n| `commandHistoryMaxSize` | `number` | `50` | Maximum number of recent commands retained for input history and reverse search. Must be an integer between `1` and `1000`. | |\n| `compactPaste` | `boolean` | `true` | Collapse large pastes (more than 10 lines) into compact tokens. | |\n| `companyAnnouncements` | `string[]` | `[]` | Custom messages shown randomly on startup. One message is randomly selected each time the CLI starts. Useful for team announcements or reminders. | |\n| `continueOnAutoMode` | `boolean` | `false` | Automatically switch to auto mode when rate-limited. When `true`, eligible rate limit errors trigger an automatic switch to auto mode and retry. Does not apply to global rate limits or BYOK providers. | |\n| `copyOnSelect` | `boolean` | `true` (macOS), `false` (other) | Automatically copy mouse-selected text to the system clipboard. | |\n| `customAgents.defaultLocalOnly` | `boolean` | `false` | Only use local custom agents (no remote organization or enterprise agents). | |\n| `deniedUrls` | `string[]` | `[]` | URLs or domains that are always denied. Denial rules take precedence over allow rules. | |\n| `disableAllHooks` | `boolean` | `false` | Disable all hooks (both repository-level and user-level). | |\n| `disabledMcpServers` | `string[]` | `[]` | MCP server names to disable. Listed servers are configured but not started. | |\n| `disabledSkills` | `string[]` | `[]` | Skill names to disable. Listed skills are discovered but not loaded. | |\n| `dynamicRetrieval` | `{ skills?: boolean }` | unset | Per-category control of embeddings-based dynamic instruction retrieval. Set `skills` to `false` to disable retrieval for skills. | |\n| `effortLevel` | `string` | `\"medium\"` | Reasoning effort level for extended thinking: `\"low\"`, `\"medium\"`, `\"high\"`, or `\"xhigh\"`. Higher levels use more compute. | |\n| `enabledMcpServers` | `string[]` | `[]` | Enable built-in MCP servers that are disabled by default. | |\n| `enabledPlugins` | `Record` | `{}` | Declarative plugin auto-install. Keys are plugin specs; values are `true` (enabled) or `false` (disabled). | |\n| `experimental` | `boolean` | `false` | Enable experimental features. Can also be enabled with the `--experimental` command-line option or the `/experimental` slash command. | |\n| `extraKnownMarketplaces` | `Record` | `{}` | Additional plugin marketplaces. Each key is a marketplace name; the value specifies the required `source` (`\"directory\"`, `\"git\"`, or `\"github\"`). Set `autoUpdate: true` on an entry to opt that marketplace's installed plugins into session-start auto-update, the same as first-party plugins. This opt-in applies only to interactive and `-p` sessions—SDK and server sessions don't auto-update. The opt-in is honored when set in your own user settings, or in managed (MDM/server) settings. On a same-name collision, a built-in first-party marketplace wins, then a managed entry (which replaces the whole same-named user entry, so a managed entry without `\"autoUpdate\": true` removes the user's opt-in), then the user's own entry. | |\n| `footer` | `object` | — | Controls which items appear in the status line. Sub-keys include `showModelEffort`, `showDirectory`, `showBranch`, `showContextWindow`, `showQuota`, `showAgent`, `showAiUsed`, `showCodeChanges`, `showUsername`, `showSandbox`, `showYolo`, and `showCustom` (all `boolean`). Managed by the `/statusline` slash command. | |\n| `hooks` | `object` | — | Inline user-level hook definitions, keyed by event name. Uses the same schema as `.github/hooks/*.json` files. See [Using hooks with GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/use-hooks). | |\n| `ide.autoConnect` | `boolean` | `true` | Automatically connect to an IDE workspace on startup. When `false`, you can still connect manually using the `/ide` command. | |\n| `ide.openDiffOnEdit` | `boolean` | `true` | Open file edit diffs in the connected IDE for approval. When `false`, file edit approvals are shown only in the terminal. | |\n| `includeCoAuthoredBy` | `boolean` | `true` | Add a `Co-authored-by` trailer to git commits made by the agent. | |\n| `keepAlive` | `\"on\"` \\| `\"off\"` \\| `\"busy\"` | `\"off\"` | Keep-alive mode applied at CLI startup. `\"on\"` always prevents the system from sleeping, `\"busy\"` prevents sleeping only while the agent is running, and `\"off\"` disables keep-alive. Also configurable with the `/keep-alive` slash command. | |\n| `logLevel` | `\"none\"` \\| `\"error\"` \\| `\"warning\"` \\| `\"info\"` \\| `\"debug\"` \\| `\"all\"` \\| `\"default\"` | `\"default\"` | Logging verbosity. | |\n| `mergeStrategy` | `\"rebase\"` \\| `\"merge\"` | — | Conflict resolution strategy for `/pr fix conflicts`. When set to `\"rebase\"`, conflicts are resolved by rebasing onto the base branch. When set to `\"merge\"`, the base branch is merged into the feature branch. If not configured, a picker dialog is shown. | |\n| `model` | `string` | varies | AI model to use. Set to `\"auto\"` to let Copilot pick the best available model automatically. Managed by the `/model` slash command. | |\n| `mouse` | `boolean` | `true` | Enable mouse support. Can also be set with `--mouse` or `--no-mouse`. | |\n| `permissions.disableBypassPermissionsMode` | `string` | — | Set to `\"disable\"` to suppress all allow-all flags (`--allow-all-tools`, `--allow-all-paths`, `--allow-all-urls`, `--allow-all`, `--yolo`) at startup so they cannot be used to grant elevated permissions. Set to `\"allow-auto-only\"` to keep blocking full allow-all while still permitting `/allow-all auto` (LLM-assisted auto-approval). See [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference#restricting-the---allow-all-options). | |\n| `pinnedPrompts` | `boolean` | `true` | Pin the current section's user prompt just below the top bar while scrolling the timeline, so it stays clear which request the visible output belongs to. CLI UI only—has no effect on prompts sent to the model. | |\n| `powershellFlags` | `string[]` | `[\"-NoProfile\", \"-NoLogo\"]` | Flags passed to PowerShell on startup. On Windows, the CLI prefers PowerShell 7+ (`pwsh`) and falls back to Windows PowerShell (`powershell.exe`) when `pwsh` is unavailable. Windows only. | |\n| `proxyKerberosServicePrincipal` | `string` | unset | Service principal name (SPN) for Kerberos/Negotiate proxy authentication, overriding the derived `HTTP/`. | |\n| `proxyUrl` | `string` | unset | Proxy URL for HTTP(S) requests (for example, `http://proxy.corp.example:3128`). Overridden by the `HTTP_PROXY` or `HTTPS_PROXY` environment variables (any casing). | |\n| `remote` | `\"on\"` \\| `\"off\"` | `\"on\"` | Controls session syncing and remote access. Set to `\"off\"` to keep session data local only and disable remote control. Can also be set with `--remote` or `--no-remote`. | |\n| `renderHexColors` | `boolean` | `true` | Show six-digit hex color codes written as inline code (for example, `` `#FF0000` ``) as color swatches. | |\n| `renderMarkdown` | `boolean` | `true` | Render Markdown in terminal output. | |\n| `remoteExport` | `boolean` | `true` | Export sessions remotely when session sync is available. Set to `false` to opt out of remote export by default. The `remoteSessions` setting when set to `true`, or the `--remote` flag, still enables export and steering regardless of this setting. | |\n| `respectGitignore` | `boolean` | `true` | Exclude gitignored files from the `@` file mention picker. When `false`, the picker includes files normally excluded by `.gitignore`. | |\n| `sandbox.allowBypass` | `boolean` | `true` | Allow sandboxed commands to request a bypass for specific operations (surfaces a permission prompt) so tools like `grep` and `glob` keep working when the sandbox would otherwise block them. Set to `false` to opt out. | |\n| `sandbox.enabled` | `boolean` | `false` | Restrict shell commands, MCP/LSP servers, and built-in file/web tools to a sandboxed environment with limited file system and network access. Enable it from the `/sandbox` dialog or with `/sandbox enable`. | |\n| `sandbox.failIfUnavailable` | `boolean` | `false` | Make sandboxing mandatory instead of falling back to unsandboxed execution: blocks model and tool execution if the policy can't be validated, compiled, or enforced by a usable sandbox backend. Typically set by a managed policy alongside `sandbox.enabled: true`; when set that way, you can't disable it. | |\n| `sandbox.auth.git` | `boolean` | `true` | Inject Git credentials into the sandbox so commands running inside it can authenticate with Git. Set to `false` to opt out. Renamed from `sandbox.gitAuth`; the old key has no migration and is ignored wherever it still appears. | |\n| `sandbox.auth.gh` | `boolean` | `true` | Inject GitHub CLI (`gh`) credentials into the sandbox so commands running inside it can authenticate with the GitHub CLI. Set to `false` to opt out. Renamed from `sandbox.ghAuth`; the old key has no migration and is ignored wherever it still appears. | |\n| `sandbox.userPolicy.network.allowLocalNetwork` | `boolean` | `true` | Allow sandboxed commands to reach local network addresses (for example, local dev servers). Set to `false` to opt out. | |\n| `sandbox.userPolicy.network.proxy` | `object` | unset | Route sandboxed network traffic through an HTTP proxy. Fields: `url` (required), `username` (optional), `password` (optional). Configure it from the `/sandbox` dialog's **Network** tab, which masks the password field. The password itself is stored in the OS keychain rather than in `settings.json`, so it isn't editable via `/settings`. On Linux and macOS the proxy is cooperative (not strictly enforced); Windows enforces it. | |\n| `sandbox.userPolicy.deniedPaths` | `string[]` | `[]` | Paths that sandboxed commands are denied access to. On Windows, the ProcessContainer sandbox backend cannot enforce per-path deny rules, so entries have no effect—therefore don't rely on `deniedPaths` to protect a sensitive directory on Windows. | |\n| `sandbox.userPolicy.seatbelt.keychainAccess` | `boolean` | `false` | macOS only. Grant sandboxed commands access to the system keychain. Can also be toggled from the `/sandbox` dialog. | |\n| `screenReader` | `boolean` | `false` | Enable screen reader optimizations. | |\n| `scrollbar` | `boolean` | `true` | Show the scrollbar in scrollable views. Set to `false` to hide it and use the full terminal width. | |\n| `shellShortcut` | `boolean` | `true` | Let a lone `$` at the prompt, followed by Enter, open an interactive shell rooted at the session's working directory (activates only for a local, trusted, idle session on a real TTY). User- or managed-scoped only—not repo-overridable. | |\n| `showTimestamps` | `boolean` | `true` | Show dim `HH:mm` timestamps next to user messages in the timeline. | |\n| `showTipsOnStartup` | `boolean` | `true` | Show a random command tip when the CLI starts. | |\n| `skillDirectories` | `string[]` | `[]` | Additional directories to search for custom skill definitions (in addition to `~/.copilot/skills/`). | |\n| `statusLine` | `object` | — | Custom status line display. `type`: must be `\"command\"`. `command`: path to an executable script that receives session JSON on stdin and prints status content to stdout. `padding`: optional number of left-padding spaces. `refreshInterval`: optional integer number of seconds (`1`–`2147483`) to re-run the command on a timer instead of only on events; omit it to refresh only when the session state changes. If the command fails to spawn, exits non-zero, or fails to receive the status JSON on stdin, the CLI logs a warning once per continuous failure episode and leaves the status line blank instead of failing silently. Run with `--log-level all` to see the underlying error detail. | |\n| `stayInAutopilot` | `boolean` | `true` | Remain in autopilot mode after each task completes. When enabled, the next prompt you enter after a task completes is also handled in autopilot mode. For more information, see [Allowing GitHub Copilot CLI to work autonomously](/en/copilot/concepts/agents/copilot-cli/autopilot#staying-in-autopilot-mode-between-tasks). | |\n| `storeTokenPlaintext` | `boolean` | `false` | Allow authentication tokens to be stored in plain text in `config.json` when no system keychain is available. | |\n| `stream` | `boolean` | `true` | Enable streaming responses. | |\n| `streamerMode` | `boolean` | `false` | Hide preview model names, quota details, prompt timestamps, and the update-available notice. Useful when demonstrating Copilot CLI or screen sharing. | |\n| `subagents.agents` | `object` | `{}` | Per-agent model configuration, keyed by agent name. Each value is an object with optional `model` (string), `effortLevel` (string), and `contextTier` (`\"default\"`, `\"long_context\"`, or `\"inherit\"`) fields. Set any field to `\"inherit\"` to use the parent session's value at dispatch time. Use the `/subagents` slash command to configure these settings interactively. | |\n| `subagents.disabledSubagents` | `string[]` | `[]` | Agent names to prevent from being dispatched. Only the `rubber-duck` agent cannot be disabled via this setting. All other built-in agents—including `explore`, `task`, `code-review`, `general-purpose`, `research`, and `security-review`—can be disabled. | |\n| `subagents.maxConcurrency` | `number` | plan-based | Maximum concurrent subagents for this session. Only honored for usage-based billing users; ignored for all other plans. Capped at `32`. See [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference#subagent-limits). | |\n| `subagents.maxDepth` | `number` | `6` | Maximum subagent nesting depth. Only honored for usage-based billing users; ignored for all other plans. Capped at `256`. See [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference#subagent-limits). | |\n| `tabs.enabled` | `boolean` | `true` | Show the home tab bar. Set to `false` to hide it entirely. | |\n| `tabs.hide` | `string[]` | `[]` | Tab identifiers to hide. Accepted values: `\"copilot\"`, `\"agents\"`, `\"issues\"`, `\"pull-requests\"`, `\"gists\"` (matched case-insensitively). | |\n| `tabs.sort` | `string[]` | `[]` | Order in which tabs are displayed. Tabs not listed keep their default relative order after the listed ones. Unknown identifiers are ignored. | |\n| `terminalProgress` | `boolean` | `true` | Emit OSC 9;4 terminal progress indicators while the agent is working. Supported terminals include Windows Terminal, iTerm2, Ghostty, and ConEmu. | |\n| `theme` | `\"default\"` \\| `\"github\"` \\| `\"dim\"` \\| `\"high-contrast\"` \\| `\"colorblind\"` | `\"github\"` | Color palette for terminal output. Managed by the `/settings` and `/theme` slash commands. `colorMode` is a deprecated alias for this setting. | |\n| `toolSearch` | `boolean` | model- and feature-dependent | Controls tool search (deferred tool loading). Set `toolSearch: false` to opt out of tool search. | |\n| `updateTerminalTitle` | `boolean` | `true` | Show the current intent in the terminal tab or window title. | |\n| `worktreeBaseRef` | `\"head\"` \\| `\"defaultBranch\"` | `\"head\"` | Starting point for new worktrees created by `/worktree`, `/worktree new`, and `--worktree`. `\"defaultBranch\"` starts from the remote default branch instead of the current checkout. | |\n\n> \\[!TIP]\n> Run `copilot help sandbox` for the full sandbox reference, including supported hosts and all `sandbox` settings keys.\n\n#### Proxy client certificates (mTLS)\n\nWhen a request routed through an `https://` proxy (set with `proxyUrl`, `HTTPS_PROXY`, or `HTTP_PROXY`) requests a client certificate, Copilot CLI automatically selects an OS-managed client identity. You don't need to configure a certificate path, private key, or passphrase. Private keys never leave the platform store.\n\n| Platform | Identity source |\n| -------------------------------- | ----------------------------------------------------------------------------- |\n| Windows | Current user's `MY` certificate store. |\n| macOS | User keychain search list, including a preferred identity for the proxy host. |\n| Linux (glibc) | Chromium-compatible NSS database and its configured PKCS#11 modules. |\n| Linux (musl) and other platforms | Unsupported. Ordinary proxy behavior is unchanged. |\n\nClient identity selection only activates for `https://` proxies. Direct requests, `NO_PROXY` matches, and plaintext `http://` proxies never install a client identity. The platform store is re-read on every request, so certificate rotation or smart-card insertion doesn't require a session restart.\n\nThe `/sandbox` dialog groups `git`, `gh`, and keychain access under a dedicated **Auth** tab, and shows the `settings.json` path where the current sandbox configuration is stored. Press Ctrl+E in the `/sandbox` dialog to save any pending changes and open `settings.json` in your editor (`COPILOT_EDITOR`, `VISUAL`, or `EDITOR`), matching the same shortcut in `/settings`. The dialog reloads its state from disk after you edit and save the file.\n\nSandboxing is powered by [Microsoft eXecution Container (MXC)](https://github.com/microsoft/mxc), which provides platform-specific containment backends. Copilot CLI uses Seatbelt on macOS, Bubblewrap on Linux, and ProcessContainer on Windows.\n\n### Repository settings (`.github/copilot/settings.json`)\n\nRepository settings apply to everyone who works in the repository. They are committed to the repository and shared with collaborators.\n\n> \\[!NOTE]\n> The plugin-related keys in the repository configuration file (`enabledPlugins` and `extraKnownMarketplaces`) are also read by Copilot cloud agent, not only Copilot CLI. This lets you enable the same plugins for both clients from a single file. For more information about plugins, see [About GitHub Copilot plugins](/en/copilot/concepts/agents/about-plugins).\n\nOnly the keys listed in the following table are supported at the repository level. Any other keys—including keys that are valid in the user configuration file—are silently ignored. Each supported key has a directional merge policy that keeps the override fail-closed and safe.\n\n| Key | Type | Merge behavior | Description |\n| ------------------------ | ------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `companyAnnouncements` | `string[]` | Replaced—repository takes precedence | Messages shown randomly on startup. |\n| `contextTier` | `\"default\"` \\| `\"long_context\"` | Replaced—repository takes precedence | Pin the default context tier. |\n| `deniedUrls` | `string[]` | Union—repository can add entries, never remove | URLs or domains blocked. |\n| `disableAllHooks` | `boolean` | Repository takes precedence | Disable all hooks. |\n| `disabledMcpServers` | `string[]` | Union—repository can add entries, never remove | MCP servers configured but not started. |\n| `disabledSkills` | `string[]` | Union—repository can add entries, never remove | Skills discovered but not loaded. |\n| `effortLevel` | `string` | Replaced—repository takes precedence | Pin the default reasoning effort. |\n| `enabledPlugins` | `Record` | Merged—repository overrides user for same key | Declarative plugin auto-install. |\n| `extraKnownMarketplaces` | `Record` | Merged—repository overrides user for same key | Plugin marketplaces available in this repository. Each entry's `source` is required. An `autoUpdate: true` on an entry is accepted at the repository level but currently ignored—the auto-update opt-in is only honored when set in the user's own settings or in managed (MDM/server) settings. |\n| `hooks` | `object` | Merged—repository overrides user for same key | Hook definitions scoped to this repository. See [Using hooks with GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/use-hooks). |\n| `includeCoAuthoredBy` | `boolean` | Replaced—repository takes precedence | Add a `Co-authored-by` trailer to commits. |\n| `mergeStrategy` | `\"rebase\"` \\| `\"merge\"` | Replaced—repository takes precedence | Conflict resolution strategy for `/pr fix conflicts`. |\n| `model` | `string` | Replaced—repository takes precedence | Pin the default model for this repo. |\n| `respectGitignore` | `boolean` | Tighten-only—repository can enable, never disable | Exclude gitignored files from the `@` file mention picker. |\n\n`model`, `effortLevel`, and `contextTier` overrides only apply when the working directory is [trusted](/en/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools).\n\nA plugin enabled only through a repository's `enabledPlugins` is scoped to that repository: it auto-installs and activates in the declaring repository, but stays disabled globally, so it never activates in unrelated projects. Leaving the repository, or the repository disabling the plugin, tears down its MCP server and deactivates its agents and skills for the session.\n\n### Repository-level models allowlist (`.github/allowed_models.txt`)\n\nRestrict which built-in models a repository can use with a plain-text allowlist at `.github/allowed_models.txt`, resolved from the current working directory's repository root (or the working directory itself outside a repository).\n\nEach line is a glob pattern matched against model IDs, or a `fallback:` directive naming the model to use when the configured or requested model isn't allowed:\n\n```text\n# .github/allowed_models.txt\nfallback: gpt-5.2\ngpt-5.2\ngpt-5.4\nclaude-sonnet-*\n```\n\n| Rule | Description |\n| -------------------- | ---------------------------------------------------------------------------------- |\n| `*` | Allow all models (default when no file is present). |\n| `MODEL-ID` | Allow an exact model ID. |\n| `GLOB-PATTERN` | Allow model IDs matching the glob (for example, `claude-sonnet-*`). |\n| `fallback: MODEL-ID` | Required exactly once. The model Copilot uses when the active model isn't allowed. |\n| `#` | Comment line. |\n\nNegated patterns (`!pattern`) aren't supported, the fallback model must be an exact ID (not a glob), and the fallback model must itself match one of the configured globs. Copilot CLI re-evaluates the policy on `/cd` and rejects an invalid file with an error before running.\n\nThe allowlist governs only Copilot's built-in models. It cannot filter out custom models added using the bring your own API keys (BYOK) method. BYOK models remain listed and selectable regardless of the patterns you configure, and the `fallback:` directive never applies to them. For more information, see [Enabling custom models for GitHub Copilot in your enterprise](/en/copilot/how-tos/administer-copilot/manage-for-enterprise/enable-custom-models) and [Enabling custom models for GitHub Copilot in your organization](/en/copilot/how-tos/administer-copilot/manage-for-organization/enable-custom-models).\n\n### Local settings (`.github/copilot/settings.local.json`)\n\nCreate `.github/copilot/settings.local.json` in the repository for personal overrides that should not be committed. Add this file to `.gitignore`.\n\nThe local configuration file uses the same schema as the repository configuration file (`.github/copilot/settings.json`) and takes precedence over it.\n\n## MDM managed settings\n\nIT administrators can push baseline policy using Mobile Device Management (MDM) managed settings instead of requiring per-user configuration. These settings apply device-level defaults for supported keys and load before user settings.\n\nCopilot CLI also loads server-managed settings at startup, in addition to MDM. Device-managed (MDM) and server-managed settings are resolved **per key**: MDM's value wins for any key it sets, and the server's value fills in keys MDM leaves unset. This lets an organization set some policy via MDM (for example, `permissions`) while still receiving other managed defaults (for example, `model`) from the server.\n\nLong-running sessions re-fetch and re-apply managed settings hourly, so policy changes—for example, an organization enabling `permissions.disableBypassPermissionsMode`—take effect without restarting the session.\n\n### MDM managed settings sources\n\nCopilot CLI reads managed settings from platform-specific MDM or file-based locations.\n\n| Platform | Source type | Location |\n| -------- | ------------ | ------------------------------------------------------------------ |\n| macOS | MDM plist | `com.github.copilot` |\n| macOS | File | `/Library/Application Support/GitHubCopilot/managed-settings.json` |\n| Windows | MDM registry | `HKLM\\SOFTWARE\\Policies\\GitHubCopilot` |\n| Windows | File | `%ProgramFiles%\\GitHubCopilot\\managed-settings.json` |\n| Linux | File | `/etc/github-copilot/managed-settings.json` |\n\n> \\[!NOTE]\n> On POSIX systems, Copilot CLI rejects file-based managed settings that are symlinks, not owned by root, or world-writable.\n\n### File format\n\nWrite file-based managed settings as JSON.\n\n```json\n{\n \"model\": \"auto\",\n \"permissions\": {\n \"disableBypassPermissionsMode\": \"disable\"\n }\n}\n```\n\n> \\[!NOTE]\n> `model` is a top-level key. Older configurations that nested it as `permissions.model` still work—the runtime falls back to that location when the top-level `model` key is absent—but write new configurations with `model` at the top level.\n\n### Supported keys\n\nOnly the following keys are supported in MDM managed settings.\n\n| Key | Description |\n| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `allowedMcpServers` | Allowlist of MCP servers users may load, matched by `serverUrl`, `serverCommand`, or `serverName`. Trusted first-party servers (for example, the built-in GitHub MCP server) are always exempt. Leaving this key unset allows all non-default servers; an empty array denies all of them. See [Managed MCP server allow/deny list](#managed-mcp-server-allowdeny-list). |\n| `deniedMcpServers` | Denylist of MCP servers that must never load, matched the same way as `allowedMcpServers`. A matching non-default server is blocked regardless of the allowlist—deny always wins. See [Managed MCP server allow/deny list](#managed-mcp-server-allowdeny-list). |\n| `enabledPlugins` | Enable or disable specific plugins |\n| `extraKnownMarketplaces` | Add trusted plugin marketplaces |\n| `forceRemoteSettingsRefresh` | Require a fresh server-managed settings fetch on startup, even when a fresh cached policy exists. The cached entry is still kept as a fallback if the fetch fails. The device (MDM) value takes precedence over a cached server value. |\n| `model` | Set a default model for all users (overridden by the `--model` flag or a resumed-session model) |\n| `permissions` | Set managed permissions, including `disableBypassPermissionsMode` and `deny` / `ask` / `allow` rule arrays. See [Managed permission rules](#managed-permission-rules). |\n| `policyHelper` | Register an executable that supplies the lowest-priority managed-settings layer. Fields: `path` (required), plus optional `args`, `timeoutMs`, and `refreshIntervalMs`. If both a device (MDM) and a server policy register a `policyHelper`, the device registration wins. |\n| `remoteControl` | Control whether sessions on this device can be controlled from other devices. `mode` is `\"enabled\"`, `\"disabled\"`, or `\"requireSSO\"` (requires `githubDotComOrganizations` when set). |\n| `shellShortcut` | Force-enable or force-disable the `$` interactive shell shortcut for all users. A managed value always overrides the user's own `shellShortcut` setting. |\n| `strictKnownMarketplaces` | Restrict plugins to known marketplaces |\n| `strictPluginOnlyCustomization` | Customization lockdown baseline. Prevents standalone user and workspace/project customizations from the named surfaces, so eligible customizations may then originate only from plugins or managed settings. `true` locks all four surfaces (`skills`, `agents`, `hooks`, MCP servers); an array (for example, `[\"skills\", \"mcp\"]`) locks only the named surfaces. Unset preserves existing behavior. This does **not** mean managed-plugin-only—plugin-provided customizations are still permitted. Use `allowManagedMcpServersOnly` and `allowManagedHooksOnly` for the stricter managed-only overlays described below. |\n| `allowManagedMcpServersOnly` | A stricter overlay on top of `strictPluginOnlyCustomization`. When `true`, only the managed `allowedMcpServers` allowlist (plus MCP servers from managed or force-enabled plugins, and any fixed managed-MCP deployment) governs which MCP servers are eligible. Lower-precedence user and workspace/project allowlist entries can't broaden it; `deniedMcpServers` still applies. Trusted first-party servers (for example, the built-in GitHub MCP server) remain exempt. See [Managed MCP server allow/deny list](#managed-mcp-server-allowdeny-list). |\n| `allowManagedHooksOnly` | A stricter overlay on top of `strictPluginOnlyCustomization`. When `true`, only enterprise-managed hooks and hooks supplied by plugins force-enabled through managed `enabledPlugins` may load; user, workspace/project, and otherwise user-enabled plugin hooks are blocked. Normal managed permission and sandbox policies still apply. |\n| `telemetry` | Push baseline OpenTelemetry export configuration: `enabled`, `endpoint`, `protocol`, `headers`, `resourceAttributes`, `captureContent`, `lockCaptureContent`, and `serviceName`. See [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference#opentelemetry-monitoring). |\n\n> \\[!NOTE]\n> `policyHelper.path` accepts an absolute path, a home-relative path (`~/...`), or a bare program name resolved from `PATH`. Other relative forms are rejected. The registration is accepted and validated, but the runtime doesn't yet invoke the helper—helper execution ships in a future release.\n\n> \\[!NOTE]\n> When `remoteControl.mode` is `\"requireSSO\"`, list the allowed organizations in `remoteControl.githubDotComOrganizations`. The client must be SSO-authorized for at least one listed GitHub.com organization—it no longer needs to be authorized for all of them.\n\n> \\[!NOTE]\n> Set `permissions.disableBypassPermissionsMode` to `\"disable\"` in MDM managed settings to enforce the restriction at the device level. Account switches cannot override this policy. Set it to `\"allow-auto-only\"` to block full allow-all escalation while still permitting `/permissions assisted` (LLM-assisted permission approval). If an unrecognized value is set, the CLI logs the issue and enforces `\"disable\"` as a fail-closed default, so a malformed managed policy still restricts the allow-all options instead of silently allowing them. See [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference#restricting-the---allow-all-options).\n\n> \\[!NOTE]\n> Most managed keys lock the entire row: a local edit is silently overridden by the managed value on the next load. `enabledPlugins` and `extraKnownMarketplaces` are the exception—the managed layer merges these maps with your own entries field-by-field instead of replacing them outright. This means the lock applies **per entry**, not to the whole key: a plugin or marketplace pinned by a managed policy can't be re-enabled, disabled, or repointed locally, but other entries in the same map remain fully user-controlled.\n\n> \\[!NOTE]\n> `strictPluginOnlyCustomization`, `allowManagedMcpServersOnly`, and `allowManagedHooksOnly` compose across managed sources with a most-restrictive-wins strategy: a surface locked, or an overlay set to `true`, by any managed source stays locked or `true` even if a lower-priority managed source leaves it unset.\n\n### Managed permission rules\n\nPush `deny`, `ask`, and `allow` rule lists under the managed `permissions` key to enforce a permission policy across all users, independent of `permissions.disableBypassPermissionsMode`.\n\n```json\n{\n \"permissions\": {\n \"deny\": [\"Shell(rm -rf *)\", \"Domain(*.evil.example)\"],\n \"ask\": [\"Shell(git push *)\"],\n \"allow\": [\"Read(**)\"]\n }\n}\n```\n\n| Rule family | Matches |\n| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `Bash(...)`, `Shell(...)` | Shell commands. Use ` *` (for example, `git push *`) to match a command prefix; otherwise the rule matches exact text. |\n| `PowerShell(...)` | PowerShell commands, matched the same way as `Shell(...)`. |\n| `Read(...)` | File read/view paths. Supports glob patterns: `/` for the workspace root, `~/` for the home directory, and `./` for the current working directory. |\n| `Edit(...)`, `Write(...)` | File write/edit paths, matched the same way as `Read(...)`. |\n| `Domain(...)` | URL hostnames, matched like [URL rules](/en/copilot/reference/copilot-cli-reference/cli-command-reference#tool-permission-patterns). |\n\nRules are combined across managed sources with a fixed precedence: deny always wins, then ask, then allow—matching a `deny` rule blocks the request even if an `allow` rule also matches. `deny` and `ask` are unioned across every managed source (server, MDM). `allow` requires every source that declares an `allow` list to admit the operation—an intersection, not a union. When any of `deny`, `ask`, or `allow` is set, an operation that matches none of them defaults to `ask` rather than falling through silently.\n\n## Managed MCP server allow/deny list\n\nAdministrators can govern MCP servers directly through MDM managed settings, independent of the [enterprise MCP allowlist](/en/copilot/reference/copilot-cli-reference/cli-command-reference#enterprise-mcp-allowlist).\n\nSet `allowedMcpServers` and/or `deniedMcpServers` in a managed settings source:\n\n```json\n{\n \"allowedMcpServers\": [\n { \"serverUrl\": \"https://mcp.example.com/*\" },\n { \"serverCommand\": [\"npx\", \"-y\", \"@example/mcp-server\"] }\n ],\n \"deniedMcpServers\": [\n { \"serverName\": \"untrusted-server\" }\n ]\n}\n```\n\nEach entry identifies a server by exactly one of the following matchers.\n\n| Matcher | Matches | Notes |\n| --------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |\n| `serverUrl` | A remote (HTTP/SSE) server by URL | Supports `*` wildcards; scheme and host match case-insensitively, path case-sensitively. `${VAR}` references expand before matching. |\n| `serverCommand` | A stdio server by its exact command and arguments, in order | `${VAR}` references expand before matching. |\n| `serverName` | A server by its assigned label | Allowlist entries are restricted to `[A-Za-z0-9_-]+` (no wildcards); denylist entries accept any non-empty string. |\n\nRules:\n\n* **Trusted first-party servers** (for example, the built-in GitHub MCP server) are always exempt from both lists.\n* **Unset `allowedMcpServers`** allows all non-default servers; an **empty array** blocks all of them (deny-all).\n* **Unset or empty `deniedMcpServers`** blocks nothing.\n* **Deny always wins**—a server matching `deniedMcpServers` is blocked even if it also matches `allowedMcpServers`.\n* For remote servers, a match must come from a `serverUrl` entry; `serverName` only counts when no `serverUrl` entries exist. For stdio servers, a match must come from a `serverCommand` entry; `serverName` only counts when no `serverCommand` entries exist.\n\nSet the managed `allowManagedMcpServersOnly` key to `true` for a stricter overlay: only the managed `allowedMcpServers` allowlist (plus MCP servers from managed or force-enabled plugins, and any fixed managed-MCP deployment) governs which servers are eligible, and lower-precedence user or workspace/project allowlist entries can no longer broaden it. `deniedMcpServers` still applies, and trusted first-party servers remain exempt.\n\n## Further reading\n\n* [GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli)\n* [GitHub Copilot CLI command reference](/en/copilot/reference/copilot-cli-reference/cli-command-reference)\n* [GitHub Copilot CLI programmatic reference](/en/copilot/reference/copilot-cli-reference/cli-programmatic-reference)\n* [GitHub Copilot CLI plugin reference](/en/copilot/reference/copilot-cli-reference/cli-plugin-reference)\n* [GitHub Copilot hooks reference](/en/copilot/reference/hooks-reference)"}