Plugin commands reference changedplugins/cli-reference

A whole new page. There's nothing to diff it against, so here is what it says.

# Plugin commands reference

> Complete reference for the claude plugin shell commands, /plugin and /reload-plugins in a session, and the flags that load a plugin for one session.

You run plugin commands either as `claude plugin` from your shell or a script, or as `/plugin` and `/reload-plugins` inside a Claude Code session. This reference gives each command's flags, defaults, output, and exit codes, along with the two flags that load a plugin for one session.

Run `claude plugin --help` on your build to confirm which subcommands your version has.

<Note>
  These cases are covered on other pages:

  * **Install and manage steps, and where `/plugin` runs**: see [Install and manage plugins](/docs/en/plugins/install)
  * **What a command changes on disk and which scope takes precedence**: see [Plugin loading reference](/docs/en/plugins/loading)
  * **What an error message means**: see [Troubleshoot plugins](/docs/en/plugins/troubleshooting)
</Note>

## claude plugin commands

Run `claude plugin <subcommand>` from your shell or a script, outside a Claude Code session. These subcommands install and manage plugins without opening the [`/plugin`](#plugin-in-a-session) panel.

`claude plugins` is an alias for `claude plugin`.

Every subcommand shares these exit codes, plugin arguments, and scope values:

* **Exit codes**: `0` on success and `1` on failure. `validate` adds exit `2` for an unexpected error, and `eval` adds the codes listed in [its section](#plugin-eval).
* **Plugin arguments**: a `<plugin>` argument is a plugin `name` or `name@marketplace`. When two marketplaces offer the same name, use the qualified form.
* **Scopes**: `--scope` takes `user`, `project`, or `local`, and names the settings file the command writes to. `update` also takes `managed`.

### plugin init

Scaffold a new plugin at `~/.claude/skills/<name>/`. It loads in your next session as `<name>@skills-dir` with no install step.

`new` is an alias for `init`.

For the create, test, and edit workflow that begins with this command, see [Create a plugin](/docs/en/plugins/create).

```bash theme={null}
claude plugin init <name> [options]
```

`<name>` becomes the directory name under `~/.claude/skills/` and the plugin's `name` in its manifest.

The command has no flag for another location. To scaffold inside a project instead, see [Create a plugin](/docs/en/plugins/create).

| Flag                     | Description                                                                                             |
| :----------------------- | :------------------------------------------------------------------------------------------------------ |
| `--description <text>`   | Manifest description                                                                                    |
| `--author <name>`        | Author name. Defaults to `git config user.name`                                                         |
| `--author-email <email>` | Author email. Defaults to `git config user.email`                                                       |
| `--with <components...>` | Also scaffold starter files for `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, or `channel` |
| `-f, --force`            | Overwrite an existing `.claude-plugin/` at the target                                                   |

Scaffold a plugin with starter skill and hook files:

```bash theme={null}
claude plugin init my-helper --with skills hooks
```

Claude Code validates what it wrote and prints `Created plugin "my-helper" at ~/.claude/skills/my-helper`, followed by the id it loads as and the `claude plugin disable` command that turns it off.

Claude Code exits `1` without writing when it can't scaffold safely, and the message names the reason. These are common reasons:

* An unknown `--with` value
* An existing scaffold at the target without `--force`
* A managed setting that blocks skills-directory plugins

### plugin install

Install a plugin from a marketplace you've added. `i` is an alias for `install`.

```bash theme={null}
claude plugin install <plugin> [options]
```

Most 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]`.

| Flag                        | Description                                                                                                                                                                                                                                                                                         |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-s, --scope <scope>`       | Installation scope: `user`, `project`, or `local`. Defaults to `user`                                                                                                                                                                                                                               |
| `--config <key=value>`      | Set a [`userConfig`](/docs/en/plugins/manifest-reference) option the plugin's manifest declares. Repeat the flag for each option. Requires Claude Code v2.1.147 or later                                                                                                                                 |
| `-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                                                                           |
| `--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 |
| `--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                                                                                     |

Pass `-y` from your own terminal to accept the displayed command without the prompt. Here's what happens without a TTY and when Claude runs the command:

* **stdin or stdout isn't a TTY, and you pass neither `-y` nor `--accept-command`**: the install is refused. The output says the command was only displayed, and the exit code is `1`
* **Claude runs the command through its Bash tool**: `-y` is ignored. Run the command from your own terminal instead

Install a plugin for everyone who clones the project:

```bash theme={null}
claude plugin install formatter@my-marketplace --scope project
```

Claude Code prints `Successfully installed plugin: formatter@my-marketplace (scope: project)`. When nothing new is installed, the output says why:

* **Already installed at that scope**: the output is `Plugin "formatter@my-marketplace" is already installed (scope: project)` and the exit code is `0`
* **You decline a command-source prompt**: the output is `Aborted.` and the exit code is `1`
* **You decline a `headersHelper` prompt, or it can't be confirmed without a TTY**: the output is `Aborted — the command was not run.` and the exit code is `1`

<h4 id="plugin-json-result">
  JSON result format
</h4>

When you pass `--json` to `plugin install`, the last line of stdout is one JSON object. Parse only that line, because Claude Code prints any command the marketplace declares ahead of it.

Three fields are always present:

* `command`: the subcommand that ran, such as `install`
* `outcome`: `ok` or `failed`
* `message`: a human-readable description of the result

Other fields, such as `pluginId`, `scope`, and `failureCode`, appear only when they apply.

The `--json` option on `plugin uninstall`, `plugin update`, `plugin enable`, and `plugin disable` prints the same object with that subcommand's own fields.

A usage error, such as an invalid `--scope`, prints no result line and exits `1` with the reason on stderr.

#### Accept a displayed install command

When a `--json` run displays a marketplace-declared command and doesn't run it, the `failed` result also carries a `shownCommand` object. Its fields include the command as displayed, the plugin it belongs to, and the command's `sha256`.

To accept exactly that command, re-run with that `sha256` as `--accept-command` from your own terminal, because the flag has no effect inside a Claude Code session. Requires Claude Code v2.1.271 or later.

The `sha256` counts as acceptance for exactly that command, plugin, and marketplace catalog. If any of them changed since the command was displayed, Claude Code doesn't accept the `sha256` and shows the command again. A change that the run's own marketplace refresh fetches also counts as such a change.

If `shownCommand.acceptCommandMatched` is `false`, the `sha256` you passed doesn't match the command now displayed. Review that command before re-running with its `sha256`.

### plugin uninstall

Remove an installed plugin from one scope. `remove` and `rm` are aliases for `uninstall`.

```bash theme={null}
claude plugin uninstall <plugin> [options]
```

| Flag                  | Description                                                                                                                                                                                                    |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-s, --scope <scope>` | Uninstall from scope: `user`, `project`, or `local`. Defaults to `user`                                                                                                                                        |
| `--keep-data`         | Preserve the plugin's persistent data directory, `~/.claude/plugins/data/<id>/`                                                                                                                                |
| `--prune`             | Also remove auto-installed [dependencies](/docs/en/plugins/dependencies) that no remaining plugin needs                                                                                                             |
| `-y, --yes`           | Skip the `--prune` confirmation prompt. Required with `--prune` when stdin or stdout isn't a TTY                                                                                                               |
| `--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 |

Uninstall a plugin from project scope:

```bash theme={null}
claude plugin uninstall formatter@my-marketplace --scope project
```

Claude Code prints `Successfully uninstalled plugin: formatter (scope: project)`. When the plugin isn't installed at that scope, the command prints a line that starts `Failed to uninstall plugin "formatter@my-marketplace":` and exits `1`.

### plugin enable

Enable a disabled plugin. For a [plugin synced from claude.ai](/docs/en/plugins/loading#synced-plugins), pass `<name>@synced` as the plugin.

```bash theme={null}
claude plugin enable <plugin> [options]
```

| Flag                  | Description                                                                                                                                                                  |
| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-s, --scope <scope>` | Scope to enable at: `user`, `project`, or `local`. Auto-detected when omitted                                                                                                |
| `--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 |

Without `--scope`, the command checks your settings files in the order local, project, user, and uses the first scope that mentions the plugin.

If you pass a `--scope` where the plugin isn't declared, the command either writes an override or fails:

* **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
* **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.`

If 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.

When the plugin declares [dependencies](/docs/en/plugins/dependencies), Claude Code enables them too. The command fails in these cases:

* **A dependency is not installed**: enable fails and prints the `claude plugin install` command for each missing dependency
* **A dependency is blocked by your organization's plugin policy**: enable fails and names the blocked dependency
* **A dependency is set to `false` at a scope with higher precedence than the target scope**: enable fails. Enable the dependency at that scope, or pass `--scope` to write there

Re-enable a plugin wherever it's declared:

```bash theme={null}
claude plugin enable formatter
```

Claude Code prints `Successfully enabled plugin: formatter (scope: project)`, naming the scope it detected.

### plugin disable

Disable a plugin without uninstalling it. For a [plugin synced from claude.ai](/docs/en/plugins/loading#synced-plugins), pass `<name>@synced` as the plugin.

```bash theme={null}
claude plugin disable [plugin] [options]
```

| Flag                  | Description                                                                                                                                                                  |
| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-a, --all`           | Disable every enabled plugin. Can't be combined with a plugin name or `--scope`                                                                                              |
| `-s, --scope <scope>` | Scope to disable at: `user`, `project`, or `local`. Auto-detected when omitted                                                                                               |
| `--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 |

Without `--scope`, the scope is auto-detected in the same local, project, user order as [`plugin enable`](#plugin-enable).

If you pass neither a plugin name nor `--all`, Claude Code prints `Please specify a plugin name or use --all to disable all plugins` and exits `1`. Disabling a plugin that is already disabled prints `Plugin "formatter" is already disabled` and exits `1`, as [`plugin enable`](#plugin-enable) does for an already-enabled plugin.

The command fails for a plugin that is still required:

* **Another enabled plugin [depends on](/docs/en/plugins/dependencies) it**: the command fails and names the dependents to disable first
* **Your organization requires it as a synced plugin**: the command fails and saves nothing

Disable one plugin:

```bash theme={null}
claude plugin disable formatter
```

Claude Code prints `Successfully disabled plugin: formatter (scope: project)`.

### plugin update

Update a plugin to the latest version its marketplace offers. The new version loads in your next session, or after you run `/reload-plugins` in a running one.

```bash theme={null}
claude plugin update <plugin> [options]
```

| Flag                        | Description                                                                                                                                                                                                                              |
| :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-s, --scope <scope>`       | Scope to update: `user`, `project`, `local`, or `managed`. Defaults to the scope the plugin is installed at                                                                                                                              |
| `-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 |
| `--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                  |
| `--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                                                             |

`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).

Update a plugin:

```bash theme={null}
claude plugin update formatter@my-marketplace
```

Claude Code prints `Checking for updates for plugin "formatter@my-marketplace"…`, then the result. When nothing is newer, it prints `formatter is already at the latest version (1.0.0).` and exits `0`.

You can pass a bare plugin name, which the command matches against your installed plugins. When installed plugins from different marketplaces share the name, the command refuses the update and lists the qualified `plugin-name@marketplace-name` commands to run instead. Updating by bare name requires Claude Code v2.1.246 or later.

### plugin list

List installed plugins with their version, scope, and status.

```bash theme={null}
claude plugin list [options]
```

| Flag          | Description                                                                                          |
| :------------ | :--------------------------------------------------------------------------------------------------- |
| `--json`      | Print the list as JSON                                                                               |
| `--available` | Also list plugins your marketplaces offer that you haven't installed. Has no effect without `--json` |

Claude Code groups the human-readable output by how each plugin loads:

* **`Installed plugins:`**: plugins you installed from a marketplace
* **`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`
* **`Skills-directory plugins (.claude/skills/*):`**: plugins Claude Code found in a skills directory
* **`Synced from claude.ai`**: [plugins synced from your claude.ai account](/docs/en/plugins/loading#synced-plugins)

With nothing in any group, Claude Code prints ``No plugins installed. Use `claude plugin install` to install a plugin.``

#### JSON output

With `--json`, Claude Code prints an array with one object per installation. Each object carries the fields below. `id`, `version`, `scope`, `enabled`, and `installPath` are always present, and the others appear only when they apply.

| Field          | Type             | Description                                                                                                                                                                                                                              |
| :------------- | :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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                                                                 |
| `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 |
| `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                                                  |
| `enabled`      | boolean          | Whether the plugin is enabled in your merged settings                                                                                                                                                                                    |
| `installPath`  | string           | Directory the plugin loads from                                                                                                                                                                                                          |
| `installedAt`  | string           | ISO timestamp of the install. Marketplace installs only                                                                                                                                                                                  |
| `lastUpdated`  | string           | ISO timestamp of the last update. Marketplace installs only                                                                                                                                                                              |
| `projectPath`  | string           | Project the install belongs to. `project` and `local` scope only                                                                                                                                                                         |
| `mcpServers`   | object           | The plugin's MCP server definitions, when a marketplace-installed plugin has any                                                                                                                                                         |
| `errors`       | array of strings | Load errors, when the plugin failed to load                                                                                                                                                                                              |
| `notes`        | array of strings | Authoring warnings for a plugin that loaded and works                                                                                                                                                                                    |
| `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                                                         |
| `noteDetails`  | array of objects | The same detail objects for each `notes` entry. Requires Claude Code v2.1.268 or later                                                                                                                                                   |

With `--json --available`, Claude Code prints one object instead of an array. Its `installed` field holds the array of installed-plugin objects, and its `available` field holds one object per uninstalled marketplace plugin with the fields below.

| Field             | Type             | Description                                                                                                            |
| :---------------- | :--------------- | :--------------------------------------------------------------------------------------------------------------------- |
| `pluginId`        | string           | `name@marketplace`                                                                                                     |
| `name`            | string           | The plugin's name in the marketplace                                                                                   |
| `marketplaceName` | string           | The marketplace that offers it                                                                                         |
| `source`          | string or object | The marketplace entry's [source](/docs/en/plugins/marketplace-reference): a string for a relative path, an object otherwise |
| `description`     | string           | The entry's description, when it has one                                                                               |
| `version`         | string           | The entry's version, when it declares one                                                                              |
| `installCount`    | number           | Install count, when Claude Code has one for the plugin                                                                 |

Cut at 300 lines. The page has the rest.

No line in this hunk matches that.