|
| 1 | +--- |
| 2 | +title: Changing settings with the `/settings` command |
| 3 | +shortTitle: Change settings |
| 4 | +allowTitleToDifferFromFilename: true |
| 5 | +intro: 'View and change your personal settings for {% data variables.copilot.copilot_cli %} with the `/settings` slash command.' |
| 6 | +versions: |
| 7 | + feature: copilot |
| 8 | +contentType: how-tos |
| 9 | +category: |
| 10 | + - Configure Copilot # Copilot discovery page |
| 11 | + - Configure Copilot CLI # Copilot CLI bespoke page |
| 12 | +docsTeamMetrics: |
| 13 | + - copilot-cli |
| 14 | +--- |
| 15 | + |
| 16 | +You can use the `/settings` slash command to view and change your settings from within an interactive CLI session. This command controls user-level settings such as whether {% data variables.copilot.copilot_cli_short %} updates itself automatically, which color palette the interface uses, what's displayed in the footer, and many other options. |
| 17 | + |
| 18 | +Use `/settings` to: |
| 19 | + |
| 20 | +* **Browse and edit settings interactively** — Run `/settings` on its own to open a searchable editor that lists every setting with a description and its current value. |
| 21 | +* **Change a setting with a single command** — Run `/settings KEY VALUE` to change a particular setting without opening the editor. |
| 22 | +* **Check a setting's value** — Run `/settings show KEY` to display the current value of a setting. |
| 23 | + |
| 24 | +You can also use `/config`, which is an alias of `/settings`. |
| 25 | + |
| 26 | +Changes you make with `/settings` or `/config` are written to your personal settings file (by default, `~/.copilot/settings.json`) and persist across sessions. |
| 27 | + |
| 28 | +## Opening the settings editor |
| 29 | + |
| 30 | +To browse and edit settings interactively, enter the slash command with no arguments: |
| 31 | + |
| 32 | +```copilot copy |
| 33 | +/settings |
| 34 | +``` |
| 35 | + |
| 36 | +The editor lists every setting you can change, and the setting's current value. As you move up or down through the list, a short description of the highlighted setting is shown at the bottom of the editor. This allows you to browse and edit settings without needing to know their exact names. |
| 37 | + |
| 38 | +For more information about the available settings, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#user-settings-copilotsettingsjson). |
| 39 | + |
| 40 | +While the editor is open, you can use the following keyboard shortcuts: |
| 41 | + |
| 42 | +<!-- Force table-layout: auto so the first column shrinks to its content width on all viewports. The site applies table-layout: fixed below 544px, which would otherwise collapse the first column and make its keys overflow. --> |
| 43 | + |
| 44 | +<table style="table-layout: auto;"> |
| 45 | + <thead> |
| 46 | + <tr> |
| 47 | + <th style="white-space: nowrap;">Key</th> |
| 48 | + <th style="width: 100%;">Action</th> |
| 49 | + </tr> |
| 50 | + </thead> |
| 51 | + <tbody> |
| 52 | + <tr> |
| 53 | + <td style="white-space: nowrap;"><kbd>↑</kbd> / <kbd>↓</kbd></td> |
| 54 | + <td>Move between settings.</td> |
| 55 | + </tr> |
| 56 | + <tr> |
| 57 | + <td style="white-space: nowrap;"><kbd>/</kbd></td> |
| 58 | + <td>Search and filter the list by a setting's name or description.</td> |
| 59 | + </tr> |
| 60 | + <tr> |
| 61 | + <td style="white-space: nowrap;"><kbd>Enter</kbd></td> |
| 62 | + <td>Toggle a boolean setting, or edit other types of values.</td> |
| 63 | + </tr> |
| 64 | + <tr> |
| 65 | + <td style="white-space: nowrap;"><kbd>Ctrl</kbd>+<kbd>R</kbd></td> |
| 66 | + <td>Reset the highlighted setting to its default.</td> |
| 67 | + </tr> |
| 68 | + <tr> |
| 69 | + <td style="white-space: nowrap;"><kbd>Ctrl</kbd>+<kbd>E</kbd></td> |
| 70 | + <td>Open <code>settings.json</code> in your configured terminal editor to make advanced changes.</td> |
| 71 | + </tr> |
| 72 | + <tr> |
| 73 | + <td style="white-space: nowrap;"><kbd>Esc</kbd></td> |
| 74 | + <td>Clear the current search, or close the editor.</td> |
| 75 | + </tr> |
| 76 | + </tbody> |
| 77 | +</table> |
| 78 | + |
| 79 | +Most changes take effect immediately—for example, switching the color palette updates the interface as soon as you select a new value. |
| 80 | + |
| 81 | +## Changing a single setting inline |
| 82 | + |
| 83 | +If you already know which setting you want to change, you can set it directly from the CLI's prompt box, without opening the editor: |
| 84 | + |
| 85 | +```copilot |
| 86 | +/settings KEY VALUE |
| 87 | +``` |
| 88 | + |
| 89 | +For example: |
| 90 | + |
| 91 | +```copilot copy |
| 92 | +/settings autoUpdate off |
| 93 | +``` |
| 94 | + |
| 95 | +{% data variables.product.prodname_copilot_short %} writes the value and confirms it, for example: `Set autoUpdate = false.` |
| 96 | + |
| 97 | +> [!NOTE] |
| 98 | +> * **Boolean settings** accept `on`/`off` or `true`/`false`. For example, `/settings renderMarkdown on`. |
| 99 | +> * **Settings with a fixed set of choices** accept one of those values. For example, `/settings theme dim` or `/settings banner never`. |
| 100 | +> * **Nested settings** use a dotted path. For example, `/settings footer.showBranch off` hides the Git branch in the footer. |
| 101 | +
|
| 102 | +You can configure settings that take set values without needing to remember the exact key or value, just by using the navigation and <kbd>Enter</kbd> keys. For example, to prevent the agent from asking clarifying questions: |
| 103 | + |
| 104 | +1. Type `/settings`, without pressing <kbd>Enter</kbd>, to display a list of options. |
| 105 | +1. Use the <kbd>↓</kbd> key to move down the list until `❯` points to `/settings askUser Allow the agent to ask clarifying questions`, then press <kbd>Enter</kbd>. |
| 106 | +1. Use the <kbd>↓</kbd> key to move down the list of options for this setting until `❯` points to `/settings askUser off`, then press <kbd>Enter</kbd>. |
| 107 | +1. Press <kbd>Enter</kbd> again to submit the `/settings askUser off` command. |
| 108 | + |
| 109 | + The CLI confirms the change: `Set askUser = false.` |
| 110 | + |
| 111 | +## Viewing valid values for a setting |
| 112 | + |
| 113 | +To display the valid values that are available for a setting, enter `/settings KEY` with no value. For example, to see the valid values for `theme`: |
| 114 | + |
| 115 | +```copilot copy |
| 116 | +/settings theme |
| 117 | +``` |
| 118 | + |
| 119 | +## Viewing the current value of a setting |
| 120 | + |
| 121 | +To display a setting's current value, use `show`. For example: |
| 122 | + |
| 123 | +```copilot copy |
| 124 | +/settings show theme |
| 125 | +``` |
| 126 | + |
| 127 | +This outputs a line such as `theme = high-contrast`. The `show` form is useful for quickly checking a value, or for capturing settings in logs. |
| 128 | + |
| 129 | +## Changing settings that require a restart |
| 130 | + |
| 131 | +Most settings apply right away, but a few only take full effect after {% data variables.copilot.copilot_cli_short %} restarts—for example, `experimental` and the proxy settings. When you change one of these, {% data variables.product.prodname_copilot_short %} tells you a restart is needed, and may restart the session for you. |
| 132 | + |
| 133 | +## Settings you can't change from the command line |
| 134 | + |
| 135 | +Not every setting is editable through the inline `/settings KEY VALUE` method: |
| 136 | + |
| 137 | +* **Security-sensitive settings**—such as those that change how credentials are stored or that run a shell command—are deliberately excluded, because flipping them in a single line with no confirmation is risky. |
| 138 | +* **List and structured settings** can't be set inline. Enter `/settings` then press <kbd>Ctrl</kbd>+<kbd>E</kbd> to open `settings.json` in your configured terminal editor, then edit the setting there. |
| 139 | +* **Settings managed by your repository or organization** are shown for reference, but their values come from those sources and override your personal value. Changing them in your user settings has no effect. |
| 140 | + |
| 141 | +In each of these cases, {% data variables.product.prodname_copilot_short %} explains why the change wasn't applied and points you to the right place to make it. |
| 142 | + |
| 143 | +## Commands replaced by `/settings` |
| 144 | + |
| 145 | +Some older slash commands have been folded into `/settings`. They still work, but display a notice telling you about the equivalent `/settings` command. |
| 146 | + |
| 147 | +## Settings you might want to change |
| 148 | + |
| 149 | +Some commonly used settings include: |
| 150 | + |
| 151 | +* `autoUpdate` — Automatically download updated CLI versions. |
| 152 | +* `theme` — Color palette (`default`, `github`, `dim`, `high-contrast`, or `colorblind`). |
| 153 | +* `renderMarkdown` — Render Markdown in the terminal. |
| 154 | +* `banner` — How often to show the startup banner (`always`, `once`, or `never`). |
| 155 | +* `beep` — Beep when {% data variables.product.prodname_copilot_short %} needs your attention. |
| 156 | +* `includeCoAuthoredBy` — Add a `Co-authored-by` trailer to commits. |
| 157 | +* `footer.showBranch` — Show the current Git branch in the footer. |
| 158 | + |
| 159 | +For the full list of available settings and how user, repository, and organization settings combine, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference). |
| 160 | + |
| 161 | +## Further reading |
| 162 | + |
| 163 | +* [AUTOTITLE](/copilot/how-tos/copilot-cli/set-up-copilot-cli/configure-copilot-cli) |
| 164 | +* [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/overview) |
0 commit comments