Host and maintain a marketplace changedplugins/host-marketplace
Upstream edited this page at 10 Oct 2026 18:15 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 23 Oct 2026 19:07 UTC.
Upstream edited
Recorded here
Lines+52added
Lines−52removed
From line
10
where the diff opens
First seen
25 Sep 2026
this site's first read of the page
Recorded edits12to this page, all time
The whole hunk
from line 10, old and new numbered
/
from line 10
1010>
1111> These cases are covered on other pages:
1212>
13> * **You haven't written the catalog file yet**: start with [Create a marketplace](/docs/en/plugins/create-marketplace.md)
14> * **You're an admin requiring, restricting, or pre-installing marketplaces across your organization's machines**: read [Manage plugins for your organization](/docs/en/plugins/org.md)
13> * **You haven't written the catalog file yet**: start with [Create a marketplace](https://code.claude.com/docs/en/plugins/create-marketplace.md)
14> * **You're an admin requiring, restricting, or pre-installing marketplaces across your organization's machines**: read [Manage plugins for your organization](https://code.claude.com/docs/en/plugins/org.md)
1515
1616Start with [Host your marketplace](#host-your-marketplace) to pick a host and the command your users run. Read [Keep users up to date](#keep-users-up-to-date) before your first release. Read [Rename or remove a plugin](#rename-or-remove-a-plugin) before you change a plugin's `name`.
1717
from line 26
2626| A hosted `marketplace.json` URL | `/plugin marketplace add https://plugins.example.com/marketplace.json` | HTTPS access to the URL. Users don't need `git` for the catalog itself |
2727| A directory on a shared filesystem | `/plugin marketplace add /Volumes/shared/claude-plugins` | Read access to the path |
2828
29To pin a branch or tag of a GitHub or git-URL marketplace, tell users to append `#<ref>`, as in `your-org/your-marketplace#stable`. The [plugin commands reference](/docs/en/plugins/cli-reference.md#plugin-marketplace-add) lists every form the command accepts.
29To pin a branch or tag of a GitHub or git-URL marketplace, tell users to append `#<ref>`, as in `your-org/your-marketplace#stable`. The [plugin commands reference](https://code.claude.com/docs/en/plugins/cli-reference.md#plugin-marketplace-add) lists every form the command accepts.
3030
3131A successful add prints `Successfully added marketplace: your-marketplace`. Claude Code takes that name from the `name` field in your `marketplace.json`, not from the repository name.
3232
from line 34
3434
3535### Register the marketplace for everyone in a repository
3636
37To share the marketplace with everyone who works in one repository, run `claude plugin marketplace add your-org/your-marketplace --scope project` there once from your shell and commit the `.claude/settings.json` it writes. Claude Code then registers the marketplace for each teammate who [trusts the folder](/docs/en/plugins/org.md#require-plugins-per-repository).
37To share the marketplace with everyone who works in one repository, run `claude plugin marketplace add your-org/your-marketplace --scope project` there once from your shell and commit the `.claude/settings.json` it writes. Claude Code then registers the marketplace for each teammate who [trusts the folder](https://code.claude.com/docs/en/plugins/org.md#require-plugins-per-repository).
3838
3939### Avoid relative-path entries in a URL-hosted marketplace
4040
41When users add your marketplace as a bare `marketplace.json` URL, Claude Code downloads only that file. An entry in your `plugins` array whose `source` is a relative path such as `./plugins/formatter` then fails at install with [`its marketplace entry path does not stay inside the marketplace directory`](/docs/en/plugins/troubleshooting#plugins-with-relative-paths-fail-in-url-based-marketplaces). Give every entry a source that can be fetched on its own, such as a `github` repository or an `archive` URL, or host the marketplace in a git repository so Claude Code clones the whole tree.
41When users add your marketplace as a bare `marketplace.json` URL, Claude Code downloads only that file. An entry in your `plugins` array whose `source` is a relative path such as `./plugins/formatter` then fails at install with [`its marketplace entry path does not stay inside the marketplace directory`](https://code.claude.com/docs/en/plugins/troubleshooting#plugins-with-relative-paths-fail-in-url-based-marketplaces). Give every entry a source that can be fetched on its own, such as a `github` repository or an `archive` URL, or host the marketplace in a git repository so Claude Code clones the whole tree.
4242
4343### Stay within the download limits for hosted files
4444
45When users add your marketplace as a `marketplace.json` URL, or install an entry with an [`archive`](/docs/en/plugins/marketplace-reference#archive-plugin-source) source, Claude Code downloads the file from your server. The download fails past the limits in this table, so size your files and configure your server to stay inside them.
45When users add your marketplace as a `marketplace.json` URL, or install an entry with an [`archive`](https://code.claude.com/docs/en/plugins/marketplace-reference#archive-plugin-source) source, Claude Code downloads the file from your server. The download fails past the limits in this table, so size your files and configure your server to stay inside them.
4646
4747| File | Largest download | Time for your server to respond | Redirects |
4848| :- | :- | :- | :- |
from line 74
7474* **Elsewhere within the same marketplace**: the symlink is dereferenced. The target's content is copied into the cache in its place. This lets a meta-plugin's `skills/` directory link to skills defined by other plugins in the marketplace.
7575* **Outside the marketplace**: the symlink is skipped for security.
7676
77For plugins installed from a local path, or from a [`command` source](/docs/en/plugins/marketplace-reference#command-plugin-source) whose `mode` is the default `copy`, Claude Code preserves only symlinks that resolve within the plugin's own directory and skips all others.
77For plugins installed from a local path, or from a [`command` source](https://code.claude.com/docs/en/plugins/marketplace-reference#command-plugin-source) whose `mode` is the default `copy`, Claude Code preserves only symlinks that resolve within the plugin's own directory and skips all others.
7878
7979The following command creates a link from inside a marketplace plugin to a shared skill defined by a sibling plugin. On Windows, use `mklink /D` from an elevated Command Prompt or enable Developer Mode:
8080
from line 89
8989Organization sync is stricter about the repository than `/plugin marketplace add` is:
9090
9191* **Marketplace repository**: on github.com and gitlab.com, it must be private or internal
92* **Plugin sources**: organization sync accepts only some [source types](/docs/en/plugins/marketplace-reference.md#plugin-sources)
92* **Plugin sources**: organization sync accepts only some [source types](https://code.claude.com/docs/en/plugins/marketplace-reference.md#plugin-sources)
9393* **Top-level `bin/` directory**: claude.ai rejects a plugin that has one and syncs the rest of the marketplace. The error message starts with `Plugin contains a top-level bin/ directory`. Keep executables in another directory, such as `scripts/`, and reference them as `${CLAUDE_PLUGIN_ROOT}/scripts/<name>` from your hooks or MCP server configs
9494
9595[Sync your organization's plugins from a repository](https://claude.com/docs/plugins/org-sync) on claude.com lists the accepted sources, the GitLab setup, and the `bin/` error, and [Manage plugins for your organization](https://claude.com/docs/plugins/admin) covers the admin workflow.
from line 109
109109* **SSH**: the key must work without a passphrase prompt, for example because it's loaded in `ssh-agent`. The host must already be in `known_hosts`.
110110* **HTTPS**: Claude Code leaves the user's git credential helper enabled but forbids it from prompting. A credential the helper already stores works; one it would have to ask for fails. On GitHub, `gh auth login` followed by `gh auth setup-git` stores one.
111111
112For a GitHub Enterprise Server host, users need git access to that host from their machine. See [Plugin marketplaces on GHES](/docs/en/github-enterprise-server.md#plugin-marketplaces-on-ghes) for what each Claude Code surface needs to reach a GHES-hosted marketplace.
112For a GitHub Enterprise Server host, users need git access to that host from their machine. See [Plugin marketplaces on GHES](https://code.claude.com/docs/en/github-enterprise-server.md#plugin-marketplaces-on-ghes) for what each Claude Code surface needs to reach a GHES-hosted marketplace.
113113
114114If you distribute through **Organization settings > Plugins & skills** on claude.ai instead, your users' git credentials aren't involved. See [Distribute through organization settings](#distribute-through-organization-settings).
115115
from line 139
139139After the check, Claude Code does one of the following:
140140
141141* **The checkout is up to date**: Claude Code leaves it as it is.
142* **The check finds new commits, or fails because it can't reach or authenticate to the remote**: Claude Code clones the marketplace again and replaces the existing checkout with the new clone. If that clone fails, the existing checkout stays in place. The re-clone can [time out on large repositories](/docs/en/plugins/troubleshooting.md#git-clone-timed-out-after-120s).
142* **The check finds new commits, or fails because it can't reach or authenticate to the remote**: Claude Code clones the marketplace again and replaces the existing checkout with the new clone. If that clone fails, the existing checkout stays in place. The re-clone can [time out on large repositories](https://code.claude.com/docs/en/plugins/troubleshooting.md#git-clone-timed-out-after-120s).
143143
144144To keep a private marketplace current, a user can do either of the following:
145145
from line 155
155155| Who | What they do | Where it's covered |
156156| :- | :- | :- |
157157| You, the marketplace owner | Keep the catalog in a repository only the company can read, send the add command for your host, and say what each person needs on their machine | [Host your marketplace](#host-your-marketplace) and [Grant access to a private marketplace](#grant-access-to-a-private-marketplace) |
158| An administrator | Registers the marketplace and turns its plugins on for everyone with `extraKnownMarketplaces` and `enabledPlugins` in managed settings, and sets `autoUpdate` there | [Require a marketplace and its plugins](/docs/en/plugins/org.md#require-a-marketplace-and-its-plugins) and [Set update policy](/docs/en/plugins/org.md#set-update-policy) |
159| Each person | Needs read access to a private git repository, with credentials already stored on their machine. Without an administrator, they also run the add and install commands | [Add a private marketplace](/docs/en/plugins/install.md#add-a-private-marketplace) |
158| An administrator | Registers the marketplace and turns its plugins on for everyone with `extraKnownMarketplaces` and `enabledPlugins` in managed settings, and sets `autoUpdate` there | [Require a marketplace and its plugins](https://code.claude.com/docs/en/plugins/org.md#require-a-marketplace-and-its-plugins) and [Set update policy](https://code.claude.com/docs/en/plugins/org.md#set-update-policy) |
159| Each person | Needs read access to a private git repository, with credentials already stored on their machine. Without an administrator, they also run the add and install commands | [Add a private marketplace](https://code.claude.com/docs/en/plugins/install.md#add-a-private-marketplace) |
160160
161161For people who have no git-host account, these sections each cover one way to reach them:
162162
163163* **Entry sources that need no git account**: [Serve users who have no git-host account](#serve-users-who-have-no-git-host-account)
164* **A pre-populated plugins directory**: [Seed containers and CI](/docs/en/plugins/org.md#seed-containers-and-ci), which also serves users who have no git-host account
164* **A pre-populated plugins directory**: [Seed containers and CI](https://code.claude.com/docs/en/plugins/org.md#seed-containers-and-ci), which also serves users who have no git-host account
165165* **claude.ai organization settings**: [Distribute through organization settings](#distribute-through-organization-settings), where your users' git credentials aren't involved
166166
167167## Keep users up to date
from line 173
173173Background auto-update is off for your marketplace by default, and `marketplace.json` has no field to turn it on. A user or an admin turns it on:
174174
175175* **Tell users to turn it on**: each user goes to **Marketplaces** in `/plugin`, selects your marketplace, and selects **Enable auto-update**.
176* **Ask an admin to set it**: if an admin sets `"autoUpdate": true` on your marketplace's `extraKnownMarketplaces` entry in managed settings, it's on for everyone who receives those settings. See [Set update policy](/docs/en/plugins/org.md#set-update-policy).
176* **Ask an admin to set it**: if an admin sets `"autoUpdate": true` on your marketplace's `extraKnownMarketplaces` entry in managed settings, it's on for everyone who receives those settings. See [Set update policy](https://code.claude.com/docs/en/plugins/org.md#set-update-policy).
177177
178178Without auto-update, users receive your changes when they run `/plugin marketplace update <name>` in a session or `claude plugin update <plugin>@<name>` in the shell.
179179
180For what users see when an update reaches them, see [When auto-update runs](/docs/en/plugins/loading.md#when-auto-update-runs).
180For what users see when an update reaches them, see [When auto-update runs](https://code.claude.com/docs/en/plugins/loading.md#when-auto-update-runs).
181181
182182### Release a new version
183183
184To release a new version to users, change the plugin's `version`. Users get a new copy only when the plugin's computed version differs from the one they have. That version comes from `plugin.json` first, then from the marketplace entry, per [Versions and updates](/docs/en/plugins/loading.md#versions-and-updates).
184To release a new version to users, change the plugin's `version`. Users get a new copy only when the plugin's computed version differs from the one they have. That version comes from `plugin.json` first, then from the marketplace entry, per [Versions and updates](https://code.claude.com/docs/en/plugins/loading.md#versions-and-updates).
185185
186A plugin that users [load in place](/docs/en/plugins/loading.md#find-plugins-on-disk) from a marketplace they added from a local path isn't controlled by `version`. It loads your current files at every session start, whatever its version string says.
186A plugin that users [load in place](https://code.claude.com/docs/en/plugins/loading.md#find-plugins-on-disk) from a marketplace they added from a local path isn't controlled by `version`. It loads your current files at every session start, whatever its version string says.
187187
188188For every install other than an in-place load or one from a `command` source, either increase `version` on each release or omit it:
189189
from line 196
196196
197197One marketplace serves one version of each plugin at a time, so you hold users on a version by choosing what each entry points at:
198198
199* **`ref` and `sha` on the plugin entry**: `ref` names a branch or tag and `sha` names a commit for a `github`, `url`, or `git-subdir` source. See [Plugin sources](/docs/en/plugins/marketplace-reference.md#plugin-sources).
199* **`ref` and `sha` on the plugin entry**: `ref` names a branch or tag and `sha` names a commit for a `github`, `url`, or `git-subdir` source. See [Plugin sources](https://code.claude.com/docs/en/plugins/marketplace-reference.md#plugin-sources).
200200* **`#<ref>` on the add command**: users who add `your-org/your-marketplace#stable` get that branch or tag of the catalog. For two release lines at once, see [Run release channels](#run-release-channels).
201* **`<plugin>--v<version>` tags**: a dependency's version range resolves against these tags. See [Release a plugin that others depend on](/docs/en/plugins/dependencies.md#tag-plugin-releases-for-version-resolution).
201* **`<plugin>--v<version>` tags**: a dependency's version range resolves against these tags. See [Release a plugin that others depend on](https://code.claude.com/docs/en/plugins/dependencies.md#tag-plugin-releases-for-version-resolution).
202202
203203[Release a new version](#release-a-new-version) says when a changed entry reaches users.
204204
205205### Change the command of a command source
206206
207If you change the `command` of a [`command` source](/docs/en/plugins/marketplace-reference#command-plugin-source), or switch its `mode`, each user has to accept the new command before Claude Code runs it. Claude Code runs only the exact command a user accepted when they installed or last updated the plugin.
207If you change the `command` of a [`command` source](https://code.claude.com/docs/en/plugins/marketplace-reference#command-plugin-source), or switch its `mode`, each user has to accept the new command before Claude Code runs it. Claude Code runs only the exact command a user accepted when they installed or last updated the plugin.
208208
209209After a user's copy of your marketplace picks up the change, that user sees the following:
210210
211* **No more background runs**: the [once-per-session run](/docs/en/plugins/loading.md#when-a-command-source-re-runs) of the command stops for that user, so the tool's new output doesn't reach them.
211* **No more background runs**: the [once-per-session run](https://code.claude.com/docs/en/plugins/loading.md#when-a-command-source-re-runs) of the command stops for that user, so the tool's new output doesn't reach them.
212212* **An entry in the `/plugin` Errors tab**: the entry shows the new command and the `claude plugin update` command to run.
213213
214214Tell users to run the `claude plugin update` command that entry shows, in a terminal. Claude Code shows them the new command and asks them to accept it.
from line 243
243243
244244Give the two refs different `plugin.json` versions, or omit `version` so the commit SHA distinguishes them. Updates are detected by comparing versions, so a ref that moves without a version change leaves users on the cached copy.
245245
246To assign the channels to user groups instead of letting users choose, an admin gives each group the matching `extraKnownMarketplaces` entry, as described under [Set update policy](/docs/en/plugins/org.md#set-update-policy).
246To assign the channels to user groups instead of letting users choose, an admin gives each group the matching `extraKnownMarketplaces` entry, as described under [Set update policy](https://code.claude.com/docs/en/plugins/org.md#set-update-policy).
247247
248248## Rename or remove a plugin
249249
from line 253
253253
254254### Migrate users with a renames map
255255
256When you must change a `name`, add a top-level `renames` map to `marketplace.json` so Claude Code migrates existing users instead of reporting [`Plugin "<name>" not found in marketplace`](/docs/en/plugins/troubleshooting#plugin-not-found-in-marketplace). Do the same when you remove an entry from `plugins`.
256When you must change a `name`, add a top-level `renames` map to `marketplace.json` so Claude Code migrates existing users instead of reporting [`Plugin "<name>" not found in marketplace`](https://code.claude.com/docs/en/plugins/troubleshooting#plugin-not-found-in-marketplace). Do the same when you remove an entry from `plugins`.
257257
258258Map each former name to its current name, or to `null` when the plugin is gone. This marketplace renames `formatter` to `code-formatter` and records that `legacy-linter` was removed:
259259
from line 277
277277* **`null` entry**: the old key is dropped from those scopes and the user sees `Removed from the "your-marketplace" marketplace`.
278278* **Enabled in managed settings**: the plugin still loads under its new name, but Claude Code can't rewrite managed settings, so the notice recurs until an admin updates `enabledPlugins` there.
279279
280For a marketplace users added from a git repository or URL, a renamed plugin reports [`Plugin "<name>" not cached at <path>`](/docs/en/plugins/troubleshooting#plugin-not-cached-at) until the user runs `/plugin install code-formatter@your-marketplace` once in a session.
280For a marketplace users added from a git repository or URL, a renamed plugin reports [`Plugin "<name>" not cached at <path>`](https://code.claude.com/docs/en/plugins/troubleshooting#plugin-not-cached-at) until the user runs `/plugin install code-formatter@your-marketplace` once in a session.
281281
282282Treat `renames` as append-only history. Keep old entries after everyone has migrated. When you rename again, add a second entry rather than editing the first, because Claude Code follows the chain from the oldest name.
283283
from line 293
293293
294294## Authenticate archive downloads
295295
296To authenticate an [`archive`](/docs/en/plugins/marketplace-reference#archive-plugin-source) download, such as a download from a private registry, set the HTTP headers Claude Code sends with it. You can set `headers` in either of these places:
296To authenticate an [`archive`](https://code.claude.com/docs/en/plugins/marketplace-reference#archive-plugin-source) download, such as a download from a private registry, set the HTTP headers Claude Code sends with it. You can set `headers` in either of these places:
297297
298* **The marketplace's `url` source**: the `url` source you registered the marketplace from, such as an [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) entry.
298* **The marketplace's `url` source**: the `url` source you registered the marketplace from, such as an [`extraKnownMarketplaces`](https://code.claude.com/docs/en/settings-reference#extraknownmarketplaces) entry.
299299* **The plugin's entry**: on Claude Code v2.1.238 or later, you can set it on the plugin's `marketplace.json` entry instead, beside `source`.
300300
301301In either place, set a `headersHelper` command instead of `headers` when the value is short-lived, such as a token your registry generates on request. Claude Code runs the command and sends the JSON object it prints as that place's headers. Requires Claude Code v2.1.238 or later.
302302
303The [marketplace reference](/docs/en/plugins/marketplace-reference.md#plugin-entries) lists the `headers` and `headersHelper` entry fields.
303The [marketplace reference](https://code.claude.com/docs/en/plugins/marketplace-reference.md#plugin-entries) lists the `headers` and `headersHelper` entry fields.
304304
305305The place you choose decides which downloads get the headers and when Claude Code runs the command:
306306
from line 313
313313
314314### Add a headersHelper to a plugin entry
315315
316This entry sets `headersHelper` beside `source`. It also sets [`"strict": false`](/docs/en/plugins/marketplace-reference#strict-mode), which Claude Code requires of a `marketplace.json` entry that sets `headersHelper`:
316This entry sets `headersHelper` beside `source`. It also sets [`"strict": false`](https://code.claude.com/docs/en/plugins/marketplace-reference#strict-mode), which Claude Code requires of a `marketplace.json` entry that sets `headersHelper`:
317317
318318```json theme={null}
319319{
from line 336
336336
337337* **Command text**: at most 500 characters of printable ASCII, with no run of four or more spaces.
338338* **Output**: print one JSON object of header names and string values on stdout, then exit 0 within 10 seconds.
339* **Shell and working directory**: Claude Code runs the command through `sh`, or through `cmd.exe` on Windows. The working directory is the configuration directory, which is `~/.claude` or [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars#variables). Give an absolute path or a command on `PATH`, because a relative path resolves against that directory, not the user's project.
340* **Variables Claude Code removes**: when the command is set in a `marketplace.json` entry, or in a project's `.claude/settings.json` or `.claude/settings.local.json`, Claude Code removes from the environment every variable whose name looks like a credential, by the [same rule it applies to an MCP `headersHelper`](/docs/en/mcp#which-variables-a-helper-can-read). `ANTHROPIC_API_KEY` and `MY_REGISTRY_TOKEN` are both removed, so have the command read its credential from a file or a credential store. This removal doesn't apply to a command set in user settings, a `--settings` file, or managed settings.
339* **Shell and working directory**: Claude Code runs the command through `sh`, or through `cmd.exe` on Windows. The working directory is the configuration directory, which is `~/.claude` or [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/en/env-vars#variables). Give an absolute path or a command on `PATH`, because a relative path resolves against that directory, not the user's project.
340* **Variables Claude Code removes**: when the command is set in a `marketplace.json` entry, or in a project's `.claude/settings.json` or `.claude/settings.local.json`, Claude Code removes from the environment every variable whose name looks like a credential, by the [same rule it applies to an MCP `headersHelper`](https://code.claude.com/docs/en/mcp#which-variables-a-helper-can-read). `ANTHROPIC_API_KEY` and `MY_REGISTRY_TOKEN` are both removed, so have the command read its credential from a file or a credential store. This removal doesn't apply to a command set in user settings, a `--settings` file, or managed settings.
341341* **Variables Claude Code sets**: `CLAUDE_CODE_MARKETPLACE_URL` and `CLAUDE_CODE_MARKETPLACE_NAME` for a `url` source's command, and `CLAUDE_CODE_PLUGIN_NAME` and `CLAUDE_CODE_PLUGIN_ARCHIVE_URL` for an entry's command. `CLAUDE_CODE_MARKETPLACE_NAME` is unset on the first fetch after a user adds a marketplace by URL, because that fetch is what supplies the name.
342342
343343A command that mints a bearer token prints an object like this one:
from line 353
353353* **Command fails**: if the command exits non-zero, runs past 10 seconds, or prints anything other than a JSON object of string values, the fetch or download the command was run for doesn't happen.
354354* **Marketplace URL doesn't start with `https://`**: that `url` source's command doesn't run, and requests carry only the headers listed in its `headers` field.
355355* **Redirect leaves the origin**: when a download is redirected off the archive URL's origin, the redirected request carries no `headers` values or command output from either the marketplace `url` source or the plugin entry.
356* **Entry sets a routing or identity header**: Claude Code drops request-routing and client-identity names such as `Host`, `Cookie`, and `X-Forwarded-*` from an entry's `headers` and command output, and keeps authentication names such as `Authorization`. Every `marketplace.json` entry is filtered this way. For an inline plugin entry in settings, see [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces).
357* **Command set in an `--add-dir` directory's settings**: the command is ignored, on a `url` source and on an [inline plugin entry](/docs/en/settings-reference.md#extraknownmarketplaces) alike, and only that file's `headers` are sent.
358* **Managed settings block the command**: setting [`disableCommandPluginSources`](/docs/en/settings-reference#disablecommandpluginsources) to `true` blocks `headersHelper` commands, and [`allowManagedHooksOnly`](/docs/en/settings-reference#allowmanagedhooksonly) blocks them too unless `disableCommandPluginSources` is explicitly `false`. Under either block, Claude Code still runs the command for a marketplace that managed settings themselves declare.
356* **Entry sets a routing or identity header**: Claude Code drops request-routing and client-identity names such as `Host`, `Cookie`, and `X-Forwarded-*` from an entry's `headers` and command output, and keeps authentication names such as `Authorization`. Every `marketplace.json` entry is filtered this way. For an inline plugin entry in settings, see [`extraKnownMarketplaces`](https://code.claude.com/docs/en/settings-reference#extraknownmarketplaces).
357* **Command set in an `--add-dir` directory's settings**: the command is ignored, on a `url` source and on an [inline plugin entry](https://code.claude.com/docs/en/settings-reference.md#extraknownmarketplaces) alike, and only that file's `headers` are sent.
358* **Managed settings block the command**: setting [`disableCommandPluginSources`](https://code.claude.com/docs/en/settings-reference#disablecommandpluginsources) to `true` blocks `headersHelper` commands, and [`allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedhooksonly) blocks them too unless `disableCommandPluginSources` is explicitly `false`. Under either block, Claude Code still runs the command for a marketplace that managed settings themselves declare.
359359
360360### How users accept a headersHelper command
361361
from line 365
365365
366366* **Terminal session**: from the plugin's own view in `/plugin`.
367367* **Shell**: with `claude plugin install` or `claude plugin update`.
368* **VS Code extension**: from the [**Manage plugins** dialog](/docs/en/vs-code.md#manage-plugins), with version 2.1.290 or later of the extension.
368* **VS Code extension**: from the [**Manage plugins** dialog](https://code.claude.com/docs/en/vs-code.md#manage-plugins), with version 2.1.290 or later of the extension.
369369
370In a non-interactive shell, pass [`--yes`](/docs/en/plugins/cli-reference#plugin-install) to accept the command. To accept only the command that a previous `--json` run displayed, pass [`--accept-command`](/docs/en/plugins/cli-reference#plugin-install) with the `sha256` the run reported.
370In a non-interactive shell, pass [`--yes`](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install) to accept the command. To accept only the command that a previous `--json` run displayed, pass [`--accept-command`](https://code.claude.com/docs/en/plugins/cli-reference#plugin-install) with the `sha256` the run reported.
371371
372372Claude Code runs only the command it showed, for the archive URL it showed. If the entry's command or archive URL changed in between, Claude Code refuses the install or update. A change in the query string alone doesn't count, except in the VS Code extension or with `--accept-command`.
373373
from line 380
380380
381381### When a marketplace `url` source's command runs
382382
383You declare a marketplace `url` source's `headersHelper` in a settings file, such as an [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) entry, rather than in the catalog the marketplace publishes. Claude Code therefore doesn't ask the user to accept it on each install or update. Instead, the settings file that declares it decides when Claude Code runs it:
383You declare a marketplace `url` source's `headersHelper` in a settings file, such as an [`extraKnownMarketplaces`](https://code.claude.com/docs/en/settings-reference#extraknownmarketplaces) entry, rather than in the catalog the marketplace publishes. Claude Code therefore doesn't ask the user to accept it on each install or update. Instead, the settings file that declares it decides when Claude Code runs it:
384384
385385| Settings file | When Claude Code runs the command |
386386| :- | :- |
387387| User settings, a `--settings` file, or a managed settings file on the machine | Without asking, including during a background marketplace refresh |
388| A project's `.claude/settings.json` or `.claude/settings.local.json` | Only after the user accepts the [workspace trust dialog](/docs/en/permissions.md#what-runs-before-you-trust-a-folder) for that folder itself. A `-p` or SDK session doesn't count as accepting it, and neither does trust granted to a parent folder |
389| Server-managed settings | In an interactive session, only after the user approves the delivered settings in the [security approval dialog](/docs/en/server-managed-settings.md#security-approval-dialogs) |
388| A project's `.claude/settings.json` or `.claude/settings.local.json` | Only after the user accepts the [workspace trust dialog](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder) for that folder itself. A `-p` or SDK session doesn't count as accepting it, and neither does trust granted to a parent folder |
389| Server-managed settings | In an interactive session, only after the user approves the delivered settings in the [security approval dialog](https://code.claude.com/docs/en/server-managed-settings.md#security-approval-dialogs) |
390390
391For an [inline plugin entry](/docs/en/settings-reference.md#extraknownmarketplaces) in one of these files, Claude Code requires the same folder trust or settings approval as for a marketplace-level command in that file, and the user also accepts the entry's command on each install or update.
391For an [inline plugin entry](https://code.claude.com/docs/en/settings-reference.md#extraknownmarketplaces) in one of these files, Claude Code requires the same folder trust or settings approval as for a marketplace-level command in that file, and the user also accepts the entry's command on each install or update.
392392
393393## Depend on and recommend other plugins
394394
from line 397
397397* **Version ranges**: a dependency can carry a semver range.
398398* **Cross-marketplace dependencies**: a dependency from another marketplace installs only when your marketplace lists that marketplace in `allowCrossMarketplaceDependenciesOn`.
399399
400For version ranges, the `<plugin>--v<version>` git-tag convention they resolve against, and cross-marketplace trust, see [Plugin dependencies](/docs/en/plugins/dependencies.md).
400For version ranges, the `<plugin>--v<version>` git-tag convention they resolve against, and cross-marketplace trust, see [Plugin dependencies](https://code.claude.com/docs/en/plugins/dependencies.md).
401401
402To have Claude Code suggest a plugin when a project matches it, add a `relevance` block to the entry with the signals that identify the project. Users see suggestions from your marketplace only when an admin lists it in `pluginSuggestionMarketplaces`. For the signals and the enablement step, see [Plugin relevance](/docs/en/plugins/relevance.md).
402To have Claude Code suggest a plugin when a project matches it, add a `relevance` block to the entry with the signals that identify the project. Users see suggestions from your marketplace only when an admin lists it in `pluginSuggestionMarketplaces`. For the signals and the enablement step, see [Plugin relevance](https://code.claude.com/docs/en/plugins/relevance.md).
403403
404404## Work around what a marketplace can't do
405405
406406Some things owners ask for have no field in `marketplace.json`. Here is the nearest option for each:
407407
408* **Restrict what else users install**: the marketplace allowlist is a managed setting, `strictKnownMarketplaces`. See [Restrict what users can install](/docs/en/plugins/org.md#restrict-what-users-can-install).
409* **Install or enable a plugin without the user asking**: no entry field installs a plugin. Managed `enabledPlugins` does that for a fleet; see [Pre-install and require plugins](/docs/en/plugins/org.md#pre-install-and-require-plugins).
408* **Restrict what else users install**: the marketplace allowlist is a managed setting, `strictKnownMarketplaces`. See [Restrict what users can install](https://code.claude.com/docs/en/plugins/org.md#restrict-what-users-can-install).
409* **Install or enable a plugin without the user asking**: no entry field installs a plugin. Managed `enabledPlugins` does that for a fleet; see [Pre-install and require plugins](https://code.claude.com/docs/en/plugins/org.md#pre-install-and-require-plugins).
410410* **Show different entries to different users**: entries carry no audience field, and every user who adds the marketplace sees the whole catalog. Host separate marketplaces for separate audiences.
411411* **Mark a plugin deprecated**: there is no deprecation state. The option is to remove the entry, map its name to `null` in `renames`, and optionally set `forceRemoveDeletedPlugins`.
412412* **Turn on auto-update for your users**: each user turns it on under **Marketplaces** in `/plugin`, or an admin sets `autoUpdate` in managed settings. See [Turn on auto-update](#turn-on-auto-update).
from line 414
414414
415415## Next steps
416416
417* [Marketplace reference](/docs/en/plugins/marketplace-reference.md): `marketplace.json` fields, source types, and validation messages
418* [Manage plugins for your organization](/docs/en/plugins/org.md): require, restrict, or seed your marketplace across your organization's machines
419* [Plugin dependencies](/docs/en/plugins/dependencies.md): tag releases so plugins that depend on yours can resolve versions
420* [Troubleshoot plugins](/docs/en/plugins/troubleshooting.md): the errors your users see when adding or updating from your marketplace
417* [Marketplace reference](https://code.claude.com/docs/en/plugins/marketplace-reference.md): `marketplace.json` fields, source types, and validation messages
418* [Manage plugins for your organization](https://code.claude.com/docs/en/plugins/org.md): require, restrict, or seed your marketplace across your organization's machines
419* [Plugin dependencies](https://code.claude.com/docs/en/plugins/dependencies.md): tag releases so plugins that depend on yours can resolve versions
420* [Troubleshoot plugins](https://code.claude.com/docs/en/plugins/troubleshooting.md): the errors your users see when adding or updating from your marketplace
421421
No line in this hunk matches that.