diff --git a/content/authentication/authenticating-with-single-sign-on/authorizing-a-personal-access-token-for-use-with-single-sign-on.md b/content/authentication/authenticating-with-single-sign-on/authorizing-a-personal-access-token-for-use-with-single-sign-on.md index 749f1ee6ea86..4d839af497c4 100644 --- a/content/authentication/authenticating-with-single-sign-on/authorizing-a-personal-access-token-for-use-with-single-sign-on.md +++ b/content/authentication/authenticating-with-single-sign-on/authorizing-a-personal-access-token-for-use-with-single-sign-on.md @@ -19,6 +19,10 @@ You must authorize your {% data variables.product.pat_v1 %} after creation befor {% data reusables.saml.authorized-creds-info %} +Enterprise administrators can use a {% data variables.product.prodname_github_app %} to authorize credentials for multiple organizations. See [AUTOTITLE](/authentication/authenticating-with-single-sign-on/authorizing-credentials-for-single-sign-on-with-a-github-app). + +## Authorizing a {% data variables.product.pat_v1 %} + {% data reusables.user-settings.access_settings %} {% data reusables.user-settings.developer_settings %} {% data reusables.user-settings.personal_access_tokens %} diff --git a/content/authentication/authenticating-with-single-sign-on/authorizing-credentials-for-single-sign-on-with-a-github-app.md b/content/authentication/authenticating-with-single-sign-on/authorizing-credentials-for-single-sign-on-with-a-github-app.md new file mode 100644 index 000000000000..d0c9bcbf30f9 --- /dev/null +++ b/content/authentication/authenticating-with-single-sign-on/authorizing-credentials-for-single-sign-on-with-a-github-app.md @@ -0,0 +1,90 @@ +--- +title: Authorizing credentials for single sign-on with a GitHub App +intro: 'Authorize credentials for multiple organizations by allowing an enterprise-installed {% data variables.product.prodname_github_app %} to manage single sign-on (SSO) authorizations.' +versions: + ghec: '*' +permissions: Enterprise owners and users with the "Manage enterprise credentials" permission +shortTitle: Authorize credentials with an app +category: + - Sign in with SSO or a passkey +--- + +## About authorizing credentials with a {% data variables.product.prodname_github_app %} + +By default, enterprise-installed {% data variables.product.prodname_github_apps %} cannot authorize credentials. To reduce the number of times that enterprise members must authorize the same credential for individual organizations, you can allow an app to authorize existing {% data variables.product.pat_v1_plural %} or verified, user-owned SSH authentication keys. Up to 50 selected organizations are allowed per request. + +To authorize a credential for a single organization without a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/authentication/authenticating-with-single-sign-on/authorizing-a-personal-access-token-for-use-with-single-sign-on) or [AUTOTITLE](/authentication/authenticating-with-single-sign-on/authorizing-an-ssh-key-for-use-with-single-sign-on). + +## Prerequisites + +Before the app can authorize credentials, the following requirements must be met: + +* The enterprise must use enterprise-level SSO. +* The credential owner must be a member of every organization where the app will authorize the credential. + +## Creating the {% data variables.product.prodname_github_app %} + +1. Register a new app. For instructions, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app#registering-a-github-app). The app must: + + * Be owned by the enterprise or an organization in the enterprise. + * Have write access to the "Enterprise credentials" permission. + +1. Note the app's client ID, then generate and securely store a private key. See [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). +1. Install the app on your enterprise account. See [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-on-your-enterprise). +1. In the URL of the app's installation page, note the installation ID. The ID is the string of numbers at the end of the `/enterprises/ENTERPRISE/settings/installations/ID` URL. + +## Allowing a {% data variables.product.prodname_github_app %} to authorize credentials + +{% data reusables.enterprise-accounts.access-enterprise %} +{% data reusables.enterprise-accounts.security-tab %} + +1. Under "Credentials," enable **Allow {% data variables.product.prodname_github_apps %} to authorize credentials**. + +## Generating an installation access token + +The app must use an enterprise installation access token to authenticate its API requests. Organization installation access tokens, user access tokens, and {% data variables.product.pat_generic_plural %} are not supported. + +To generate an installation access token: + +1. Use the app's client ID and private key to generate a JSON Web Token (JWT). See [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app). +1. Use the JWT and enterprise installation ID to create an installation access token. See [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app). + +The installation access token inherits the enterprise permissions granted to the app, cannot be scoped down, and expires after one hour. + +## Finding credential identifiers + +For credentials that are already authorized for an organization in your enterprise, an organization owner can use the REST API to obtain identifiers in bulk. See [AUTOTITLE](/rest/orgs/orgs#list-saml-sso-authorizations-for-an-organization). + +In the response, use `authorized_credential_id` for a {% data variables.product.pat_v1 %}, or `fingerprint` for an SSH key. Do not use `credential_id`, which identifies the credential's authorization for that organization. + +This endpoint does not return credentials that have not been authorized for the organization. To obtain an identifier for another credential, use one of these methods: + +* For a {% data variables.product.pat_v1 %}, open the token from the [token settings](https://github.com/settings/tokens) page. The token ID is the number at the end of the `/settings/tokens/ID` URL. Alternatively, if the token was used for an action recorded in the enterprise audit log, an enterprise owner can find the ID in the event's `token_id` field. The ID is available in the audit log only while an enterprise-visible event authenticated with that token is retained. Share the ID, not the token value. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise). +* For an SSH key, find the SHA-256 fingerprint for the verified, user-owned authentication key. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-ssh-keys). + +## Authorizing a credential + +Use the REST API to authorize the credential for selected organizations. For example: + +```shell +curl --request POST \ + --url "https://api.github.com/enterprises/ENTERPRISE/credential-authorizations" \ + --header "Accept: application/vnd.github+json" \ + --header "Authorization: Bearer INSTALLATION-ACCESS-TOKEN" \ + --header "X-GitHub-Api-Version: 2026-03-10" \ + --data '{ + "credential_id": 12345678, + "credential_type": "classic_pat", + "organizations": ["ORGANIZATION-1", "ORGANIZATION-2"] + }' +``` + +Replace `ENTERPRISE` with the enterprise slug, `INSTALLATION-ACCESS-TOKEN` with the installation access token, and `ORGANIZATION-1` and `ORGANIZATION-2` with the organization slugs. Replace `12345678` with the ID of the {% data variables.product.pat_v1 %}. To authorize an SSH key instead, replace `12345678` with the key's SHA-256 fingerprint and replace `classic_pat` with `ssh_key`. + +For more information, see [AUTOTITLE](/rest/enterprise-admin/credential-authorizations). + +## Disabling credential authorization by {% data variables.product.prodname_github_apps %} + +Disabling the setting prevents apps from creating new credential authorizations. Existing authorizations remain active until they are revoked, the credential is revoked or deleted, or the credential owner loses membership in the organization. + +You can use the same REST API to revoke authorizations that an app created through enterprise delegation. diff --git a/content/authentication/authenticating-with-single-sign-on/index.md b/content/authentication/authenticating-with-single-sign-on/index.md index ec5e85d9e6a8..009aeeb7561c 100644 --- a/content/authentication/authenticating-with-single-sign-on/index.md +++ b/content/authentication/authenticating-with-single-sign-on/index.md @@ -13,6 +13,7 @@ children: - /about-authentication-with-single-sign-on - /authorizing-an-ssh-key-for-use-with-single-sign-on - /authorizing-a-personal-access-token-for-use-with-single-sign-on + - /authorizing-credentials-for-single-sign-on-with-a-github-app - /authorizing-an-app-for-single-sign-on - /viewing-and-managing-your-active-sso-sessions shortTitle: Authenticate with SSO diff --git a/content/code-security/reference/code-scanning/codeql/codeql-cli-manual/test-run.md b/content/code-security/reference/code-scanning/codeql/codeql-cli-manual/test-run.md index 2e1671ca131f..2a2cfd5e78b4 100644 --- a/content/code-security/reference/code-scanning/codeql/codeql-cli-manual/test-run.md +++ b/content/code-security/reference/code-scanning/codeql/codeql-cli-manual/test-run.md @@ -100,6 +100,14 @@ useful for testing extractors. \[Advanced] Run [codeql dataset check](/code-security/reference/code-scanning/codeql/codeql-cli-manual/dataset-check) over each test database created and report a failure if it detects inconsistencies. This is useful when testing extractors. If the check is (temporarily!) expected to fail for a particular database, place a `DB-CHECK.expected` file in the test directory. +#### `--[no-]reuse-dataset` + +\[Advanced] Attempt to reuse an existing test database from a previous +run. When this option is given, if a `.testproj` directory exists for a +test directory, its dataset will be used instead of extracting a new +database. If no existing database is found, extraction proceeds as +normal. This option implies `--keep-databases`. + #### `--[no-]show-extractor-output` \[Advanced] Show the output from extractor scripts that create test diff --git a/content/copilot/reference/copilot-cli-reference/acp-server.md b/content/copilot/reference/copilot-cli-reference/acp-server.md index 2f128414e51b..23d3911edf8a 100644 --- a/content/copilot/reference/copilot-cli-reference/acp-server.md +++ b/content/copilot/reference/copilot-cli-reference/acp-server.md @@ -32,7 +32,7 @@ The Agent Client Protocol (ACP) is a protocol that standardizes communication be Use the `--acp` option of the `copilot` command to start the CLI's ACP server. You can specify the transport mode with either the `--stdio` or `--port` options. If no transport mode is specified, the server defaults to stdio mode. -ACP mode allows sessions with a configured bring-your-own-key (BYOK) provider (`COPILOT_PROVIDER_*` environment variables) to run without {% data variables.product.github %} login, matching the behavior of `-p`/interactive mode. +ACP mode allows sessions with a configured bring-your-own-key (BYOK) provider (`COPILOT_PROVIDER_*` environment variables, or a providers configuration file—see `COPILOT_PROVIDERS_CONFIG` in [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#environment-variables)) to run without {% data variables.product.github %} login, matching the behavior of `-p`/interactive mode. ### Options applied to every session diff --git a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md index b7fde536cbf6..67c5488643bc 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md @@ -25,9 +25,10 @@ docsTeamMetrics: | `copilot init` | Initialize {% data variables.product.prodname_copilot_short %} custom instructions for this repository. | | `copilot login [OPTION]` | Authenticate with {% data variables.product.prodname_copilot_short %} via OAuth. See [`copilot login` options](#copilot-login-options). | | `copilot mcp` | Manage MCP server configurations from the command line. | -| `copilot plugin` | Manage plugins and plugin marketplaces. | -| `copilot plugins list` | Non-interactively inspect every plugin, MCP server, skill, instruction source, and language server discovered for the current working directory. See [Using `copilot plugins list`](#using-copilot-plugins-list). | -| `copilot skill` | Manage agent skills from the command line (list, add, and remove skills). See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-skills). | +| `copilot plugin` | Manage plugins and plugin marketplaces, including listing, enabling, disabling, and uninstalling them. `copilot plugins` (plural) is a legacy alias. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference). | +| `copilot instruction` | Non-interactively list custom instruction sources discovered for the current working directory. See [Using `copilot instruction`](#using-copilot-instruction). | +| `copilot lsp` | Non-interactively list configured language servers. See [Using `copilot lsp`](#using-copilot-lsp). | +| `copilot skill` | Manage agent skills from the command line (list, add, remove, enable, and disable skills). See [Managing skills non-interactively](#managing-skills-non-interactively). | | `copilot update` | Download and install the latest version. | | `copilot version` | Display version information and check for updates. | @@ -102,77 +103,43 @@ Fish: copilot completion fish > ~/.config/fish/completions/copilot.fish ``` -### Using `copilot plugins list` +### Managing plugins non-interactively -Run `copilot plugins list` to inspect every plugin, MCP server, skill, instruction source, and language server discovered for the current working directory. Output is grouped by kind, then by configuration scope (user, repository, organization, plugin-contributed, built-in, or unknown). +Use `copilot plugin` to install, list, update, enable, disable, and uninstall plugins from the command line, without opening an interactive session. `copilot plugins` (plural) is a legacy alias for the same command. For the full command and option reference, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference). -```bash -# List everything for the current workspace -copilot plugins list +### Using `copilot instruction` -# Only MCP servers and skills -copilot plugins list --kind mcp --kind skill +Run `copilot instruction list` to non-interactively list custom instruction sources discovered for the current working directory. This replaces the retired `copilot plugins list --kind instruction`. -# Only user-scoped resources, as JSON -copilot plugins list --scope user --json +```bash +copilot instruction list +copilot instruction list --json ``` | Option | Description | |-----------------------|------------------------------------------------------------------------------------| -| `--kind KINDS` | Filter by kind. Repeatable or comma-separated: `mcp`, `skill`, `instruction`, `plugin`, `lsp`. | -| `--scope SCOPES` | Filter by configuration scope. Repeatable or comma-separated. | -| `--json` | Emit machine-readable JSON instead of grouped text. | +| `--json` | Emit JSON instead of text. | | `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. | -Custom agents and session-scoped hooks aren't covered by `copilot plugins list`; both require a live session. +Each `--json` entry has the shape `{ id, label, description?, location, type, sourcePath, defaultDisabled, applyTo? }`. This listing resolves plugin-contributed instructions against your global user settings only—an instruction enabled by a trusted repository or by managed settings might not appear here even though a live session applies it. -### `copilot plugins enable` / `copilot plugins disable` +### Using `copilot lsp` -Enable or disable a plugin, MCP server, or skill by name. The change persists to configuration and applies to future sessions. +Run `copilot lsp list` to non-interactively list configured language servers. This replaces the retired `copilot plugins list --kind lsp`. This command is inspect-only; use the `/lsp` slash command in an interactive session to start, stop, or reload a language server. ```bash -# Disable an MCP server -copilot plugins disable github --mcp - -# Enable a skill -copilot plugins enable my-skill --skill - -# Enable a plugin (default kind) -copilot plugins enable spark@copilot-plugins +copilot lsp list +copilot lsp list --json ``` | Option | Description | -|------------------------|------------------------------------------------------------------------------------| -| `--plugin` | Target a plugin (default). | -| `--mcp` | Target an MCP server. | -| `--skill` | Target a skill. | +|-----------------------|------------------------------------------------------------------------------------| +| `--json` | Emit JSON instead of text. | | `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. | -Instructions are session-scoped only and can't be toggled with these commands. Language servers, agents, and hooks are managed elsewhere. - -### `copilot plugins remove` - -Uninstall a plugin, remove an MCP server, or delete a skill by name. - -```bash -# Remove an MCP server -copilot plugins remove github --mcp - -# Delete a personal or project skill -copilot plugins remove my-skill --skill - -# Uninstall a plugin (default kind) -copilot plugins remove spark@copilot-plugins -``` - -| Option | Description | -|------------------------|------------------------------------------------------------------------------------| -| `--plugin` | Remove a plugin (default). | -| `--mcp` | Remove an MCP server. | -| `--skill` | Remove a personal or project skill. | -| `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. | +Each `--json` entry has the shape `{ id, fileExtensions?, sourcePlugin? }`. -With `--skill`, pass either a skill name or the path to a custom skill directory you added. A skill name deletes that skill's files; a custom directory path only unregisters the directory and leaves its files on disk. Only personal and project skills you added can be deleted—skills provided by a plugin or the builtin set can't be removed this way (disable them instead). Instruction sources are discovered from disk and can't be removed here. +Custom agents and session-scoped hooks aren't covered by `copilot instruction`, `copilot lsp`, `copilot plugin`, `copilot mcp`, or `copilot skill`. All require a live session. ## The sessions sidebar @@ -298,8 +265,10 @@ For more information about the sessions sidebar, see [AUTOTITLE](/copilot/how-to | Ctrl+X then `e` | Edit the prompt in an external editor (`$EDITOR`). | | Ctrl+X then `b` | Promote the running task or shell command to the background. | | Ctrl+X then `g` | Collapse or expand the autopilot goal panel. | +| Ctrl+X then `h` | Hide the current-session sidebar. | | Ctrl+X then `o` | Open the most recent link from the timeline. | | Ctrl+X then `v` | Toggle voice dictation on or off. | +| Ctrl+X then `x` | Close the current session. | | Ctrl+Z | Suspend the process to the background (Unix). | | Shift+Enter or Option+Enter (Mac) / Alt+Enter (Windows/Linux) | Insert a newline in the input. | | Shift+Tab | Cycle between standard, plan, and autopilot mode. | @@ -334,6 +303,12 @@ When the tasks dialog is open (opened via `/tasks`): Subagents that spawn their own nested subagents appear as an indented tree; the row you're teleported into is highlighted as "current." While drilled into a subagent's view, you can send it a steering message from the composer the same way you would the main session. +## Restoring an interrupted session + +If a session was still open when its CLI process went away—for example, due to a crash or a machine restart—the next `copilot` startup can offer to restore it, letting you choose which sessions to bring back or start fresh instead. A session whose agent was mid-turn automatically resumes that work once restored. + +This restore behavior is temporarily opt-in while its startup dialog is reworked. Set the `COPILOT_ENABLE_INTERRUPTED_SESSION_RESTORE` environment variable to `1` to enable it. See [Environment variables](#environment-variables). + ## Session picker shortcuts When the session picker is open (opened via `/resume` or `--continue`): @@ -358,6 +333,41 @@ Sessions sort by the following modes: Sessions already open in another window float to the top in all non-relevance sort modes. When no working-directory context is available, the `relevance` mode is skipped. +## Sidebar and sessions tab shortcuts + +The current-session sidebar lets you browse and switch between sessions without leaving the one you're in. On an empty composer, ←/→ walk a three-state focus cycle: closed, timeline-focused, and sidebar-focused. Disable the sidebar entirely with the `sidebar` setting—see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings). + +| Shortcut | Purpose | +|----------|---------| +| ← (Current tab, closed) | Open the sidebar; the timeline keeps focus. | +| ← (timeline-focused) | Move focus into the sidebar. | +| → (sidebar-focused) | Return focus to the timeline. | +| → (timeline-focused) | Close the sidebar. | +| Tab/Shift+Tab | Switch tabs (**Current**, **Sessions**, and so on). | +| ↑/↓ (sidebar-focused) | Move the selection cursor; `j`/`k` are aliases. | +| Enter (sidebar-focused) | Switch the foreground session to the selected card. | +| `n` (sidebar-focused) | Spawn a new background session and bring it to the foreground. | +| `s` (sidebar-focused) | Cycle the sort order: recent → created → name → none. | +| `x`, `x` (sidebar-focused) | Close the selected card (armed for one keystroke, shown in red, before closing). | + +The sidebar's divider can be dragged to resize it, and it auto-collapses below a minimum usable width. Each card shows a status dot, the session name, and its Git branch (or working directory when there is no branch). The foreground session's title is highlighted in accent color, and its card carries a persistent subtle fill. The active sort order (`recent`, `created`, `name`, or `none` for insertion order) persists across restarts. + +Mouse actions mirror the keyboard: click a card to switch the foreground session, double-click a card or empty rail space to focus the sidebar, and click the timeline pane while the sidebar is focused to return focus to it. + +The **Sessions** tab lists the current session plus your full resumable session history under a "Resumable" divider: + +| Shortcut | Purpose | +|----------|---------| +| ↑/↓ | Navigate rows. | +| Shift+↑/↓ | Page up or down. | +| Enter | Resume the selected session. | +| `n` | Start a new session. | +| `a` | Cycle the filter scope: all → local → remote (cloud). | +| `/` | Search live across name, branch or working directory, repository, and session ID. | +| ←/→ | Switch tabs. | + +Remote (cloud) rows in the **Sessions** tab also show online or offline status and the repository. + ## Diff mode shortcuts When diff mode is open (entered via `/diff`): @@ -449,7 +459,7 @@ These are the slash commands you can use from within an interactive CLI session. | `/login` | Log in to {% data variables.product.prodname_copilot_short %}. | | `/logout` | Log out of {% data variables.product.prodname_copilot_short %}. | | `/lsp [show\|test\|reload\|logs\|help] [SERVER-NAME]` | Manage the language server configuration. The `logs` subcommand opens the live LSP services log panel. | -| `/mcp [config\|list\|show\|add\|edit\|delete\|disable\|enable\|auth\|reload\|search] [SERVER-NAME]` | Manage the MCP server configuration. With no subcommand, or with `show`, the plugins dashboard opens showing your MCP servers. Select a server and press Enter for its details and for actions such as enabling or disabling it, or use `show SERVER-NAME` to open that server's details directly. `config` opens the MCP configuration interface instead of the dashboard. `list` (alias `ls`) prints a plain-text list of configured servers with connection status and live state, and is read-only, so it can run while the agent is busy processing a turn. All subcommands other than `config`, `show`, and `list` are blocked until the turn finishes. Sandboxed local servers show a `connected (sandboxed)` status. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers#managing-mcp-servers). | +| `/mcp [config\|list\|show\|add\|edit\|delete\|disable\|enable\|auth\|reload\|search] [SERVER-NAME]` | Manage the MCP server configuration. With no subcommand, or with `config`, the plugins dashboard opens pinned to the MCP server list; the add, edit, and authenticate forms open inside that dashboard too, so closing a form returns you to the server list. Use `show` or `show SERVER-NAME` to display all configured servers or open one server's details directly, including its available tools, and to enable or disable it. `list` (alias `ls`) prints a plain-text list of configured servers with connection status and live state. Bare `/mcp`, `config`, `show`, and `list` (alias `ls`) are read-only or open the dashboard, so they can run while the agent is busy processing a turn. The mutating subcommands (`add`, `edit`, `delete`, `disable`, `enable`, `auth`, `reload`, and `search`) are blocked until the turn finishes. `edit ` rejects a workspace-sourced server (one defined in a repository's `.mcp.json`) instead of opening the user-tier wizard, since saving would silently create a same-name user entry that the workspace one still shadows. The error names the file to edit directly. `delete ` reports the same file when asked to remove a workspace-sourced server. Sandboxed local servers show a `connected (sandboxed)` status. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers#managing-mcp-servers). | | `/model [--session\|--global\|--repo\|--local] [MODEL]`, `/models` | Select the AI model you want to use, or choose **Auto**. By default (or with `--session`, alias `-s`), changes the model, reasoning effort, or context window for the current session only, without touching saved settings. `--repo`/`--local` pins the default model in repository settings instead; `--global` (or `/config model`) sets the default for future sessions. Press Tab on a model with a long-context variant to toggle its Context column between the default and long-context window. The picker groups models into sections—press Shift+Tab to cycle grouping between recommended (Recent, Recommended, New, and other models), vendor, and category. A model with vendor-specific data retention terms shows a data retention warning banner with a link to the vendor's policy. Usable mid-turn: a change requested while the agent is running is queued as a cancellable (Ctrl+C) command and applied once the current turn finishes, instead of switching the live model mid-request. See [AUTOTITLE](/copilot/concepts/models/auto-model-selection). | | `/permissions [default\|assisted\|allow-all\|show]` | Switch between permission modes (`default`, `assisted`, `allow-all`), or show the current mode (`show`). This is the canonical command for permission mode changes; `/allow-all` and `/yolo` remain supported as aliases. | | `/permissions reset` | Reset all in-memory tool and path approvals for the current session (re-prompt on next use). | @@ -474,7 +484,7 @@ These are the slash commands you can use from within an interactive CLI session. | `/resume [SESSION-ID]`, `/continue [SESSION-ID]` | Switch to a different session by choosing from a list (optionally specify a session ID). | | `/review [PROMPT]` | Run the code review agent to analyze changes. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review). | | `/rubber-duck [PROMPT]` | Consult the rubber duck agent for a second opinion on plans, code, and tests. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/rubber-duck). | -| `/sandbox [config\|status\|policy\|enable\|disable]` | Manage OS-level sandboxing that restricts filesystem and network access for shell commands, MCP/LSP servers, and built-in file/web tools. `config` (or bare `/sandbox`) opens the sandbox settings dialog. `status` shows whether sandboxing is enabled. `policy` shows the effective policy, with path grants grouped by source (user-configured, system, working directory, current session, and `~/.copilot`) and access type, plus the network stance and any detected developer tools. `enable`/`disable` turn sandboxing on or off directly. {% data reusables.copilot.experimental %} | +| `/sandbox [config\|status\|policy\|enable\|disable]` | Manage OS-level sandboxing that restricts filesystem and network access for shell commands, MCP/LSP servers, and built-in file/web tools. `config` (or bare `/sandbox`) opens the sandbox settings dialog. `status` shows whether sandboxing is enabled. `policy` shows the effective policy, with path grants grouped by source (user-configured, system, working directory, current session, and `~/.copilot`) and access type, plus the network stance and any detected developer tools. `enable`/`disable` turn sandboxing on or off directly. `status` and `policy` are read-only and can run while the agent is busy processing a turn. `config`, `enable`, and `disable` are queued until the turn finishes. {% data reusables.copilot.experimental %} | | `/search [QUERY]`, `/find [QUERY]` | Search the conversation timeline. | | `/security-review [PROMPT]` | Run a focused security review of active local code changes and return prioritized vulnerability findings with remediation suggestions. This command is not a full repository security audit. | | `/session [info\|checkpoints [n]\|files\|plan\|rename [NAME]\|cleanup\|prune\|delete [ID]\|delete-all]`, `/sessions [info\|checkpoints [n]\|files\|plan\|rename [NAME]\|cleanup\|prune\|delete [ID]\|delete-all]` | Show session information and manage sessions. The `info` subcommand shows session details including the session link (when available). Subcommands: `info`, `checkpoints`, `files`, `plan`, `rename`, `cleanup`, `prune`, `delete`, `delete-all`. | @@ -487,7 +497,7 @@ These are the slash commands you can use from within an interactive CLI session. | `/skills remove ` | Remove a skill by name, or unregister a custom skill directory. | | `/skills reload` | Reload skills from all directories. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-skills). | | `/statusline`, `/footer` | Configure which items appear in the status line. | -| `/subagents`, `/agents` | Configure default and per-agent subagent models. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings). | +| `/subagents`, `/agents` | Configure default and per-agent subagent models. For an agent with `modelPolicy: "required"`—whether set in the agent's own definition or in the `subagents` settings override—the picker shows a locked **Model** entry and a **Model enforcement** row reading "required - cannot be overridden" (or "required by agent definition" when the agent definition itself sets the policy). Switch the policy back to `"preferred"` from the picker to allow overrides again, unless the agent definition requires it. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#configuration-file-settings). | | `/tasks` | View and manage tasks (subagents and shell commands). | | `/terminal-setup` | Configure the terminal for multiline input support (Shift+Enter and Ctrl+Enter). | | `/theme [default\|github\|dim\|high-contrast\|colorblind]` | View or set the color mode. | @@ -497,6 +507,7 @@ These are the slash commands you can use from within an interactive CLI session. | `/usage` | Display session usage metrics and statistics, including per-model token totals. | | `/user [show\|list\|switch]` | Manage the current {% data variables.product.github %} user. | | `/version` | Display version information and check for updates. | +| `/vim` | Toggle Vim mode for the input composer, enabling Vim-style modal editing: motions (for example, `hjkl`, `w`, `b`, `e`, `0`, `$`, `gg`, `G`), character search (`f`/`F`/`t`/`T`/`;`/`,`), insert commands (`i`/`a`/`o`), edit commands (`r`/`~`/`J`/`x`/`D`/`C`), operators (`d`/`c`/`y`), yank and put (`y`/`p`/`P`), repeat (`.`), undo and redo (`u`/Ctrl+R), counts, and Esc to return to normal mode. Also configurable with the `editorMode` setting. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#user-settings-copilotsettingsjson). | | `/voice [on\|off\|models\|devices]` | Toggle voice mode, browse available voice models, or choose the input device (microphone). | | `/fork [NAME]`, `/branch [NAME]` | Fork the current session into a new session, optionally with a name. | | `/worktree [branch\|task]` | Create a new Git worktree and switch to it, leaving uncommitted changes behind in the current worktree. Pass a branch name, a task description (multiline supported, used as the opening prompt in the new worktree), or omit the argument to auto-generate a branch name from the conversation. By default, branches off the current checkout (`HEAD`); set the `worktreeBaseRef` setting to `"defaultBranch"` to branch off the remote default branch instead. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#user-settings-copilotsettingsjson). Requires a Git repository. {% data reusables.copilot.experimental %} | @@ -518,7 +529,7 @@ In the schedule manager opened by a bare `/every` or `/after`, use ↑↑/providers.json`. When this file declares any provider or model, it takes precedence over the legacy `COPILOT_PROVIDER_*` environment variables. See [`providers.json`](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#providersjson). | | `COPILOT_SKILLS_DIRS` | Comma-separated list of additional directories for skills. | | `PLUGINS_DASHBOARD` | Set to `false` to disable the plugins dashboard opened by bare `/plugin`, `/mcp`, and `/skills`, and to disable the non-interactive `copilot plugin`/`copilot plugins` commands. | | `COPILOT_STRIP_REASONING_ON_RESUME` | Set to `0` or `false` to keep BYOK reasoning tokens across a session resume instead of stripping them. Defaults to stripping them. | @@ -761,7 +776,7 @@ copilot --deny-tool='write(secret.txt)' | `GITHUB_TOKEN` | Authentication token. | | `PLAIN_DIFF` | Set to `true` to disable rich diff rendering. | | `USE_BUILTIN_RIPGREP` | Set to `false` to use the system ripgrep instead of the bundled version. | -| `USE_TGREP` | Set to `true` to always use [tgrep](https://github.com/microsoft/tgrep), a trigram-indexed search engine, regardless of repository size, or `false` to always use ripgrep. When unset, {% data variables.copilot.copilot_cli_short %} automatically switches from ripgrep to tgrep once a repository exceeds a platform-specific file-count threshold. | +| `USE_TGREP` | Set to `true` to always use [tgrep](https://github.com/microsoft/tgrep), a trigram-indexed search engine, even outside a Git repository or on a virtualized or network filesystem (for example, a VFS for Git checkout, or an SMB/9p mount), or `false` to always use ripgrep. When forced outside a Git repository, tgrep indexes the working directory itself, so avoid forcing it somewhere large such as your home directory. Windows cloud-sync folders (for example, OneDrive) always use ripgrep, even when this is set to `true`. When unset, {% data variables.copilot.copilot_cli_short %} automatically switches from ripgrep to tgrep only inside a Git repository, on a non-virtualized filesystem, and once it exceeds a platform-specific file-count threshold. | ## Configuration file settings @@ -838,6 +853,7 @@ Use `copilot mcp` to manage MCP server configurations from the command line with | `list [--json]` | List all configured MCP servers grouped by source, including plugin-provided servers. | | `get [--json]` | Show configuration and tools for a specific server. For plugin-provided servers, also shows the source plugin name and version. | | `add [options] [url]` | Add a server to the user configuration. Writes to `~/.copilot/mcp-config.json`. | +| `enable ` / `disable ` | Enable or disable a server by name. The change persists to the user configuration and applies to future sessions. | | `remove ` | Remove a user-level server. Workspace servers must be edited in their configuration files directly. | For local (stdio) servers, provide the command after `--`: @@ -1002,6 +1018,10 @@ The `github-mcp-server` provides the following tools. | `list_workflow_runs`, `get_workflow_run_logs` | {% data variables.product.prodname_actions %}. | | `get_label`, `list_label`, `label_write` | Label management. | +### Resource discovery + +{% data reusables.copilot.experimental %} When a local capability is missing, the agent can search a remote catalog for public MCP servers and skills to add, using a built-in `discover-resources` skill. The skill queries the catalog for relevance-ranked MCP servers and skills matching an abstract capability (for example, "database access" or "architecture diagrams"), then presents candidates for you to choose from. The skill itself never installs anything. The `/plugin`, `/mcp`, and `/skills` dashboards also include a typed catalog search that blends the same remote results into the local resource list. + ### MCP server naming Server names can contain any printable characters, including spaces, Unicode characters, and punctuation. Control characters (U+0000–U+001F, U+007F) and the closing brace (`}`) are not allowed. Server names are used as prefixes for tool names—for example, a server named `my-server` produces tool names like `my-server-fetch`, and a server named `My Server` produces `My Server-fetch`. @@ -1124,19 +1144,33 @@ Remote skills are projected alongside local skills and follow the same name-base When two plugins provide skills with the same name, both coexist using plugin-qualified invocation names such as `/my-plugin/search` and `/other-plugin/search`. The bare name routes to the higher-priority plugin. This applies to skills only; commands keep the standard tier-based deduplication, where the higher-priority source wins. -### Installing a skill non-interactively +### Managing skills non-interactively -Use `copilot plugins install --skill` to install a skill from a file, URL, or directory without opening an interactive session: +Use `copilot skill` to manage skills from the command line without opening an interactive session. + +| Subcommand | Description | +|------------|-------------| +| `list [--json]` | List all discovered skills. | +| `add [--project]` | Add a skill from a file path, URL, or directory. | +| `remove ` | Remove a personal or project skill, or unregister a custom skill directory. | +| `enable ` / `disable ` | Enable or disable a skill by name. | ```bash -# Install for your user account (default scope) -copilot plugins install --skill ./my-skill/SKILL.md +# Install a skill for your user account (default) +copilot skill add ./my-skill/SKILL.md -# Install into the current project (.github/skills; file or URL skills only) -copilot plugins install --skill --scope project ./my-skill/SKILL.md +# Install a skill into the current project (.github/skills; file or URL skills only) +copilot skill add --project ./my-skill/SKILL.md + +# Enable, disable, or remove a skill by name +copilot skill enable my-skill +copilot skill disable my-skill +copilot skill remove my-skill ``` -Installing a directory registers it as a custom skill source rather than copying it. Installing a file or URL copies the skill's content into your personal or project skills directory. The equivalent interactive command is `/skills add [--project] `. For the full option reference, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference#copilot-plugins-install-options). +Installing a directory registers it as a custom skill source rather than copying it. Installing a file or URL copies the skill's content into your personal or project skills directory. The equivalent interactive command is `/skills add [--project] `. + +`copilot skill list --json` rows have the shape `{ name, description, source, path, enabled }`. With `remove`, pass either a skill name or the path to a custom skill directory you added—a skill name deletes that skill's files, while a custom directory path only unregisters the directory and leaves its files on disk. Only personal and project skills you added can be removed; skills provided by a plugin or the builtin set can't be removed this way (disable them instead). This replaces the retired `copilot plugins install --skill [--scope project]` and `copilot plugins remove/enable/disable --skill`. ### Commands (alternative skill format) @@ -1150,12 +1184,12 @@ Custom agents are specialized AI agents defined in Markdown files. The filename | Agent | Default model | Description | |-------|--------------|-------------| -| `code-review` | claude-sonnet-4.5 | High signal-to-noise code review. Analyzes diffs for bugs, security issues, and logic errors. Will not modify code. | +| `code-review` | claude-sonnet-4.6 | High signal-to-noise code review. Analyzes diffs for bugs, security issues, and logic errors. Will not modify code. | | `explore` | gpt-5.4-mini | Fast codebase exploration. Searches files, reads code, and answers questions. Returns focused answers under 300 words. Safe to run in parallel. | -| `general-purpose` | claude-sonnet-4.5 | Full-capability agent for complex multi-step tasks. Runs in a separate context window. | +| `general-purpose` | claude-sonnet-4.6 | Full-capability agent for complex multi-step tasks. Runs in a separate context window. | | `research` | claude-haiku-4.5 | Executes thorough searches based on instructions. Searches {% data variables.product.github %} repositories, fetches files, verifies claims, and reports detailed findings with citations. | | `rubber-duck` | complementary model | Use a complementary model to provide a constructive critique of proposals, designs, implementations, or tests. Identifies weak points and suggests improvements. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/rubber-duck). | -| `security-review` | claude-sonnet-4.5 | Security-focused code review. Analyzes changes for high-confidence vulnerabilities across 11 categories. Only flags issues with >80% confidence of exploitability. Reports severity and confidence scores. Will not modify code. | +| `security-review` | claude-sonnet-4.6 | Security-focused code review. Analyzes changes for high-confidence vulnerabilities across 11 categories. Only flags issues with >80% confidence of exploitability. Reports severity and confidence scores. Will not modify code. | | `task` | claude-haiku-4.5 | Command execution (tests, builds, lints). Returns brief summary on success, full output on failure. | `code-review` and `security-review` never forward a full review to another review agent: launching one already fulfills a request to "use" or "call" a reviewer, so it performs the review itself instead of delegating the whole task to a nested `code-review` or `security-review` subagent, recursively, across the entire delegation chain. `code-review` still hands off to the dedicated `security-review` specialist for security-focused portions of a request, and both agents may delegate narrow, independently scoped fact-finding work to non-review agents such as `explore`. @@ -1170,11 +1204,13 @@ Only the root agent can call `store_memory` or `vote_memory` to save or vote on | `infer` | boolean | No | Allow auto-delegation by the main agent. Default: `true`. | | `mcp-servers` | object | No | MCP servers to connect. Uses the same schema as `~/.copilot/mcp-config.json`. | | `model` | string | No | AI model for this agent. When unset, inherits the outer agent's model. When the session model is set to `Auto` (server-selected), subagents always inherit the resolved session model regardless of this field. | +| `models` | string[] | No | Authored models in priority order. The runtime uses the first model the user's plan can access; if none resolve, dispatch falls back to the session's model. Overrides `model` when both are set. | +| `modelPolicy` | string | No | `"preferred"` (default) lets `model`/`models` be overridden by a `subagents` override in `~/.copilot/settings.json` or the `/subagents` picker. `"required"` locks dispatch to one of the authored models—overrides are rejected and the picker's **Model** entry is disabled. | | `name` | string | No | Display name. Defaults to the filename. | | `reasoningEffort` | string | No | Default reasoning effort for this agent (for example, `"low"`, `"medium"`, or `"high"`). When unset, inherits the outer agent's effort. | | `tools` | string[] | No | Tools available to the agent. Default: `["*"]` (all tools). Include `*` anywhere in the list to grant full tool access—for example, `["view", "*"]` grants every tool, not just `view`. | -`model` and `reasoningEffort` apply whether the agent is dispatched through the `task` tool or started directly—for example, through the SDK's `session.startSubagent`. They're resolved with this precedence, highest first: an explicit per-call value, the `subagents` override in `~/.copilot/settings.json`, the agent definition's `model`/`reasoningEffort` field, then the parent session's value. A declared model or effort that can't be honored falls back to the session's value instead of failing the dispatch. +`model`, `models`, `modelPolicy`, and `reasoningEffort` apply whether the agent is dispatched through the `task` tool or started directly—for example, through the SDK's `session.startSubagent`. Model and effort are resolved with this precedence, highest first: an explicit per-call value, the `subagents` override in `~/.copilot/settings.json`, the agent definition's `model`/`models`/`reasoningEffort` field, then the parent session's value. A declared model or effort that can't be honored falls back to the session's value instead of failing the dispatch—unless the agent declares `modelPolicy: "required"`, in which case dispatch is refused rather than silently substituting an unauthored model. ### Custom agent locations @@ -1372,6 +1408,12 @@ High-risk commands display additional warnings and require explicit confirmation When sandboxing is enabled and the **Allow sandbox bypass** setting is on (the default), a synchronous shell command that's blocked by the sandbox's filesystem or network policy prompts you to re-run it outside the sandbox—no model round-trip is required. Approving the prompt re-runs the command and returns its output. Declining keeps the sandboxed (blocked) result. +A sandbox bypass prompt also offers a **Yes, and disable the sandbox for the rest of this session** option. Choosing it turns off sandboxing for every remaining command in the current session, not just the command being approved. This only applies to the current session—starting a new session with `/new` sandboxes commands again, and the option has no effect on the saved `sandbox` configuration setting or on other running sessions. + +A detached (backgrounded) command can't be sandboxed at all, since the sandbox can't wrap a process that outlives the tool call. When the **Allow sandbox bypass** setting is on, this prompts for approval before the command starts, instead of being refused outright. Approving runs the command unsandboxed from the start. + +On Windows hosts whose sandbox policy supports denial capture, a blocked interactive shell command escalates in a single step instead of jumping straight to a full bypass. Approving re-runs the command with file and process restrictions set to record instead of block (the network policy still applies), then falls back to the disclosed full bypass only if the command is still blocked. Only one prompt is shown for the entire escalation. + For more information, see [AUTOTITLE](/copilot/how-tos/cloud-and-local-sandboxes/configuring-local-sandbox-settings#allowing-sandbox-bypass). #### Environment variable denylist @@ -1395,6 +1437,8 @@ The `web_fetch` tool enforces server-side request forgery (SSRF) protections bef * **IP blocklist**: Requests to loopback addresses (`127.x.x.x`, `::1`), RFC-1918 private ranges (`10.x`, `172.16–31.x`, `192.168.x`), and cloud metadata endpoints (for example, `169.254.169.254`) are blocked by IP-literal check and DNS pre-resolution. * **Validated redirects**: `web_fetch` follows `3xx` redirects (up to 10 hops, within a 60-second network budget), re-validating each hop's target against the same IP blocklist before following it. A redirect to a different origin than the original URL requires permission approval, the same as any other cross-origin fetch; same-origin redirects are followed without an extra prompt. The final result notes when content was `(redirected from )`. +When sandboxing is enabled, requests are checked against the sandbox network policy (outbound access, local and private hosts) before the permission prompt, so a target blocked by policy fails fast instead of prompting. If the **Allow sandbox bypass** setting is on and the sandbox network proxy can't reach a URL—as opposed to the URL being denied by policy—`web_fetch` prompts you to retry the request outside the sandbox. Approving makes one more attempt at the fetch and returns its outcome. + To allow `web_fetch` to reach `localhost` during development—for example, for a local docs server—set the following environment variable: ```bash @@ -1437,6 +1481,8 @@ Every variable is read on every platform; the **Typically set on** column shows These are not the only read-only grants. {% data variables.copilot.copilot_cli_short %} also grants your user-profile application directories (`~/.local/bin` and `~/.local/lib` on Linux and macOS; the immediate subdirectories of `%LOCALAPPDATA%\Programs` on Windows), standard system and profile locations, and the caches and registries used by common package managers and toolchains (shown as **dev-tool access** in the `/sandbox policy` report). To see the fully resolved policy for your current directory—read/write, read-only, and denied paths—run `/sandbox policy` in a session. For the concepts behind how the policy is assembled, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/understanding-local-sandboxing). +On Windows, `/sandbox policy` lists the directories on your `PATH` environment variable under **System** read-only grants; other developer-tool paths are grouped separately as detected project tool groups. + ## OpenTelemetry monitoring {% data variables.copilot.copilot_cli_short %} can export traces and metrics via [OpenTelemetry](https://opentelemetry.io/) (OTel), giving you visibility into agent interactions, LLM calls, tool executions, and token usage. All signal names and attributes follow the [OTel GenAI Semantic Conventions](https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai/). diff --git a/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md b/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md index 480a58f4102f..7f9c2df7230b 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md @@ -38,6 +38,7 @@ The `~/.copilot` directory contains the following top-level items. | `mcp-secrets/` | Directory | Local fallback storage and index for MCP secret placeholders | | `permissions-config.json` | File | Saved tool and directory permissions per project | | `plugin-data/` | Directory | Persistent data for installed plugins | +| `providers.json` | File | User-level bring-your-own-key (BYOK) provider and model registry | | `session-state/` | Directory | Session history and workspace data | | `command-history-state/` | Directory | Command history data | | `session-store.db` | File | SQLite database for cross-session data | @@ -93,6 +94,12 @@ Defines Language Server Protocol (LSP) servers available at the user level. Thes For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers). +### `providers.json` + +Defines a registry of bring-your-own-key (BYOK) providers and models, as a JSON object with `providers` and `models` keys. When this file declares any provider or model, it takes precedence over the legacy `COPILOT_PROVIDER_*` environment variables. + +By default, this file is located at `~/.copilot/providers.json`. Override its location with the `COPILOT_PROVIDERS_CONFIG` environment variable. + ### `agents/` Store 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. @@ -401,6 +408,7 @@ To override the default `~/.copilot` location, set the `COPILOT_HOME` environmen | `mcp-secrets/` | With caution | Clears local MCP secret fallback state and mappings. Secret-backed MCP servers may need reconfiguration. | | `permissions-config.json` | With caution | Resets all saved permissions. The CLI will prompt you again for tool and directory approvals. | | `plugin-data/` | Yes | Plugin persistent data is re-created as needed. | +| `providers.json` | Not recommended | You will lose your BYOK provider and model configuration. Back up first. | | `session-state/` | With caution | Deleting removes session history. You will no longer be able to resume past sessions. | | `command-history-state/` | With caution | Deleting removes command history. You will no longer be able to search previous commands with Ctrl+R. | | `session-store.db` | With caution | Deleting removes cross-session data. The file is re-created automatically. | @@ -458,6 +466,7 @@ These settings apply across all your sessions and repositories. You can use the | `disabledMcpServers` | `string[]` | `[]` | MCP server names to disable. Listed servers are configured but not started. | | `disabledSkills` | `string[]` | `[]` | Skill names to disable. Listed skills are discovered but not loaded. | | `dynamicRetrieval` | `{ skills?: boolean }` | unset | Per-category control of embeddings-based dynamic instruction retrieval. Set `skills` to `false` to disable retrieval for skills. | +| `editorMode` | `"normal"` \| `"vim"` | `"normal"` | Input composer editing mode. Set by toggling the `/vim` slash command. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#slash-commands-in-the-interactive-interface). | | `effortLevel` | `string` | `"medium"` | Reasoning effort level for extended thinking: `"low"`, `"medium"`, `"high"`, or `"xhigh"`. Higher levels use more compute. | | `enabledMcpServers` | `string[]` | `[]` | Enable built-in MCP servers that are disabled by default. | | `enabledPlugins` | `Record` | `{}` | Declarative plugin auto-install. Keys are plugin specs; values are `true` (enabled) or `false` (disabled). | @@ -496,19 +505,21 @@ These settings apply across all your sessions and repositories. You can use the | `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. | | `showTimestamps` | `boolean` | `true` | Show dim `HH:mm` timestamps next to user messages in the timeline. | | `showTipsOnStartup` | `boolean` | `true` | Show a random command tip when the CLI starts. | +| `sidebar` | `boolean` | `true` | Enable the current-session sidebar. Set to `false` to disable it entirely, hiding the composer hint and the ← open gesture. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#sidebar-and-sessions-tab-shortcuts). | | `skillDirectories` | `string[]` | `[]` | Additional directories to search for custom skill definitions (in addition to `~/.copilot/skills/`). | | `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. | | `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 [AUTOTITLE](/copilot/concepts/agents/copilot-cli/autopilot#staying-in-autopilot-mode-between-tasks). | | `storeTokenPlaintext` | `boolean` | `false` | Allow authentication tokens to be stored in plain text in `config.json` when no system keychain is available. | | `stream` | `boolean` | `true` | Enable streaming responses. | | `streamerMode` | `boolean` | `false` | Hide preview model names, quota details, prompt timestamps, and the update-available notice. Useful when demonstrating {% data variables.copilot.copilot_cli_short %} or screen sharing. | -| `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. | +| `subagents.agents` | `object` | `{}` | Per-agent model configuration, keyed by agent name. Each value is an object with optional `model` (string), `modelPolicy` (`"preferred"` or `"required"`), `effortLevel` (string), and `contextTier` (`"default"`, `"long_context"`, or `"inherit"`) fields. Set `model`, `effortLevel`, or `contextTier` to `"inherit"` to use the parent session's value at dispatch time. `modelPolicy` has no effect when the agent definition itself sets `modelPolicy: "required"`—that lock can't be overridden here. Use the `/subagents` slash command to configure these settings interactively. | | `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. | | `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 [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#subagent-limits). | | `subagents.maxDepth` | `number` | `6` | Maximum subagent nesting depth. Only honored for usage-based billing users; ignored for all other plans. Capped at `256`. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#subagent-limits). | | `tabs.enabled` | `boolean` | `true` | Show the home tab bar. Set to `false` to hide it entirely. | | `tabs.hide` | `string[]` | `[]` | Tab identifiers to hide. Accepted values: `"copilot"`, `"agents"`, `"issues"`, `"pull-requests"`, `"gists"` (matched case-insensitively). | | `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. | +| `taskbarPresence` | `boolean` | `true` | Show a live {% data variables.product.prodname_copilot_short %} session on the Windows taskbar (agent icon and hover card). Set to `false` to opt out. Startup-only; takes effect on the next launch. Windows only. | | `terminalProgress` | `boolean` | `true` | Emit OSC 9;4 terminal progress indicators while the agent is working. Supported terminals include Windows Terminal, iTerm2, Ghostty, and ConEmu. | | `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. | | `toolSearch` | `boolean` | model- and feature-dependent | Controls tool search (deferred tool loading). Set `toolSearch: false` to opt out of tool search. | @@ -633,6 +644,7 @@ Only the following keys are supported in MDM managed settings. | `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). | | `enabledPlugins` | Enable or disable specific plugins | | `extraKnownMarketplaces` | Add trusted plugin marketplaces | +| `forceLoginOrgs` | Pin sign-in to an approved set of {% data variables.product.github %} organizations (an array of organization logins, matched case-insensitively). {% data variables.product.prodname_copilot_short %} only runs for an account belonging to at least one listed organization; a personal account, an account that belongs only to some other enterprise, or BYOK/API-key authentication is refused with an actionable error. Set an empty array to turn the pin off without deleting the key. Deploy this key through the device channel (MDM plist/registry, or `managed-settings.json`) since it must be able to redirect a developer's first sign-in—the server-managed channel only reaches accounts that have already authenticated into the organization. This key fails closed: an unusable value, or a managed policy that can't be read on a known-managed device, blocks all sign-in until fixed. | | `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. | | `model` | Set a default model for all users (overridden by the `--model` flag or a resumed-session model) | | `permissions` | Set managed permissions, including `disableBypassPermissionsMode` and `deny` / `ask` / `allow` rule arrays. See [Managed permission rules](#managed-permission-rules). | diff --git a/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md b/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md index eb0f0e5ce316..d5c17c556250 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md @@ -20,12 +20,12 @@ For an overview of what plugins are and how they work across {% data variables.p ## CLI commands -You can use the following commands in the terminal to manage plugins for {% data variables.copilot.copilot_cli_short %}. `copilot plugin` and `copilot plugins` are interchangeable—use whichever reads better for the subcommand. +You can use the following commands in the terminal to manage plugins for {% data variables.copilot.copilot_cli_short %}. `copilot plugins` (plural) is a legacy alias for `copilot plugin`—both resolve to the same command. | Command | Description | |------------------------------------------------|-------------| -| `copilot plugin install SPECIFICATION` | Install a plugin. See [Plugin specification for `install` command](#plugin-specification-for-install-command) below. | -| `copilot plugin uninstall NAME` | Remove a plugin | +| `copilot plugin install SPECIFICATION` (alias `add`) | Install a plugin. See [Plugin specification for `install` command](#plugin-specification-for-install-command) below. | +| `copilot plugin uninstall NAME` (aliases `remove`, `rm`) | Remove a plugin | | `copilot plugin list` | List installed plugins | | `copilot plugin update NAME` | Update a named plugin. Use `--all` to update all installed plugins at once. | | `copilot plugin enable NAME` | Enable a previously disabled plugin | @@ -36,10 +36,13 @@ You can use the following commands in the terminal to manage plugins for {% data | `copilot plugin marketplace update [NAME]` (alias `refresh`) | Re-fetch a marketplace's plugin catalog. Omit `NAME` to refresh the catalogs of every registered marketplace. | | `copilot plugin marketplace remove NAME` | Unregister a marketplace. Refused if plugins from the marketplace are still installed; pass `--force` to also uninstall those plugins. | -Non-interactively, `copilot plugins enable NAME --plugin`, `copilot plugins disable NAME --plugin`, and `copilot plugins remove NAME --plugin` provide the same enable, disable, and uninstall operations. `--plugin` is the default kind and can be omitted for these three commands. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#using-copilot-plugins-list) for the non-interactive `--mcp` and `--skill` kinds, which extend these commands to MCP servers and skills. +Before `copilot plugin` was split into separate commands by resource, `copilot plugins` also inspected and toggled MCP servers, skills, instructions, and language servers using `--kind`, `--scope`, `--mcp`, and `--skill` flags. Those cross-kind flags have been removed. Use the dedicated [`copilot mcp`](/copilot/reference/copilot-cli-reference/cli-command-reference#copilot-mcp-subcommand), [`copilot skill`](/copilot/reference/copilot-cli-reference/cli-command-reference#managing-skills-non-interactively), [`copilot instruction`](/copilot/reference/copilot-cli-reference/cli-command-reference#using-copilot-instruction), and [`copilot lsp`](/copilot/reference/copilot-cli-reference/cli-command-reference#using-copilot-lsp) commands instead. `copilot plugin list --json` now emits a flat array of plugins instead of the previous `{ plugins, errors }` object. + > [!NOTE] > A plugin or marketplace pinned by an organization or MDM managed policy (`enabledPlugins`, `extraKnownMarketplaces`) can't be re-enabled, disabled, or repointed locally—the managed value wins for that entry. The `/plugin` dashboard marks these rows with a `Managed` badge and refuses a conflicting toggle. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#mdm-managed-settings). +> +> A plugin whose activation is currently decided by the current repository's `enabledPlugins` overlay rejects `copilot plugin enable`/`disable` instead of silently persisting a global value that would have no effect in that repository. The error names the settings file that actually controls the plugin. See [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference#repository-settings-githubcopilotsettingsjson). ### Plugin specification for `install` command @@ -51,26 +54,37 @@ Non-interactively, `copilot plugins enable NAME --plugin`, `copilot plugins disa | Git URL | `https://github.com/o/r.git` | Any Git URL | | Local path | `./my-plugin` or `/abs/path` | Local directory | -### `copilot plugins install` options +### `copilot plugin list` options + +| Option | Description | +|------------------------|------------------------------------------------------------------------------------| +| `--json` | Emit a flat JSON array of plugins instead of text. | +| `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. | + +Each `--json` row has the shape `{ name, marketplace?, version?, enabled, source, installedFrom? }`. -In addition to installing a plugin from a specification, `copilot plugins install` can install an individual skill from a file, URL, or directory with `--skill`. A skill install isn't a plugin install and doesn't go through a marketplace—see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#skills-reference) for details on skills themselves. +### `copilot plugin enable`/`disable` options | Option | Description | |------------------------|------------------------------------------------------------------------------------| -| `--plugin` | Install a plugin (default). | -| `--skill` | Install a skill from a local path or URL. | -| `--scope SCOPE` | For a file or URL `--skill` install: `user` (default) or `project`. `project` scopes the install to the current repository's `.github/skills` directory instead of your user account, and only applies to file or URL skill installs. | | `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. | -Installing a directory registers it as a custom skill source rather than copying it; installing a file or URL copies the skill's content into your personal or project skills directory. +### `copilot plugin install` options -MCP servers install from a policy-configured registry, which requires authentication and interactive secret entry. Use the **Online** view of the `/mcp` dashboard to add MCP servers instead of `copilot plugins install`. +To install a skill instead of a plugin, use [`copilot skill add`](/copilot/reference/copilot-cli-reference/cli-command-reference#managing-skills-non-interactively) instead—it isn't a plugin install and doesn't go through a marketplace. -### `copilot plugins update` options +| Option | Description | +|------------------------|------------------------------------------------------------------------------------| +| `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. | + +MCP servers install from a policy-configured registry, which requires authentication and interactive secret entry. Use the **Online** view of the `/mcp` dashboard, or the [`copilot mcp add`](/copilot/reference/copilot-cli-reference/cli-command-reference#copilot-mcp-subcommand) command, to add MCP servers instead of `copilot plugin install`. + +### `copilot plugin update` options | Option | Description | |-----------|-----------------------------------------| | `--all` | Update every installed plugin | +| `--config-dir=DIRECTORY` | Path to the configuration directory. This option is deprecated. Use `COPILOT_HOME` instead. | > [!NOTE] > Path-sourced plugins in a local (directory-source) marketplace load live from their real directory—editing one takes effect on `/restart` or in a new session, with no `copilot plugin update` needed. @@ -81,7 +95,7 @@ A marketplace you've added yourself can opt into the same session-start auto-upd In interactive mode, `/plugin` flags an installed plugin or marketplace when a newer version is available upstream, and offers an **Update** action from the dashboard to pull it. -### `copilot plugins marketplace` subcommands +### `copilot plugin marketplace` (alias `marketplaces`) subcommands Built-in default marketplaces ship with the runtime and can't be removed. diff --git a/content/copilot/tutorials/copilot-cli-hooks.md b/content/copilot/tutorials/copilot-cli-hooks.md index 1230fbdad344..6e537908575c 100644 --- a/content/copilot/tutorials/copilot-cli-hooks.md +++ b/content/copilot/tutorials/copilot-cli-hooks.md @@ -399,15 +399,6 @@ fi COMMAND="$(echo "$TOOL_ARGS_RAW" | jq -r '.command // empty')" -# --------------------------------------------------------------------------- -# Demo-only deny rule for safe testing. -# This blocks a harmless test command so you can validate the deny flow. -# Remove this rule after confirming your hooks work as expected. -# --------------------------------------------------------------------------- -if echo "$COMMAND" | grep -q "COPILOT_HOOKS_DENY_DEMO"; then - deny "Blocked demo command (test rule). Remove this rule after validating hooks." -fi - deny() { local reason="$1" @@ -436,6 +427,15 @@ deny() { exit 0 } +# --------------------------------------------------------------------------- +# Demo-only deny rule for safe testing. +# This blocks a harmless test command so you can validate the deny flow. +# Remove this rule after confirming your hooks work as expected. +# --------------------------------------------------------------------------- +if echo "$COMMAND" | grep -q "COPILOT_HOOKS_DENY_DEMO"; then + deny "Blocked demo command (test rule). Remove this rule after validating hooks." +fi + # Privilege escalation if echo "$COMMAND" | grep -qE '\b(sudo|su|runas)\b'; then deny "Privilege escalation requires manual approval." diff --git a/data/reusables/enterprise-accounts/enterprise-apps-capabilities.md b/data/reusables/enterprise-accounts/enterprise-apps-capabilities.md index 92167705bd5f..8fa813f053ac 100644 --- a/data/reusables/enterprise-accounts/enterprise-apps-capabilities.md +++ b/data/reusables/enterprise-accounts/enterprise-apps-capabilities.md @@ -7,6 +7,9 @@ Enterprise-installed {% data variables.product.prodname_github_apps %} cannot ca {%- ifversion enterprise-billing-github-app %} * Manage enterprise billing, including budgets, cost centers, and usage reports. For more information, see [AUTOTITLE](/rest/billing). {%- endif %} +{%- ifversion ghec %} +* Authorize {% data variables.product.pat_v1_plural %} and verified, user-owned SSH authentication keys for SSO in selected organizations. See [AUTOTITLE](/authentication/authenticating-with-single-sign-on/authorizing-credentials-for-single-sign-on-with-a-github-app). +{%- endif %} * Call the enterprise SCIM APIs Check the [changelog](https://github.blog/changelog/) for updates on new APIs and permissions for {% data variables.product.prodname_github_apps %}. diff --git a/src/content-pipelines/state/copilot-cli.sha b/src/content-pipelines/state/copilot-cli.sha index dcbb3c91d1b3..43f24c9f055d 100644 --- a/src/content-pipelines/state/copilot-cli.sha +++ b/src/content-pipelines/state/copilot-cli.sha @@ -1 +1 @@ -bc65d3739bbe4d7f9832b2bceea9d03f633b6d0b +2a544262cc3ef9298fa36c38bcfc454d625d0888