Copilot CLI docs should clarify enabledPlugins for non-default marketplaces also requires extraKnownMarketplaces

[mohammadrayan]

What needs clarification

The current Copilot plugin docs say you can declaratively install plugins for Copilot CLI by adding entries to enabledPlugins in ~/.copilot/settings.json or .github/copilot/settings.json.

In practice, for plugins that come from a non-default marketplace, that is not sufficient by itself. The marketplace also needs to be registered via extraKnownMarketplaces (or copilot plugin marketplace add).

Without that, the behavior is confusing:

• gh copilot -- plugin list can show the plugin as installed
• but nothing is materialized under ~/.copilot/installed-plugins/
• and VS Code therefore does not auto-discover it via the documented CLI plugin integration

Reproduction

Environment:

• macOS
• VS Code 1.127.0
• GitHub Copilot CLI 1.0.68

Starting state in ~/.copilot/settings.json:

{
  "enabledPlugins": {
    "bv-dev-workflow@bv-ai-assets": true
  }
}

Observed state:

1. gh copilot -- plugin list reported:

Installed plugins:
  • bv-dev-workflow@bv-ai-assets (v2.2.0)

2. But the marketplace was not actually registered:

gh copilot -- plugin marketplace list

did not include bv-ai-assets.

3. The documented install directory was empty:

~/.copilot/installed-plugins/

4. VS Code did not show the plugin as installed automatically.

After registering the marketplace explicitly:

gh copilot -- plugin marketplace add bluevine-dev/bv-ai-assets
gh copilot -- plugin install bv-dev-workflow@bv-ai-assets

then the plugin was materialized under:

~/.copilot/installed-plugins/bv-ai-assets/bv-dev-workflow

and the behavior aligned with the VS Code docs.

Why this is confusing

The docs currently make it easy to read enabledPlugins as sufficient for declarative installation in CLI, but for non-default marketplaces there also appears to be a dependency on marketplace registration.

Also, gh copilot -- plugin list appearing to report the plugin as installed before anything exists in ~/.copilot/installed-plugins/ makes this hard to diagnose.

Suggested doc improvement

In the CLI plugin installation docs, explicitly state that:

• if a plugin comes from a marketplace other than the default built-in marketplaces
• you must also register that marketplace in config (for example via extraKnownMarketplaces or copilot plugin marketplace add)
• otherwise enabledPlugins alone may not materialize the plugin on disk for cross-client discovery

It may also help to add a note explaining the difference between:

• being listed in config as enabled
• being physically installed under ~/.copilot/installed-plugins/

Related docs

• Copilot CLI plugin install docs
• VS Code agent plugins docs section: "Plugins installed by GitHub Copilot CLI"

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[mohammadrayan]

Closing this because my reproduction was confounded by manual local Copilot CLI marketplace/plugin registration on the test machine, so it does not isolate the enterprise-managed plugin rollout path this report was meant to describe.