|
| 1 | +--- |
| 2 | +title: Configure GitHub Copilot CLI |
| 3 | +shortTitle: Configure Copilot CLI |
| 4 | +intro: Configure trusted directories, tool access, and path and URL permissions for {% data variables.copilot.copilot_cli_short %} |
| 5 | +versions: |
| 6 | + feature: copilot |
| 7 | +topics: |
| 8 | + - Copilot |
| 9 | + - CLI |
| 10 | +contentType: how-tos |
| 11 | +category: |
| 12 | + - Configure Copilot |
| 13 | +--- |
| 14 | + |
| 15 | +{% data reusables.cli.preview-note-cli %} |
| 16 | + |
| 17 | +## Introduction |
| 18 | + |
| 19 | +{% data variables.copilot.copilot_cli_short %} has several configuration options that control what it can access and do on your behalf. |
| 20 | + |
| 21 | +This article shows you how to set trusted directories, configure access for tools, and grant permissions to file paths and URLs. |
| 22 | + |
| 23 | +### Prerequisites |
| 24 | + |
| 25 | +* Install the {% data variables.copilot.copilot_cli_short %}. See [AUTOTITLE](/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli). |
| 26 | + |
| 27 | +## Setting trusted directories |
| 28 | + |
| 29 | +Trusted directories control where {% data variables.copilot.copilot_cli_short %} can read, modify, and execute files. Trusting a directory has security implications, see [Security considerations](/copilot/concepts/agents/about-copilot-cli#trusted-directories). |
| 30 | + |
| 31 | +### Choosing to trust a directory |
| 32 | + |
| 33 | +When you start a {% data variables.copilot.copilot_cli %} session, you'll be asked to confirm that you trust the files in, and below, the directory from which you launched the CLI. |
| 34 | + |
| 35 | +You can choose to trust the current directory for: |
| 36 | + |
| 37 | +* The currently running session only |
| 38 | +* This and future sessions |
| 39 | + |
| 40 | +If you choose to trust the directory for future sessions, the trusted directory prompt will not be displayed again. You should only choose this second option if you are sure that this location will always be a safe place for {% data variables.product.prodname_copilot_short %} to operate. |
| 41 | + |
| 42 | +### Editing trusted directories |
| 43 | + |
| 44 | +You can edit the list of permanently trusted directories. |
| 45 | + |
| 46 | +1. Open the CLI’s `config.json` file. By default, it’s stored in a `.copilot` folder under your home directory: |
| 47 | + * **macOS/Linux**: `~/.copilot/config.json` |
| 48 | + * **Windows**: `$HOME\.copilot\config.json` |
| 49 | + |
| 50 | + You can change the config location by setting the `XDG_CONFIG_HOME` environment variable (primarily on macOS/Linux). |
| 51 | +1. Edit the contents of the `trusted_folders` array. |
| 52 | + |
| 53 | +## Setting allowed tools |
| 54 | + |
| 55 | +You can control which tools {% data variables.copilot.copilot_cli_short %} can use, either by responding to approval prompts when {% data variables.product.prodname_copilot_short %} attempts to use a tool, or by specifying permissions via command-line flags. |
| 56 | + |
| 57 | +Be aware that allowing tool access has security implications, see [Security considerations](/copilot/concepts/agents/about-copilot-cli#allowed-tools). |
| 58 | + |
| 59 | +In this section, you can learn how to: |
| 60 | + |
| 61 | +* [Allow a tool for the first time](#allowing-a-tool-for-the-first-time) |
| 62 | +* [Allow tools to be used without manual approval](#allowing-tools-to-be-used-without-manual-approval) |
| 63 | +* [Specify which tool you want to allow or deny](#specifying-which-tool-you-want-to-allow-or-deny) |
| 64 | +* [Allow some tools while denying others](#allowing-some-tools-while-denying-others) |
| 65 | +* [Limit available tools](#limiting-available-tools) |
| 66 | + |
| 67 | +### Allowing a tool for the first time |
| 68 | + |
| 69 | +The first time that {% data variables.product.prodname_copilot_short %} needs to use a tool that may require approval—for example, {% data reusables.cli.tools-needing-approval %}—it will ask you whether you want to allow it to run. Whether you’re prompted can depend on the tool and how it’s being used (such as the arguments provided or whether the tool has been previously approved). |
| 70 | + |
| 71 | +1. Prompt {% data variables.product.prodname_copilot_short %} to perform a task that requires a tool. For example: |
| 72 | + |
| 73 | + ```shell |
| 74 | + copilot -p "Create a new file called README.md with a project description" |
| 75 | + ``` |
| 76 | + |
| 77 | +1. Choose from one of the three options: |
| 78 | + |
| 79 | + * `1. Yes` |
| 80 | + |
| 81 | + Choose this option to allow {% data variables.product.prodname_copilot_short %} to run this particular command, this time only. The next time it needs to use this tool, it will ask you again. |
| 82 | + |
| 83 | + * `2. Yes, and approve TOOL for the rest of the running session` |
| 84 | + |
| 85 | + Choose this option to allow {% data variables.product.prodname_copilot_short %} to use this tool for the duration of the currently running session. It will ask for your approval again in new sessions, or if you resume the current session in the future. If you choose this option, you are allowing {% data variables.product.prodname_copilot_short %} to use this tool in any way it thinks is appropriate. |
| 86 | + |
| 87 | + For example, if {% data variables.product.prodname_copilot_short %} asks you to allow it to run the command `rm ./this-file.txt`, and you choose option 2, then {% data variables.product.prodname_copilot_short %} can run any `rm` command (for example, `rm -rf ./*`) during the current run of this session, without asking for your approval. |
| 88 | + |
| 89 | + * `3. No, and tell Copilot what to do differently (Esc)` |
| 90 | + |
| 91 | + Choose this option to cancel the proposed command and instruct {% data variables.product.prodname_copilot_short %} to try a different approach. |
| 92 | + |
| 93 | +### Allowing tools to be used without manual approval |
| 94 | + |
| 95 | +You can use command-line flags to designate tools that {% data variables.product.prodname_copilot_short %} can use without asking for your approval. |
| 96 | + |
| 97 | +#### Allowing all tools |
| 98 | + |
| 99 | +Use the `--allow-all-tools` to allow {% data variables.product.prodname_copilot_short %} to use any tool without asking for your approval. |
| 100 | + |
| 101 | +* For example: |
| 102 | + |
| 103 | + ```shell |
| 104 | + copilot -p "Revert the last commit" --allow-all-tools |
| 105 | + ``` |
| 106 | + |
| 107 | +#### Denying a tool |
| 108 | + |
| 109 | +Use `--deny-tool` to prevent {% data variables.product.prodname_copilot_short %} from using a specific tool. |
| 110 | + |
| 111 | +* For example: |
| 112 | + |
| 113 | + ```shell |
| 114 | + copilot --deny-tool 'shell(git push)' |
| 115 | + ``` |
| 116 | + |
| 117 | +This option takes precedence over the `--allow-all-tools` and `--allow-tool` options. |
| 118 | + |
| 119 | +#### Allowing a tool |
| 120 | + |
| 121 | +Use `--allow-tool` to allow {% data variables.product.prodname_copilot_short %} to use a specific tool without asking for your approval. |
| 122 | + |
| 123 | +* For example: |
| 124 | + |
| 125 | + ```shell |
| 126 | + copilot --allow-tool 'shell' |
| 127 | + ``` |
| 128 | + |
| 129 | +### Specifying which tool you want to allow or deny |
| 130 | + |
| 131 | +To use the `--deny-tool` and `--allow-tool` options, you must specify what type of tool you want to allow or deny: |
| 132 | + |
| 133 | +* [Shell commands](#allowing-or-denying-shell-commands) |
| 134 | +* ['Write' tools](#allowing-or-denying-write-tools) |
| 135 | +* [MCP server tools](#allowing-or-denying-mcp-server-tools) |
| 136 | + |
| 137 | +#### Allowing or denying shell commands |
| 138 | + |
| 139 | +Use `shell(COMMAND)` to allow or deny a specific shell command. |
| 140 | + |
| 141 | +* For example, to prevent {% data variables.product.prodname_copilot_short %} from using any `rm` command, use: |
| 142 | + |
| 143 | + ```shell |
| 144 | + copilot --deny-tool 'shell(rm)' |
| 145 | + ``` |
| 146 | + |
| 147 | +For `git` and `gh` commands, specify a particular first-level subcommand to allow or deny. |
| 148 | + |
| 149 | +* For example, to prevent {% data variables.product.prodname_copilot_short %} from using `git push`, use: |
| 150 | + |
| 151 | + ```shell |
| 152 | + copilot --deny-tool 'shell(git push)' |
| 153 | + ``` |
| 154 | + |
| 155 | +The tool specification is optional. For example, `copilot --allow-tool 'shell'` allows {% data variables.product.prodname_copilot_short %} to use any shell command without individual approval. |
| 156 | + |
| 157 | +#### Allowing or denying `'write'` tools |
| 158 | + |
| 159 | +Use `'write'` to allow or deny tools—other than shell commands—permission to modify files. |
| 160 | + |
| 161 | +* For example, to allow {% data variables.product.prodname_copilot_short %} to edit files without your individual approval, use: |
| 162 | + |
| 163 | + ```shell |
| 164 | + copilot --allow-tool 'write' |
| 165 | + ``` |
| 166 | + |
| 167 | +#### Allowing or denying MCP server tools |
| 168 | + |
| 169 | +Use `'MCP_SERVER_NAME'` to allow or deny a specific tool from the specified MCP server. |
| 170 | + |
| 171 | +* For example, to prevent {% data variables.product.prodname_copilot_short %} from using the tool called `tool_name` from the MCP server called `My-MCP-Server`, use: |
| 172 | + |
| 173 | + ```shell |
| 174 | + copilot --deny-tool 'My-MCP-Server(tool_name)' |
| 175 | + ``` |
| 176 | + |
| 177 | +`MCP_SERVER_NAME` is the name of an MCP server that you have configured. |
| 178 | + |
| 179 | +Tools from the server are specified in parentheses, using the tool name that is registered with the MCP server. |
| 180 | + |
| 181 | +Using the server name without specifying a tool allows or denies all tools from that server. |
| 182 | + |
| 183 | +You can find an MCP server's name by entering `/mcp` in the interactive mode of {% data variables.copilot.copilot_cli_short %} and selecting the server from the list that's displayed. |
| 184 | + |
| 185 | +### Allowing some tools while denying others |
| 186 | + |
| 187 | +To determine exactly which tools {% data variables.product.prodname_copilot_short %} can use without asking for your approval, you can use a combination of approval options. For example: |
| 188 | + |
| 189 | +* To prevent {% data variables.product.prodname_copilot_short %} from using the `rm` and `git push` commands, but automatically allow all other tools, use: |
| 190 | + |
| 191 | + ```shell |
| 192 | + copilot --allow-all-tools --deny-tool 'shell(rm)' --deny-tool 'shell(git push)' |
| 193 | + ``` |
| 194 | + |
| 195 | +* To prevent {% data variables.product.prodname_copilot_short %} from using the tool `tool_name` from the MCP server named `My-MCP-Server`, but allow all other tools from that server to be used without individual approval, use: |
| 196 | + |
| 197 | + ```shell |
| 198 | + copilot --allow-tool 'My-MCP-Server' --deny-tool 'My-MCP-Server(tool_name)' |
| 199 | + ``` |
| 200 | + |
| 201 | +### Limiting available tools |
| 202 | + |
| 203 | +To restrict {% data variables.product.prodname_copilot_short %} to a specific set of tools, use `--available-tools`. |
| 204 | + |
| 205 | +Tools not included in this list will not be available to {% data variables.product.prodname_copilot_short %}. |
| 206 | + |
| 207 | +## Setting path permissions |
| 208 | + |
| 209 | +Path permissions control which directories and files {% data variables.product.prodname_copilot_short %} can access. |
| 210 | + |
| 211 | +By default, {% data variables.copilot.copilot_cli_short %} can access the current working directory, its subdirectories, and the system temp directory. |
| 212 | + |
| 213 | +Path permissions apply to shell commands, file operations (create, edit, view), and search tools (such as `grep` and glob patterns). For shell commands, paths are heuristically extracted by tokenizing command text and identifying tokens that look like paths. |
| 214 | + |
| 215 | +> [!WARNING] |
| 216 | +> Path detection for shell commands has limitations: |
| 217 | +> |
| 218 | +> * Paths embedded in complex shell constructs may not be detected. |
| 219 | +> * Only a specific set of environment variables are expanded (`HOME`, `TMPDIR`, `PWD`, and similar). Custom variables like `$MY_PROJECT_DIR` are not expanded and may not be validated correctly. |
| 220 | +> * Symlinks are resolved for existing files, but not for files being created. |
| 221 | +
|
| 222 | +### Allowing access to all paths |
| 223 | + |
| 224 | +To disable path verification and allow access to any path, use the `--allow-all-paths` flag when starting {% data variables.copilot.copilot_cli_short %}. |
| 225 | + |
| 226 | +### Disallowing access to the temp directory |
| 227 | + |
| 228 | +To disallow access to the temp directory, use `--disallow-temp-dir`. |
| 229 | + |
| 230 | +## Setting URL permissions |
| 231 | + |
| 232 | +URL permissions control which external URLs {% data variables.product.prodname_copilot_short %} can access. By default, all URLs require approval before access is granted. |
| 233 | + |
| 234 | +URL permissions apply to the `web_fetch` tool and a curated list of shell commands that access the network (such as `curl`, `wget`, and `fetch`). For shell commands, URLs are extracted using regex patterns. |
| 235 | + |
| 236 | +> [!WARNING] |
| 237 | +> URL detection for shell commands has limitations: |
| 238 | +> |
| 239 | +> * URLs in file contents, config files, or environment variables read by commands are not detected. |
| 240 | +> * Obfuscated URLs (such as split strings or escape sequences) may not be detected. |
| 241 | +> * HTTP and HTTPS are treated as different protocols and require separate approval. |
| 242 | +
|
| 243 | +URL permissions can be persisted for the session or permanently. |
| 244 | + |
| 245 | +### Disabling URL verification |
| 246 | + |
| 247 | +To disable URL verification, use the `--allow-all-urls` flag. |
| 248 | + |
| 249 | +### Pre-approving specific domains |
| 250 | + |
| 251 | +To pre-approve specific domains, use `--allow-url <domain>`. |
| 252 | + |
| 253 | +* For example, `--allow-url github.com`. |
| 254 | + |
| 255 | +### Denying specific domains |
| 256 | + |
| 257 | +To deny specific domains, use `--deny-url <domain>`. |
| 258 | + |
| 259 | +* For example, `--deny-url github.com`. |
| 260 | + |
| 261 | +## Allowing all tools, paths, and URLs |
| 262 | + |
| 263 | +To allow all tools, paths and URLs, use `--allow-all`, or its alias, `--yolo`. |
| 264 | + |
| 265 | +This flag combines: |
| 266 | +* `--allow-all-tools` (skip tool approval). |
| 267 | +* `--allow-all-paths` (disable path verification). |
| 268 | +* `--allow-all-urls` (disables URL verification). |
| 269 | + |
| 270 | +> [!TIP] During an interactive session, you can also enable all permissions with the `/allow-all` or `/yolo` slash commands. |
| 271 | +
|
| 272 | +## Next steps |
| 273 | + |
| 274 | +* [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot) |
0 commit comments