docs/content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md at 888d38f84beab6ecd57f76930f2f2afd7cdc080f · github/docs

title

GitHub Copilot CLI plugin reference

shortTitle

CLI plugin reference

intro

Find commands and configuration details for CLI plugins.

versions

feature
copilot

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.

Command	Description
`copilot plugin install SPECIFICATION`	Install a plugin. See Plugin specification for `install` command below.
`copilot plugin uninstall NAME`	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
`copilot plugin disable NAME`	Disable a plugin without uninstalling it
`copilot plugin marketplace add SPECIFICATION`	Register a marketplace. The marketplace's own name, from its `marketplace.json` manifest, becomes its registration key—there is no option to set a custom local name.
`copilot plugin marketplace list`	List registered marketplaces
`copilot plugin marketplace browse NAME`	Browse marketplace plugins
`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 for the non-interactive --mcp and --skill kinds, which extend these commands to MCP servers and skills.

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.

Plugin specification for `install` command

Format	Example	Description
Marketplace	`plugin@marketplace`	Plugin from a registered marketplace
{% data variables.product.github %}	`OWNER/REPO`	Root of a {% data variables.product.github %} repository
{% data variables.product.github %} subdir	`OWNER/REPO:PATH/TO/PLUGIN`	Subdirectory in a repository
Git URL	`https://github.com/o/r.git`	Any Git URL
Local path	`./my-plugin` or `/abs/path`	Local directory

`copilot plugins install` options

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 for details on skills themselves.

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.

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.

`copilot plugins update` options

Option	Description
`--all`	Update every installed plugin

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.

First-party plugins—those installed from the built-in copilot-plugins and awesome-copilot marketplaces—automatically update at the start of each session in a trusted working directory. Disable this behavior with the autoUpdate setting (set to false) or the COPILOT_AUTO_UPDATE=false environment variable. Auto-update is also skipped by default in CI. See AUTOTITLE.

A marketplace you've added yourself can opt into the same session-start auto-update by setting autoUpdate: true on its extraKnownMarketplaces entry in your user settings. This opt-in applies only to interactive and -p sessions—SDK and server sessions don't auto-update. It is honored from your own user settings or from managed (MDM/server) settings, but a repository-level autoUpdate setting is accepted and ignored—it can't enable or redirect auto-update for a marketplace. On a same-name collision, a built-in first-party marketplace wins, then a managed entry (which replaces the whole same-named user entry, so a managed entry without "autoUpdate": true removes the user's opt-in), then the user's own entry. See Repository settings.

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

Built-in default marketplaces ship with the runtime and can't be removed.

Subcommand	Description
`list [--json]`	List every registered marketplace, including built-in defaults
`add SOURCE`	Add a marketplace (`owner/repo`, `owner/repo#ref`, a URL, or a local path)
`remove NAME [--force]`	Remove a marketplace; `--force` also uninstalls plugins sourced from it
`browse NAME [--json]`	List the plugins offered by a marketplace's catalog
`update [NAME]` (alias `refresh`)	Refresh the plugin catalog for one marketplace, or all if `NAME` is omitted

In interactive mode, run /plugin marketplace update [NAME] (alias /plugin marketplace refresh), or press R in the Marketplace view of the /plugin dashboard, to refresh every registered marketplace's catalog.

`plugin.json`

All plugins consist of a plugin directory containing, at minimum, a manifest file named plugin.json located at the root of the plugin directory. See AUTOTITLE.

Required field

Field	Type	Description
`name`	string	Kebab-case plugin name (letters, numbers, hyphens only). Max 64 chars. Plugins that opt into Open Plugin Spec support may also use dots (for example, `acme.tools`).

Optional metadata fields

Field	Type	Description
`$schema`	string	Set to the canonical Agent Plugins (Open Plugin Spec) v1.0.0 schema URL to opt into spec semantics. See Open Plugin Spec support.
`description`	string	Brief description. Max 1024 chars.
`version`	string	Semantic version (e.g., `1.0.0`).
`author`	object	`name` (required), `email` (optional), `url` (optional).
`homepage`	string	Plugin homepage URL.
`repository`	string	Source repository URL.
`license`	string	License identifier (e.g., `MIT`).
`keywords`	string[]	Search keywords.
`category`	string	Plugin category.
`tags`	string[]	Additional tags.

