Plugin commands reference changedplugins/cli-reference
Nearest release: v2.1.307, published 3 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 22 Oct 2026 00:13 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 22 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+70added
Lines−70removed
From line
10
where the diff opens
First seen
25 Sep 2026
this site's first read of the page
Recorded edits19to 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> * **Install and manage steps, and where `/plugin` runs**: see [Install and manage plugins](/docs/en/plugins/install)
14> * **What a command changes on disk and which scope takes precedence**: see [Plugin loading reference](/docs/en/plugins/loading)
15> * **What an error message means**: see [Troubleshoot plugins](/docs/en/plugins/troubleshooting)
13> * **Install and manage steps, and where `/plugin` runs**: see [Install and manage plugins](/docs/en/plugins/install.md)
14> * **What a command changes on disk and which scope takes precedence**: see [Plugin loading reference](/docs/en/plugins/loading.md)
15> * **What an error message means**: see [Troubleshoot plugins](/docs/en/plugins/troubleshooting.md)
1616
1717## claude plugin commands
1818
from line 28
2828
2929### plugin init
3030
31Scaffold a new plugin at `~/.claude/skills/<name>/`. Unless your administrator has [blocked skills-directory plugins](/docs/en/plugins/loading#skills-directory-plugins-blocked-by-managed-settings), it loads in your next session as `<name>@skills-dir` with no install step.
31Scaffold a new plugin at `~/.claude/skills/<name>/`. Unless your administrator has [blocked skills-directory plugins](/docs/en/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings), it loads in your next session as `<name>@skills-dir` with no install step.
3232
3333`new` is an alias for `init`.
3434
35For the create, test, and edit workflow that begins with this command, see [Create a plugin](/docs/en/plugins/create).
35For the create, test, and edit workflow that begins with this command, see [Create a plugin](/docs/en/plugins/create.md).
3636
3737```bash theme={null}
3838claude plugin init <name> [options]
from line 40
4040
4141`<name>` becomes the directory name under `~/.claude/skills/` and the plugin's `name` in its manifest.
4242
43The command has no flag for another location. To scaffold inside a project instead, see [Create a plugin](/docs/en/plugins/create).
43The command has no flag for another location. To scaffold inside a project instead, see [Create a plugin](/docs/en/plugins/create.md).
4444
4545| Flag | Description |
4646| :- | :- |
from line 72
7272claude plugin install <plugin> [options]
7373```
7474
75Most plugins install without a prompt. For a plugin whose marketplace entry [runs a command to install it](/docs/en/plugins/host-marketplace) or [sets a `headersHelper` for its download](/docs/en/plugins/host-marketplace#how-users-accept-a-headershelper-command), Claude Code first prints the command and asks `Run this command now? [y/N]`.
75Most plugins install without a prompt. For a plugin whose marketplace entry [runs a command to install it](/docs/en/plugins/host-marketplace.md) or [sets a `headersHelper` for its download](/docs/en/plugins/host-marketplace#how-users-accept-a-headershelper-command), Claude Code first prints the command and asks `Run this command now? [y/N]`.
7676
7777| Flag | Description |
7878| :- | :- |
7979| `-s, --scope <scope>` | Installation scope: `user`, `project`, or `local`. Defaults to `user` |
80| `--config <key=value>` | Set a [`userConfig`](/docs/en/plugins/manifest-reference) option the plugin's manifest declares. Repeat the flag for each option. A key written `<server>.<key>` sets a setting that a [bundled MCP server](/docs/en/plugins/components#include-a-packaged-mcpb-server) declares in its own `user_config` instead, for a bundle file shipped inside the plugin. The `<server>.<key>` form requires Claude Code v2.1.285 or later |
80| `--config <key=value>` | Set a [`userConfig`](/docs/en/plugins/manifest-reference) option the plugin's manifest declares. Repeat the flag for each option. A key written `<server>.<key>` sets a setting that a [bundled MCP server](/docs/en/plugins/components.md#include-a-packaged-mcpb-server) declares in its own `user_config` instead, for a bundle file shipped inside the plugin. The `<server>.<key>` form requires Claude Code v2.1.285 or later |
8181| `-y, --yes` | Accept the displayed install command without the `Run this command now?` prompt. Ignored when the command runs inside a Claude Code session, such as from the Bash tool or a hook. Requires Claude Code v2.1.229 or later |
8282| `--accept-command <sha256>` | Accept the displayed install command whose `sha256` a previous [`--json` run](#plugin-json-result) reported in `shownCommand`, in place of `-y`. Can't be combined with `-y`. See [Accept a displayed install command](#accept-a-displayed-install-command). Requires Claude Code v2.1.271 or later |
8383| `--json` | Print the result as one JSON object on the last line of stdout instead of the human-readable message, for use in scripts. See [JSON result format](#plugin-json-result). Requires Claude Code v2.1.268 or later |
84| `--marketplace <source>` | Install `<plugin>`, given by its bare name, from the marketplace at `<source>`, adding the marketplace first if you haven't added it yet. See [Add a marketplace and install in one command](/docs/en/plugins/install#add-a-marketplace-and-install-in-one-command). Requires Claude Code v2.1.292 or later |
84| `--marketplace <source>` | Install `<plugin>`, given by its bare name, from the marketplace at `<source>`, adding the marketplace first if you haven't added it yet. See [Add a marketplace and install in one command](/docs/en/plugins/install.md#add-a-marketplace-and-install-in-one-command). Requires Claude Code v2.1.292 or later |
8585
8686Run `claude plugin install --help` in your shell to see every option your version supports.
8787
from line 131
131131* `marketplace`: the name of the marketplace the command acted on
132132* `failureCode`: a code for why the command failed, such as `invalid_source`
133133
134`plugin marketplace add` and `plugin marketplace remove` can print no result line when the argument is the [reserved name](/docs/en/plugins/marketplace-reference#reserved-names) `anthropic-plugin-directory`, so check the exit code for that name.
134`plugin marketplace add` and `plugin marketplace remove` can print no result line when the argument is the [reserved name](/docs/en/plugins/marketplace-reference.md#reserved-names) `anthropic-plugin-directory`, so check the exit code for that name.
135135
136136#### Accept a displayed install command
137137
from line 155
155155| :- | :- |
156156| `-s, --scope <scope>` | Uninstall from scope: `user`, `project`, or `local`. Defaults to `user` |
157157| `--keep-data` | Preserve the plugin's persistent data directory, `~/.claude/plugins/data/<id>/` |
158| `--prune` | Also remove auto-installed [dependencies](/docs/en/plugins/dependencies) that no remaining plugin needs |
158| `--prune` | Also remove auto-installed [dependencies](/docs/en/plugins/dependencies.md) that no remaining plugin needs |
159159| `-y, --yes` | Skip the `--prune` confirmation prompt. Required with `--prune` when stdin or stdout isn't a TTY |
160160| `--json` | Print the result as one JSON object on the last line of stdout, in the [same format as `plugin install --json`](#plugin-json-result). Can't be combined with `--prune`. Requires Claude Code v2.1.268 or later |
161161
from line 171
171171
172172#### What an uninstall deletes and keeps
173173
174When you uninstall a plugin from the last scope it's installed at, Claude Code also deletes the plugin's stored [options and secrets](/docs/en/plugins/manifest-reference#user-configuration) and its data directory, `~/.claude/plugins/data/<id>/`. There are three exceptions:
174When you uninstall a plugin from the last scope it's installed at, Claude Code also deletes the plugin's stored [options and secrets](/docs/en/plugins/manifest-reference.md#user-configuration) and its data directory, `~/.claude/plugins/data/<id>/`. There are three exceptions:
175175
176176* With `--keep-data`, the data directory stays
177177* When another installed plugin uses the same folder, such as one whose ID differs from this one only in letter case, the data directory stays
from line 181
181181
182182### plugin enable
183183
184Enable a disabled plugin. For a [plugin synced from claude.ai](/docs/en/plugins/loading#synced-plugins), pass `<name>@synced` as the plugin.
184Enable a disabled plugin. For a [plugin synced from claude.ai](/docs/en/plugins/loading.md#synced-plugins), pass `<name>@synced` as the plugin.
185185
186186```bash theme={null}
187187claude plugin enable <plugin> [options]
from line 196
196196
197197If you pass a `--scope` where the plugin isn't declared, the command either writes an override or fails:
198198
199* **A scope that [takes precedence](/docs/en/plugins/loading) over the declaring one**: Claude Code writes an override at the scope you passed. For example, `claude plugin disable formatter --scope local` turns off a project-enabled plugin for you alone
199* **A scope that [takes precedence](/docs/en/plugins/loading.md) over the declaring one**: Claude Code writes an override at the scope you passed. For example, `claude plugin disable formatter --scope local` turns off a project-enabled plugin for you alone
200200* **Any other scope**: the command fails with `Plugin "formatter" is installed at project scope, not user. Use --scope project or omit --scope to auto-detect.`
201201
202202If the plugin is already enabled at the resolved scope, the command prints `Plugin "formatter" is already enabled` and exits `1`. With `--json`, the result has `"failureCode": "already_in_goal_state"` and `"alreadyInGoalState": true`, so a script can treat that case as success.
203203
204When the plugin declares [dependencies](/docs/en/plugins/dependencies), Claude Code enables them too. The command fails in these cases:
204When the plugin declares [dependencies](/docs/en/plugins/dependencies.md), Claude Code enables them too. The command fails in these cases:
205205
206206* **A dependency is not installed**: enable fails and prints the `claude plugin install` command for each missing dependency
207207* **A dependency is blocked by your organization's plugin policy**: enable fails and names the blocked dependency
from line 217
217217
218218### plugin disable
219219
220Disable a plugin without uninstalling it. For a [plugin synced from claude.ai](/docs/en/plugins/loading#synced-plugins), pass `<name>@synced` as the plugin.
220Disable a plugin without uninstalling it. For a [plugin synced from claude.ai](/docs/en/plugins/loading.md#synced-plugins), pass `<name>@synced` as the plugin.
221221
222222```bash theme={null}
223223claude plugin disable [plugin] [options]
from line 235
235235
236236The command fails for a plugin that is still required:
237237
238* **Another enabled plugin [depends on](/docs/en/plugins/dependencies) it**: the command fails and names the dependents to disable first
238* **Another enabled plugin [depends on](/docs/en/plugins/dependencies.md) it**: the command fails and names the dependents to disable first
239239* **Your organization requires it as a synced plugin**: the command fails and saves nothing
240240
241241Disable one plugin:
from line 257
257257| Flag | Description |
258258| :- | :- |
259259| `-s, --scope <scope>` | Scope to update: `user`, `project`, `local`, or `managed`. Auto-detected when omitted |
260| `-y, --yes` | Accept a changed install command from a [command-source](/docs/en/plugins/host-marketplace) plugin, without the prompt. Required when stdin or stdout isn't a TTY, unless you pass `--accept-command`. Requires Claude Code v2.1.229 or later |
260| `-y, --yes` | Accept a changed install command from a [command-source](/docs/en/plugins/host-marketplace.md) plugin, without the prompt. Required when stdin or stdout isn't a TTY, unless you pass `--accept-command`. Requires Claude Code v2.1.229 or later |
261261| `--accept-command <sha256>` | Accept the marketplace-declared command whose `sha256` a previous [`--json` run](#plugin-json-result) reported in `shownCommand`, in place of `-y`. Can't be combined with `-y`. Requires Claude Code v2.1.271 or later |
262262| `--json` | Print the result as one JSON object on the last line of stdout, in the [same format as `plugin install --json`](#plugin-json-result). Requires Claude Code v2.1.268 or later |
263263
from line 275
275275
276276Before v2.1.281, the command used `user` when you omitted `--scope`, so updating a plugin installed only at project or local scope failed with `Plugin "<name>" is not installed at scope user`. On those versions, pass `--scope`.
277277
278`managed` is the one scope you can update but not install to. For admin-installed plugins, see [Manage plugins for your organization](/docs/en/plugins/org).
278`managed` is the one scope you can update but not install to. For admin-installed plugins, see [Manage plugins for your organization](/docs/en/plugins/org.md).
279279
280280#### Update by bare name
281281
from line 283
283283
284284#### Retry an unfinished dependency install
285285
286When the plugin is already at its latest version, the command can also retry an unfinished dependency install in its cached copy. For the cases where that retry runs or is skipped, see [The packages it lists are not installed](/docs/en/plugins/troubleshooting#the-packages-it-lists-are-not-installed). If the retry fails, the output is `Failed to update plugin "formatter@my-marketplace"` with the reason and the exit code is `1`. Before v2.1.287, the command reported the plugin at its latest version without retrying the install.
286When the plugin is already at its latest version, the command can also retry an unfinished dependency install in its cached copy. For the cases where that retry runs or is skipped, see [The packages it lists are not installed](/docs/en/plugins/troubleshooting.md#the-packages-it-lists-are-not-installed). If the retry fails, the output is `Failed to update plugin "formatter@my-marketplace"` with the reason and the exit code is `1`. Before v2.1.287, the command reported the plugin at its latest version without retrying the install.
287287
288288### plugin list
289289
from line 304
304304* **`Installed plugins:`**: plugins you installed from a marketplace
305305* **`Session-only plugins (--plugin-dir / --plugin-url):`**: plugins loaded by those flags in the same command, as in `claude --plugin-dir ./my-plugin plugin list`
306306* **`Skills-directory plugins (.claude/skills/*):`**: plugins Claude Code found in a skills directory
307* **`Synced from claude.ai`**: [plugins synced from your claude.ai account](/docs/en/plugins/loading#synced-plugins)
307* **`Synced from claude.ai`**: [plugins synced from your claude.ai account](/docs/en/plugins/loading.md#synced-plugins)
308308
309309With nothing in any group, Claude Code prints ``No plugins installed. Use `claude plugin install` to install a plugin.``
310310
from line 315
315315| Field | Type | Description |
316316| :- | :- | :- |
317317| `id` | string | `name@marketplace` for installs, `name@inline` for session-only plugins, `name@skills-dir` for skills-directory plugins, `name@synced` for plugins synced from claude.ai |
318| `version` | string | For a marketplace install, the [version Claude Code computed](/docs/en/plugins/loading#versions-and-updates) at install. For a session-only, skills-directory, or synced plugin, the manifest's `version`, or `unknown` when it declares none |
318| `version` | string | For a marketplace install, the [version Claude Code computed](/docs/en/plugins/loading.md#versions-and-updates) at install. For a session-only, skills-directory, or synced plugin, the manifest's `version`, or `unknown` when it declares none |
319319| `scope` | string | `user`, `project`, `local`, or `managed` for installs; `user` or `project` for skills-directory plugins; `session` for session-only plugins; `synced` for plugins synced from claude.ai |
320320| `enabled` | boolean | Whether the plugin is enabled in your merged settings |
321| `installPath` | string | Directory the plugin loads from, except for a plugin that sessions [load in place](/docs/en/plugins/loading#in-place-and-copied-plugins) from its marketplace's folder |
322| `readFromFolder` | string | For a plugin that sessions [load in place](/docs/en/plugins/loading#in-place-and-copied-plugins) from its marketplace's folder, the plugin's source directory inside that folder. Requires Claude Code v2.1.289 or later |
321| `installPath` | string | Directory the plugin loads from, except for a plugin that sessions [load in place](/docs/en/plugins/loading.md#in-place-and-copied-plugins) from its marketplace's folder |
322| `readFromFolder` | string | For a plugin that sessions [load in place](/docs/en/plugins/loading.md#in-place-and-copied-plugins) from its marketplace's folder, the plugin's source directory inside that folder. Requires Claude Code v2.1.289 or later |
323323| `folderVersion` | string | With `readFromFolder`, the plugin's `version` as Claude Code loaded it from that folder, which can differ from the `version` field above. Absent when the plugin didn't load or declares no version. Requires Claude Code v2.1.289 or later |
324324| `installedAt` | string | ISO timestamp of the install. Marketplace installs only |
325325| `lastUpdated` | string | ISO timestamp of the last update. Marketplace installs only |
from line 326
326326| `projectPath` | string | Project the install belongs to. `project` and `local` scope only |
327327| `mcpServers` | object | The plugin's MCP server definitions, when a marketplace-installed plugin has any |
328328| `errors` | array of strings | Load errors, when the plugin failed to load |
329| `notes` | array of strings | Warnings that aren't load errors, such as authoring issues or [packages that aren't installed](/docs/en/plugins/loading#when-the-dependency-install-fails-or-is-skipped) |
329| `notes` | array of strings | Warnings that aren't load errors, such as authoring issues or [packages that aren't installed](/docs/en/plugins/loading.md#when-the-dependency-install-fails-or-is-skipped) |
330330| `errorDetails` | array of objects | One object per `errors` entry, giving its diagnostic `type` and the names it refers to, such as the plugin, marketplace, server, or file. Requires Claude Code v2.1.268 or later |
331331| `noteDetails` | array of objects | The same detail objects for each `notes` entry. Requires Claude Code v2.1.268 or later |
332332| `hasUserConfig` | boolean | Present and `true` when the plugin loaded and its manifest declares [`userConfig` options](/docs/en/plugins/manifest-reference#user-configuration). Absent for a plugin that failed to load, whatever its manifest declares. Saved values are never included. Requires Claude Code v2.1.285 or later |
from line 341
341341| `pluginId` | string | `name@marketplace` |
342342| `name` | string | The plugin's name in the marketplace |
343343| `marketplaceName` | string | The marketplace that offers it |
344| `source` | string or object | The marketplace entry's [source](/docs/en/plugins/marketplace-reference): a string for a relative path, an object otherwise |
344| `source` | string or object | The marketplace entry's [source](/docs/en/plugins/marketplace-reference.md): a string for a relative path, an object otherwise |
345345| `description` | string | The entry's description, when it has one |
346346| `version` | string | The entry's version, when it declares one |
347347| `installCount` | number | Install count, when Claude Code has one for the plugin |
from line 370
370370* **`Projected token cost`**: the always-on tokens the plugin adds to every session
371371* **`Per-component (rounded)`**: always-on and on-invoke estimates for each skill, agent, and command. Omitted when the plugin has none
372372
373For what the two cost figures mean, see [Measure plugin cost and usage](/docs/en/plugins/measure).
373For what the two cost figures mean, see [Measure plugin cost and usage](/docs/en/plugins/measure.md).
374374
375375For a plugin that isn't loaded, Claude Code prints this message and exits `1`:
376376
from line 378
378378Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.
379379```
380380
381An ID that ends in `@builtin` names one of the [plugins built into Claude Code](/docs/en/plugins/mods/overview#mods-built-into-claude-code). If you pass such an ID and Claude Code doesn't find that plugin, the message reads instead:
381An ID that ends in `@builtin` names one of the [plugins built into Claude Code](/docs/en/plugins/mods/overview.md#mods-built-into-claude-code). If you pass such an ID and Claude Code doesn't find that plugin, the message reads instead:
382382
383383```text theme={null}
384384Plugin "<name>@builtin" not found. Built-in plugins don't appear in `claude plugin list`. To see the ones available in a session, run /plugin in Claude Code and open the Installed tab.
from line 413
413413
414414### plugin prune
415415
416Remove auto-installed [dependencies](/docs/en/plugins/dependencies) that no installed plugin needs anymore. The command never removes a plugin you installed yourself. `autoremove` is an alias for `prune`.
416Remove auto-installed [dependencies](/docs/en/plugins/dependencies.md) that no installed plugin needs anymore. The command never removes a plugin you installed yourself. `autoremove` is an alias for `prune`.
417417
418418```bash theme={null}
419419claude plugin prune [options]
from line 447
447447
448448### plugin eval
449449
450Run a plugin's [eval cases](/docs/en/plugin-evals) and report scored results. Requires Claude Code v2.1.269 or later.
450Run a plugin's [eval cases](/docs/en/plugin-evals.md) and report scored results. Requires Claude Code v2.1.269 or later.
451451
452452Each case is a prompt plus graders. Claude Code runs it several times in an isolated session with only the target plugin loaded, and by default also without the plugin so the report shows the difference.
453453
454See [Test plugins with evals](/docs/en/plugin-evals) for the case format, graders, results, and CI usage.
454See [Test plugins with evals](/docs/en/plugin-evals.md) for the case format, graders, results, and CI usage.
455455
456456```bash theme={null}
457457claude plugin eval [target] [options]
from line 470
470470
471471| Option | Description | Default |
472472| :- | :- | :- |
473| `--runs <n>` | Runs per case in each [arm](/docs/en/plugin-evals#compare-against-a-no-plugin-baseline) | Each case's `runs`, else 3 |
473| `--runs <n>` | Runs per case in each [arm](/docs/en/plugin-evals.md#compare-against-a-no-plugin-baseline) | Each case's `runs`, else 3 |
474474| `-j, --concurrency <n>` | Agent sessions to run at once, 1 to 8. They share your rate limit | `1` |
475475| `--model <model>` | Model for the agent under test | Each case's `model`, else `ANTHROPIC_MODEL` if set, else Claude Code's default |
476| `--judge-model <model>` | Model for `llm` and `baseline` graders | The model for [background tasks](/docs/en/plugin-evals#grade-the-result) |
477| `--ablation <mode>` | `none` or `with-without`. See [Score against the no-plugin baseline](/docs/en/plugin-evals#compare-against-a-no-plugin-baseline) | Decided per case, as that section describes |
476| `--judge-model <model>` | Model for `llm` and `baseline` graders | The model for [background tasks](/docs/en/plugin-evals.md#grade-the-result) |
477| `--ablation <mode>` | `none` or `with-without`. See [Score against the no-plugin baseline](/docs/en/plugin-evals.md#compare-against-a-no-plugin-baseline) | Decided per case, as that section describes |
478478| `--threshold <0..1>` | Exit 1 if any case scores below this | `1.0` |
479479| `--max-cost-usd <usd>` | Stop before the next run once spend reaches this, exit 2, and report partial results | No limit |
480| `--allow-tools <tools...>` | Grant tools beyond the read-only set, such as `Bash`, `Write`, `Edit`, or `"mcp__plugin_<plugin>_<server>__*"`. See [Grant tools](/docs/en/plugin-evals#grant-tools) | |
480| `--allow-tools <tools...>` | Grant tools beyond the read-only set, such as `Bash`, `Write`, `Edit`, or `"mcp__plugin_<plugin>_<server>__*"`. See [Grant tools](/docs/en/plugin-evals.md#grant-tools) | |
481481| `--scaffold` | Run each case's [`scaffold_script`](/docs/en/plugin-evals#add-setup-or-history-with-case-yaml) | Off |
482| `--trust-plugin` | Skip the first-run trust prompt, for CI. See [What a run can access](/docs/en/plugin-evals#security) | Off |
483| `--mocks <mode>` | `record` or `off`. See [Mock MCP servers](/docs/en/plugin-evals#mock-mcp-servers) | `record` |
482| `--trust-plugin` | Skip the first-run trust prompt, for CI. See [What a run can access](/docs/en/plugin-evals.md#security) | Off |
483| `--mocks <mode>` | `record` or `off`. See [Mock MCP servers](/docs/en/plugin-evals.md#mock-mcp-servers) | `record` |
484484| `--eval-dir <dir>` | Directory below the plugin that holds the cases | The manifest's `experimental.evals`, else `evals` |
485| `--json [path]` | Print the [result document](/docs/en/plugin-evals#json-result) to stdout, or write it to a `.json` path | |
485| `--json [path]` | Print the [result document](/docs/en/plugin-evals.md#json-result) to stdout, or write it to a `.json` path | |
486486| `--no-publish` | Keep the HTML report local | |
487487
488The exit code reports how the run ended. To act on it in a pipeline, see [Run evals in CI](/docs/en/plugin-evals#run-evals-in-ci).
488The exit code reports how the run ended. To act on it in a pipeline, see [Run evals in CI](/docs/en/plugin-evals.md#run-evals-in-ci).
489489
490490| Exit code | Meaning |
491491| :- | :- |
492492| `0` | The suite passed: every case meets the threshold and nothing else failed the run |
493| `1` | A failing case, a load error, an untrusted plugin directory, a run that [ended on an API error](/docs/en/plugin-evals#runs-ended-on-an-api-error), or another cause listed under [Run evals in CI](/docs/en/plugin-evals#run-evals-in-ci) |
493| `1` | A failing case, a load error, an untrusted plugin directory, a run that [ended on an API error](/docs/en/plugin-evals.md#runs-ended-on-an-api-error), or another cause listed under [Run evals in CI](/docs/en/plugin-evals.md#run-evals-in-ci) |
494494| `2` | A partial run |
495495| `130` | Interrupted |
496496| `143` | Terminated |
from line 497
497497
498498### plugin eval init
499499
500Create an eval suite for the plugin in the current directory. Requires Claude Code v2.1.269 or later. See [Create your first eval suite](/docs/en/plugin-evals#create-your-first-eval-suite).
500Create an eval suite for the plugin in the current directory. Requires Claude Code v2.1.269 or later. See [Create your first eval suite](/docs/en/plugin-evals.md#create-your-first-eval-suite).
501501
502502```bash theme={null}
503503claude plugin eval init [name] [options]
from line 529
529529
530530Create an annotated git tag named `<name>--v<version>` for a plugin release. Before tagging, the command checks that the plugin's `plugin.json` and any marketplace entry that lists it agree on the version.
531531
532For when to tag a release, see [Publish a plugin](/docs/en/plugins/publish).
532For when to tag a release, see [Publish a plugin](/docs/en/plugins/publish.md).
533533
534534```bash theme={null}
535535claude plugin tag [path] [options]
from line 569
569569
570570### plugin test
571571
572Run the tests for a [mod](/docs/en/plugins/mods/overview), a plugin whose code registers event handlers. The command needs no session, sign-in, or network. For how to write a test, see [Test a mod](/docs/en/plugins/mods/test).
572Run the tests for a [mod](/docs/en/plugins/mods/overview.md), a plugin whose code registers event handlers. The command needs no session, sign-in, or network. For how to write a test, see [Test a mod](/docs/en/plugins/mods/test.md).
573573
574574```bash theme={null}
575575claude plugin test [directory]
from line 585
585585
586586### plugin validate
587587
588Validate a plugin manifest, a marketplace manifest, or the skills, agents, and commands in a directory, and exit with a code a CI job can act on. For the create, test, and edit workflow, see [Create a plugin](/docs/en/plugins/create). For what the validator checks in each manifest, see the [plugin manifest reference](/docs/en/plugins/manifest-reference) and the [marketplace reference](/docs/en/plugins/marketplace-reference).
588Validate a plugin manifest, a marketplace manifest, or the skills, agents, and commands in a directory, and exit with a code a CI job can act on. For the create, test, and edit workflow, see [Create a plugin](/docs/en/plugins/create.md). For what the validator checks in each manifest, see the [plugin manifest reference](/docs/en/plugins/manifest-reference.md) and the [marketplace reference](/docs/en/plugins/marketplace-reference.md).
589589
590590```bash theme={null}
591591claude plugin validate <path> [options]
from line 644
644644* `target`: the resolved path Claude Code validated
645645* `manifest`: the manifest's own result, or `null` for a run without a manifest
646646* `contents`: per-file results, each naming its `file` and carrying `errors`, `warnings`, and `notes` arrays
647 * `gatingHooks`: whether each [mod](/docs/en/plugins/mods/overview) hook that can refuse an action, such as a `tool.call` hook, has a [`.catch` handler](/docs/en/plugins/mods/events#handle-a-hook-that-fails). Each item gives `module`, `pattern`, `hook`, and `hasCatch`. Requires Claude Code v2.1.290 or later
647 * `gatingHooks`: whether each [mod](/docs/en/plugins/mods/overview.md) hook that can refuse an action, such as a `tool.call` hook, has a [`.catch` handler](/docs/en/plugins/mods/events#handle-a-hook-that-fails). Each item gives `module`, `pattern`, `hook`, and `hasCatch`. Requires Claude Code v2.1.290 or later
648648
649649On exit `2`, the command writes nothing to stdout. The error message goes to stderr.
650650
from line 655
655655* **Exit codes**: these subcommands follow the [exit-code convention](#claude-plugin-commands) of the plugin commands
656656* **Scopes**: their `--scope` flag has no `-s` short form
657657
658For what a marketplace is and how Claude Code caches it, see [Plugin loading reference](/docs/en/plugins/loading).
658For what a marketplace is and how Claude Code caches it, see [Plugin loading reference](/docs/en/plugins/loading.md).
659659
660660### plugin marketplace add
661661
662662Add a marketplace from a GitHub repository, a git URL, a hosted `marketplace.json`, or a local path, and declare it in a settings file.
663663
664After you add it, Claude Code installs any [dependencies](/docs/en/plugins/dependencies) that your installed plugins were missing.
664After you add it, Claude Code installs any [dependencies](/docs/en/plugins/dependencies.md) that your installed plugins were missing.
665665
666666```bash theme={null}
667667claude plugin marketplace add <source> [options]
from line 671
671671| :- | :- |
672672| `--scope <scope>` | Settings file to declare the marketplace in: `user`, `project`, or `local`. Defaults to `user` |
673673| `--sparse <paths...>` | Limit the git checkout to these directories, for monorepos. `github` and `git` sources only |
674| `--claudeai` | Read the argument as the name of a [marketplace hosted on claude.ai](/docs/en/plugins/install#add-from-claude-ai) instead of a source. Requires Claude Code v2.1.273 or later |
674| `--claudeai` | Read the argument as the name of a [marketplace hosted on claude.ai](/docs/en/plugins/install.md#add-from-claude-ai) instead of a source. Requires Claude Code v2.1.273 or later |
675675| `--json` | Print whether the command succeeded, and its message, as one JSON object on the last line of stdout, in the [JSON result format](#plugin-json-result). Has no effect with `--claudeai`. Requires Claude Code v2.1.287 or later |
676676
677`<source>` takes any of the forms in the table below, and its form decides the source type and how Claude Code fetches the marketplace. For the resulting source object, see the [marketplace reference](/docs/en/plugins/marketplace-reference).
677`<source>` takes any of the forms in the table below, and its form decides the source type and how Claude Code fetches the marketplace. For the resulting source object, see the [marketplace reference](/docs/en/plugins/marketplace-reference.md).
678678
679679| You type | Source type | How Claude Code fetches it |
680680| :- | :- | :- |
from line 702
702702* **Unrecognized source**: the output is `Invalid marketplace source format. Try: owner/repo, https://..., or ./path` and the exit code is `1`
703703* **Bare host such as `gitlab.example.com/team/plugins`**: the add fails as an invalid `owner/repo` shorthand, and the message tells you to add `https://` or use a local path
704704
705Add a [marketplace hosted on claude.ai](/docs/en/plugins/install#add-from-claude-ai) by the name printed in the `From claude.ai:` section of `claude plugin marketplace list`:
705Add a [marketplace hosted on claude.ai](/docs/en/plugins/install.md#add-from-claude-ai) by the name printed in the `From claude.ai:` section of `claude plugin marketplace list`:
706706
707707```bash theme={null}
708708claude plugin marketplace add --claudeai claudeai-organization-library
from line 736
736736| `ref` | The pinned branch or tag. `github` and `git` sources, only when pinned |
737737| `installLocation` | Where Claude Code cached the marketplace |
738738
739An added [claude.ai marketplace](/docs/en/plugins/install#add-from-claude-ai) has no local clone, so its entry carries its claude.ai identifiers, `marketplaceId` and `organizationUuid`, in place of `installLocation`. It also carries `scope` when one is recorded, and `status`.
739An added [claude.ai marketplace](/docs/en/plugins/install.md#add-from-claude-ai) has no local clone, so its entry carries its claude.ai identifiers, `marketplaceId` and `organizationUuid`, in place of `installLocation`. It also carries `scope` when one is recorded, and `status`.
740740
741If your terminal sessions [sync plugins from your claude.ai account](/docs/en/plugins/loading#synced-plugins), the text listing ends with a `From claude.ai:` section. That section names the marketplaces claude.ai lists for your account that you haven't added, both git-based and hosted. It requires Claude Code v2.1.273 or later.
741If your terminal sessions [sync plugins from your claude.ai account](/docs/en/plugins/loading.md#synced-plugins), the text listing ends with a `From claude.ai:` section. That section names the marketplaces claude.ai lists for your account that you haven't added, both git-based and hosted. It requires Claude Code v2.1.273 or later.
742742
743To add a marketplace from that section, see [Add a marketplace from claude.ai](/docs/en/plugins/install#add-from-claude-ai).
743To add a marketplace from that section, see [Add a marketplace from claude.ai](/docs/en/plugins/install.md#add-from-claude-ai).
744744
745745The `--json` output covers configured marketplaces only and leaves the section out.
746746
from line 750
750750
751751> [!WARNING]
752752>
753> When you remove a marketplace from the last scope that declares it, Claude Code also deletes its cache and uninstalls every plugin you installed from it. It also deletes their saved [options and secrets](/docs/en/plugins/manifest-reference#user-configuration) and [data](/docs/en/plugins/components#path-variables-and-persistent-data) where it can.
753> When you remove a marketplace from the last scope that declares it, Claude Code also deletes its cache and uninstalls every plugin you installed from it. It also deletes their saved [options and secrets](/docs/en/plugins/manifest-reference.md#user-configuration) and [data](/docs/en/plugins/components.md#path-variables-and-persistent-data) where it can.
754754>
755755> To refresh a marketplace without losing its plugins, run `plugin marketplace update` instead.
756756
from line 801
801801
802802You can run these commands only in an interactive terminal session. In a non-interactive run such as `claude -p`, Claude Code replies that `/plugin` isn't available in this environment.
803803
804For which surfaces have `/plugin`, how to install without it, and what each panel tab shows, see [Install and manage plugins](/docs/en/plugins/install).
804For which surfaces have `/plugin`, how to install without it, and what each panel tab shows, see [Install and manage plugins](/docs/en/plugins/install.md).
805805
806806A `<plugin>` is a plugin `name` or `name@marketplace`.
807807
from line 814
814814| `/plugin list [--enabled\|--disabled]` | `ls` | Prints your marketplace-installed plugins inline, with version, scope, and status. A filter flag shows only that state. A plugin whose enable state hasn't been applied yet is marked `— run /reload-plugins to apply` |
815815| `/plugin install` | `i` | Opens the **Discover** tab |
816816| `/plugin install <plugin>` | `i` | Opens the plugin's details in the **Discover** tab. With `name@marketplace`, opens them in that marketplace's list |
817| `/plugin install <source>` | `i` | Reports a [marketplace not found](/docs/en/plugins/troubleshooting#marketplace-not-found) error and installs nothing when the target is a path, URL, or `owner/repo`, even a source you've already added. To install from a source, see [Add a marketplace and install in one command](/docs/en/plugins/install#add-a-marketplace-and-install-in-one-command) |
818| `/plugin install <plugin> --marketplace <source>` | `i` | Adds the marketplace at `<source>` when you haven't added it yet, asking you to confirm first, then opens the plugin's details. See [Add a marketplace and install in one command](/docs/en/plugins/install#add-a-marketplace-and-install-in-one-command). Requires Claude Code v2.1.275 or later |
817| `/plugin install <source>` | `i` | Reports a [marketplace not found](/docs/en/plugins/troubleshooting.md#marketplace-not-found) error and installs nothing when the target is a path, URL, or `owner/repo`, even a source you've already added. To install from a source, see [Add a marketplace and install in one command](/docs/en/plugins/install.md#add-a-marketplace-and-install-in-one-command) |
818| `/plugin install <plugin> --marketplace <source>` | `i` | Adds the marketplace at `<source>` when you haven't added it yet, asking you to confirm first, then opens the plugin's details. See [Add a marketplace and install in one command](/docs/en/plugins/install.md#add-a-marketplace-and-install-in-one-command). Requires Claude Code v2.1.275 or later |
819819| `/plugin manage` | | Opens the **Installed** tab |
820820| `/plugin stats` | | Opens the **Stats** tab, in sessions where [`/skill-doctor`](/docs/en/skills#find-unused-skills) is available. Anywhere else it opens the panel on the **Discover** tab |
821821| `/plugin enable <plugin>` | | Opens the **Installed** tab at the plugin and enables it |
from line 852
852852
853853The skills count covers every skill a plugin provides, both its `commands/` entries and its `SKILL.md` skills. The agents count is the number of agents loaded in the session, including ones that don't come from plugins.
854854
855When a reloaded plugin's [dependencies](/docs/en/plugins/dependencies) are missing, Claude Code installs them, reloads again, and appends `(+ N dependencies: <names>) resolved` to the summary.
855When a reloaded plugin's [dependencies](/docs/en/plugins/dependencies.md) are missing, Claude Code installs them, reloads again, and appends `(+ N dependencies: <names>) resolved` to the summary.
856856
857857### Reloads that change MCP tools
858858
859When the reload would add or remove a plugin MCP server or the `LSP` tool, and that change would invalidate the [prompt cache](/docs/en/prompt-caching#enabling-or-disabling-a-plugin), Claude Code doesn't apply the reload. It prints a line such as `This reload changes MCP tools (<server>) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply.` Pass `--force` to apply it anyway.
859When the reload would add or remove a plugin MCP server or the `LSP` tool, and that change would invalidate the [prompt cache](/docs/en/prompt-caching.md#enabling-or-disabling-a-plugin), Claude Code doesn't apply the reload. It prints a line such as `This reload changes MCP tools (<server>) — your next message will re-read the whole conversation instead of using the cache. Run /reload-plugins --force to apply.` Pass `--force` to apply it anyway.
860860
861861### Sessions without an interactive terminal
862862
863`/reload-plugins` also runs in sessions without an interactive terminal, such as the desktop app, the Agent SDK, and [non-interactive mode](/docs/en/headless) with `-p`. Requires Claude Code v2.1.260 or later.
863`/reload-plugins` also runs in sessions without an interactive terminal, such as the desktop app, the Agent SDK, and [non-interactive mode](/docs/en/headless.md) with `-p`. Requires Claude Code v2.1.260 or later.
864864
865In those sessions, the command runs only when you type it into the session yourself, such as in the `-p` prompt or the desktop app's prompt box. When it arrives another way, such as through [Remote Control](/docs/en/remote-control) or a message relayed from Slack, the command replies `/reload-plugins isn't available over a remote connection in this session.` and reloads nothing.
865In those sessions, the command runs only when you type it into the session yourself, such as in the `-p` prompt or the desktop app's prompt box. When it arrives another way, such as through [Remote Control](/docs/en/remote-control.md) or a message relayed from Slack, the command replies `/reload-plugins isn't available over a remote connection in this session.` and reloads nothing.
866866
867867The reload in those sessions doesn't connect or disconnect plugin MCP servers. Those changes take effect in your next session.
868868
from line 870
870870
871871Two `claude` flags load a plugin for one session only, without installing it. Both are repeatable.
872872
873Plugin authors use them to test a plugin before publishing. For the load-edit-reload workflow, see [Develop without a marketplace](/docs/en/plugins/create#develop-without-a-marketplace).
873Plugin authors use them to test a plugin before publishing. For the load-edit-reload workflow, see [Develop without a marketplace](/docs/en/plugins/create.md#develop-without-a-marketplace).
874874
875875| Flag | Description | Example |
876876| :- | :- | :- |
from line 879
879879
880880A plugin that either flag loads is a session-only plugin. [`claude plugin list`](#plugin-list) shows it only when the same flag precedes the subcommand, as in `claude --plugin-dir ./my-plugin plugin list`. The plugin appears as `<name>@inline` under a heading that begins `Session-only plugins`, and `--json` reports its `scope` as `session`.
881881
882When a session-only plugin shares a name with an installed plugin, Claude Code loads the session-only copy for that session and skips the installed one. The installed copy loads instead if you disabled the session-only copy with `claude plugin disable <name>@inline`, or if managed settings lock that plugin name. For the precedence, see [Plugin loading reference](/docs/en/plugins/loading).
882When a session-only plugin shares a name with an installed plugin, Claude Code loads the session-only copy for that session and skips the installed one. The installed copy loads instead if you disabled the session-only copy with `claude plugin disable <name>@inline`, or if managed settings lock that plugin name. For the precedence, see [Plugin loading reference](/docs/en/plugins/loading.md).
883883
884884An administrator can reject both flags, and folders named in the [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/en/env-vars#variables) variable, with the managed [`disableSideloadFlags`](/docs/en/settings-reference#disablesideloadflags) setting. Claude Code then prints that the flag is disabled by your organization's managed settings and exits `1` without starting.
885885
from line 887
887887
888888## Next steps
889889
890* [Install and manage plugins](/docs/en/plugins/install): the same operations as steps, with what you see at each one
891* [Plugin loading reference](/docs/en/plugins/loading): what each command changes on disk and which scope takes effect
892* [Troubleshoot plugins](/docs/en/plugins/troubleshooting): install, marketplace, load, and validation error messages with their fixes
893* [Plugin manifest reference](/docs/en/plugins/manifest-reference): the fields `claude plugin validate` checks
890* [Install and manage plugins](/docs/en/plugins/install.md): the same operations as steps, with what you see at each one
891* [Plugin loading reference](/docs/en/plugins/loading.md): what each command changes on disk and which scope takes effect
892* [Troubleshoot plugins](/docs/en/plugins/troubleshooting.md): install, marketplace, load, and validation error messages with their fixes
893* [Plugin manifest reference](/docs/en/plugins/manifest-reference.md): the fields `claude plugin validate` checks
894894
No line in this hunk matches that.