Component path fields

These tell the CLI where to find your plugin's components. All are optional. The CLI uses default conventions if omitted.

Field	Type	Default	Description
`agents`	string \| string[]	`agents/`	Path(s) to agent directories (`.agent.md` files).
`skills`	string \| string[]	`skills/`	Path(s) to skill directories (`SKILL.md` files).
`commands`	string \| string[]	—	Path(s) to command directories.
`hooks`	string \| object	—	Path to a hooks configuration file, or an inline hooks object.
`extensions`	string \| string[] \| object	—	Path(s) to extension directories. Use `{ paths: [...], exclusive: true }` to suppress built-in extensions. In Open Plugin Spec mode, this field has a different meaning.
`mcpServers`	string \| object	—	Path to an MCP configuration file (e.g., `.mcp.json`), or inline server definitions.
`lspServers`	string \| object	—	Path to an LSP configuration file, or inline server definitions.

Example `plugin.json` file

{% data reusables.copilot.copilot-cli.cli-example-plugin-file %}

Open Plugin Spec support

Declaring the canonical $schema in plugin.json opts a plugin into the Agent Plugins (Open Plugin Spec) v1.0.0 format, additively on top of standard plugin loading:

LSP server configuration

To include LSP (Language Server Protocol) servers in a plugin, create a lsp-config/servers.json file in the plugin directory, or specify a path or inline object using the lspServers field in plugin.json.

Example lsp-config/servers.json (or inline via lspServers in plugin.json):

{
    "lspServers": {
        "my-lsp": {
            "command": "my-language-server",
            "fileExtensions": { ".myext": "mylang" }
        }
    }
}

For cross-platform support, use bash and powershell instead of command:

{
    "lspServers": {
        "my-lsp": {
            "bash": "${PLUGIN_ROOT}/scripts/start-lsp.sh",
            "powershell": "${PLUGIN_ROOT}/scripts/start-lsp.ps1",
            "fileExtensions": { ".myext": "mylang" }
        }
    }
}

Field	Type	Required	Description
`command`	string	*	Executable to launch the language server.
`bash`	string	*	Bash script to launch the server (Linux/macOS); executed via `bash -c SCRIPT`.
`powershell`	string	*	PowerShell script to launch the server (Windows); executed via `pwsh -c SCRIPT`.
`cwd`	string	No	Working directory. Absolute or relative to the configuration file. Supports `${PLUGIN_ROOT}`.
`args`	string[]	No	Arguments to pass to `command` (ignored for `bash` and `powershell`).
`env`	object	No	Environment variables to set when spawning the server.
`fileExtensions`	object	Yes	Map of file extensions to language IDs (for example, `{ ".ts": "typescript" }`).
`rootUri`	string	No	Project root relative to the git root (default: `.`).
`initializationOptions`	any	No	Options sent to the server in the LSP `initialize` request.

(*) At least one of command, bash, or powershell is required. When both bash and powershell are specified, the platform-appropriate one is selected automatically (PowerShell on Windows, Bash elsewhere).

Use ${PLUGIN_ROOT} to reference paths within the plugin directory.

`marketplace.json`

You can create a plugin marketplace—which people can use to discover and install your plugins—by creating a marketplace.json file and saving it to the .github/plugin/ directory of the repository. You can also store the marketplace.json file in your local file system. For example, saving the file as /PATH/TO/my-marketplace/.github/plugin/marketplace.json allows you to add it to the CLI using the following command:

copilot plugin marketplace add /PATH/TO/my-marketplace

{% data reusables.copilot.copilot-cli.cli-claude-plugin-dir %}

For more information, see AUTOTITLE.

Example `marketplace.json` file

{% data reusables.copilot.copilot-cli.cli-example-marketplace-file %}

Note

{% data reusables.copilot.copilot-cli.cli-path-to-plugins %}

`marketplace.json` fields

Top-level fields

Field	Type	Required	Description
`name`	string	Yes	Kebab-case marketplace name. Max 64 chars. Dots are also accepted (for example, `acme.tools`) for Open Plugin Spec plugins.
`owner`	object	Yes	`{ name, email? }` — marketplace owner info.
`plugins`	array	Yes	List of plugin entries (see the table below).
`metadata`	object	No	`{ description?, version?, pluginRoot? }`

Plugin entry fields (objects within the `plugins` array)

Field	Type	Required	Description
`name`	string	Yes	Kebab-case plugin name. Max 64 chars. Dots are also accepted for Open Plugin Spec plugins.
`source`	string \| object	Yes	Where to fetch the plugin (relative path, {% data variables.product.github %}, or URL).
`description`	string	No	Plugin description. Max 1024 chars.
`version`	string	No	Plugin version.
`author`	object	No	`{ name, email?, url? }`
`homepage`	string	No	Plugin homepage URL.
`repository`	string	No	Source repository URL.
`license`	string	No	License identifier.
`keywords`	string[]	No	Search keywords.
`category`	string	No	Plugin category.
`tags`	string[]	No	Additional tags.
`commands`	string \| string[]	No	Path(s) to command directories.
`agents`	string \| string[]	No	Path(s) to agent directories.
`skills`	string \| string[]	No	Path(s) to skill directories.
`hooks`	string \| object	No	Path to hooks configuration or inline hooks object.
`mcpServers`	string \| object	No	MCP servers to activate when the plugin is installed. Accepts an inline server map or a path to a JSON configuration file. Used when the plugin source does not ship its own MCP configuration.
`lspServers`	string \| object	No	Path to LSP configuration or inline server definitions.
`strict`	boolean	No	When `true` (the default), plugins must conform to the full schema and validation rules. When `false`, relaxed validation is used, allowing more flexibility—especially for direct installs or legacy plugins.

Plugin source types

The source field on a plugin entry accepts a relative path string, or an object describing a {% data variables.product.github %} repository or Git URL source:

{
    "source": {
        "source": "github",
        "repo": "owner/repo",
        "ref": "v1.0.0",
        "path": "plugins/my-plugin"
    }
}

Both the github and url source types accept an optional sha field to pin installs to an exact commit, in addition to (or instead of) ref:

{
    "source": {
        "source": "github",
        "repo": "owner/repo",
        "sha": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
        "path": "plugins/my-plugin"
    }
}

sha must be a full 40-character commit SHA. Pin to a sha for reproducible installs that are immune to force-pushes or tag/branch moves.

File locations

Item	Path
Installed plugins	`~/.copilot/installed-plugins/MARKETPLACE/PLUGIN-NAME` (installed via a marketplace) and `~/.copilot/installed-plugins/_direct/SOURCE-ID/` (installed directly)
Marketplace cache	Platform cache directory: `~/.cache/copilot/marketplaces/` (Linux), `~/Library/Caches/copilot/marketplaces/` (macOS). Overridable with `COPILOT_CACHE_HOME`.
Plugin manifest	`.plugin/plugin.json`, `plugin.json`, `.github/plugin/plugin.json`, or `.claude-plugin/plugin.json` (checked in this order)
Marketplace manifest	`marketplace.json`, `.plugin/marketplace.json`, `.github/plugin/marketplace.json`, or `.claude-plugin/marketplace.json` (checked in this order)
Agents	`agents/` (default, overridable in manifest)
Skills	`skills/` (default, overridable in manifest)
Hooks configuration	`hooks.json` or `hooks/hooks.json`
MCP configuration	`.mcp.json`, `.github/mcp.json`
LSP configuration	`lsp.json` or `.github/lsp.json`
Plugin data	`${COPILOT_PLUGIN_DATA}` (also available as `${CLAUDE_PLUGIN_DATA}`). Points to a persistent, writable directory unique to each installed plugin. Use this for plugin-specific runtime data instead of paths inside the installed-plugins cache directory.

Loading order and precedence

If you install multiple plugins it's possible that some custom agents, skills, MCP servers, or tools supplied via MCP servers have duplicate names. In this situation, the CLI determines which component to use based on a precedence order.

Agents and skills use first-found-wins precedence.

If you have a project-level custom agent or skill with the same name or ID as one in a plugin you install, the agent or skill in the plugin is silently ignored. The plugin cannot override project-level or personal configurations. Custom agents are deduplicated using their ID, which is derived from its file name (for example, if the file is named reviewer.agent.md, the agent ID is reviewer). Skills are deduplicated by their name field inside the SKILL.md file.
MCP servers use last-wins precedence.

If you install a plugin that defines an MCP server with the same server name as an MCP server you have already installed, the plugin's definition takes precedence. You can use the --additional-mcp-config command-line option to override an MCP server configuration with the same name, installed using a plugin. If two or more plugins declare an MCP server with the same name, the CLI uses the version from the plugin that loaded last and shows a warning naming every prior plugin that defined it.
Built-in tools and agents are always present and cannot be overridden by user-defined components.

The following diagram illustrates the loading order and precedence rules.

┌──────────────────────────────────────────────────────────────────┐
│  BUILT-IN - HARDCODED, ALWAYS PRESENT                            │
│  • tools: bash, view, apply_patch, glob, rg, task, ...           │
│  • agents: explore, task, code-review, general-purpose, research │
└────────────────────────┬─────────────────────────────────────────┘
                         │
  ┌──────────────────────▼──────────────────────────────────────────────┐
  │  CUSTOM AGENTS - FIRST LOADED IS USED (dedup by ID)                 │
  │  1. ~/.copilot/agents/           (user, .github convention)         │
  │  2. <project>/.github/agents/    (project)                          │
  │  3. <parents>/.github/agents/    (inherited, monorepo)              │
  │  4. <project>/.claude/agents/    (project)                          │
  │  5. <parents>/.claude/agents/    (inherited, monorepo)              │
  │  6. PLUGIN: agents/ dirs         (plugin, by install order)         │
  │  7. Remote org/enterprise agents (remote, via API)                  │
  └──────────────────────┬──────────────────────────────────────────────┘
                         │
  ┌──────────────────────▼──────────────────────────────────────────────┐
  │  AGENT SKILLS - FIRST LOADED IS USED (dedup by name)                │
  │  1. <project>/.github/skills/        (project)                      │
  │  2. <project>/.agents/skills/        (project)                      │
  │  3. <project>/.claude/skills/        (project)                      │
  │  4. <parents>/.github/skills/ etc.   (inherited)                    │
  │  5. ~/.copilot/skills/               (personal-copilot)             │
  │  6. ~/.agents/skills/                (personal-agents)              │
  │  7. PLUGIN: skills/ dirs             (plugin)                       │
  │  8. COPILOT_SKILLS_DIRS env + config (custom)                       │
  │  --- then commands (.claude/commands/), skills override commands ---│
  └──────────────────────┬──────────────────────────────────────────────┘
                         │
  ┌──────────────────────▼──────────────────────────────────────────────┐
  │  MCP SERVERS - LAST LOADED IS USED (dedup by server name)           │
  │  1. ~/.copilot/mcp-config.json       (lowest priority)              │
  │  2. PLUGIN: MCP configs              (plugins)                      │
  │  3. --additional-mcp-config flag     (highest priority)             │
  └─────────────────────────────────────────────────────────────────────┘

Navigation Menu

Uh oh!

CLI commands

Plugin specification for `install` command

`copilot plugins install` options

`copilot plugins update` options

`copilot plugins marketplace` subcommands

`plugin.json`

Required field

Optional metadata fields

Component path fields

Example `plugin.json` file

Open Plugin Spec support

LSP server configuration

`marketplace.json`

Example `marketplace.json` file

`marketplace.json` fields

Top-level fields

Plugin entry fields (objects within the `plugins` array)

Plugin source types

File locations

Loading order and precedence

Further reading

Uh oh!

FilesExpand file tree

cli-plugin-reference.md

Latest commit

History

cli-plugin-reference.md

File metadata and controls

CLI commands

Plugin specification for install command

copilot plugins install options

copilot plugins update options

copilot plugins marketplace subcommands

plugin.json

Required field

Optional metadata fields

Component path fields

Example plugin.json file

Open Plugin Spec support

LSP server configuration

marketplace.json

Example marketplace.json file

marketplace.json fields

Top-level fields

Plugin entry fields (objects within the plugins array)

Plugin source types

File locations

Loading order and precedence

Further reading

Plugin specification for `install` command

`copilot plugins install` options

`copilot plugins update` options

`copilot plugins marketplace` subcommands

`plugin.json`

Example `plugin.json` file

`marketplace.json`

Example `marketplace.json` file

`marketplace.json` fields

Plugin entry fields (objects within the `plugins` array)