Plugin Commands
The claude plugin command installs, updates, checks, and removes plugins from the shell.
Inside a session, /plugin opens a panel and /reload-plugins applies changes.
claude plugins is an alias of claude plugin.
For example, claude plugin list --json prints your installs as JSON.
Turn a plugin on or off with claude plugin enable and disable. Managed disableSideloadFlags turns off the session flags. State is in ~/.claude/plugins/ and in enabledPlugins.
Subcommands
-s is --scope. Scopes are user, project, and local.
The hidden flag --cowork works on install, uninstall, enable, disable, update, list, details, configure, prune, validate, and marketplace add, list, remove, and update. It makes the command use the cowork_plugins directory (the program).
Source: Plugin Commands Reference and claude plugin --help.
| Command | Status | What It Does | Flags and Notes |
|---|---|---|---|
init <name> (alias new) | Documented: An official docs page names this item. | Scaffolds ~/.. It loads next session as <name>@skills-. | --, --, --, -, -- (any of skills, agents, hooks, mcp, lsp, output-, channel) |
install <plugin> (alias i) | Documented: An official docs page names this item. | Installs a plugin from a marketplace. | - (default user), --, -, --, --, --. The hidden -- switches a plugin installed from another marketplace to this copy. It installs the copy. It moves your plugin settings to the copy. It uninstalls the other plugin. |
install -- | Documented: An official docs page names this item. | Sets the npm registry for <package>@npm installs. | Shown in --, but not in the docs table. |
uninstall <plugin> (aliases remove, rm) | Documented: An official docs page names this item. Caution: It deletes data, skips a safety check, or sends data off your machine. On the last scope it removes options, secrets, and data | Removes the plugin from one scope. | -, --, --, -, --. On the last scope it removes options, secrets, and data. |
enable <plugin> | Documented: An official docs page names this item. | Enables a plugin. | - (auto-detects local, project, then user), -- |
disable [plugin] | Documented: An official docs page names this item. | Disables a plugin. | -, -, --. Fails if another plugin depends on it. |
update <plugin> | Documented: An official docs page names this item. | Updates a plugin. | -, -, --, --. A restart or / applies it. |
list | Documented: An official docs page names this item. | Lists installs. | --, --, -- |
details <name> | Documented: An official docs page names this item. | Shows the component list and projected token cost. | No flags. |
configure <plugin> | Documented: An official docs page names this item. | Shows or saves the user values. | --, --. Needs the full plugin id. |
prune (alias autoremove) | Documented: An official docs page names this item. | Removes automatic dependencies that nothing uses. | -, --, - |
validate <path> | Documented: An official docs page names this item. | Checks a plugin, marketplace, or component folder. | --, --, and since 2. --. Also /. With -- the command also exits 1 when the plugin directory (the catalog that plugins are submitted to) would refuse the plugin on a check it runs, or when a check could not be made. -- then treats the directory's warnings as errors. Errors (exit 1) include README_ and README_ (a README under 40 words), LICENSE_ (no LICENSE file and no license in plugin.), PATH_ (a path that climbs out of the plugin), an MCP or hooks file that is unreadable or invalid, and manifest problems such as an invalid plugin. or a badly formed name. A hooks/ must be a regular file under a size cap. Warnings (they fail only with --) include ICON_ and ICON_ (the local check reads only the file type; the fix text says the directory wants a square PNG or JPEG, 512 to 2048 px on each side, under 2 MB, and no SVG or WebP), PRIVACY_ (checked only when the plugin connects to a remote MCP server or HTTP hook; set privacy in plugin.), and ARCHIVE_ (a system file such as .), plus others such as a README that does not render or a name that is not kebab-case. "A check could not be made" includes plugin. listing more than 16 files for MCP servers or for hooks (16 of each are checked) and an MCP or hooks file the checks cannot use, such as one that is not valid JSON. The directory runs more checks than the command does. It needs a plugin folder, not a project's . folder (the program). |
tag [path] | Documented: An official docs page names this item. | Creates the git tag <name>--. | --, --, -, -, --. Also /. |
test [dir] | Documented: An official docs page names this item. | Runs the tests of a mod. | Runs every *. and *. file. |
eval [target] | Documented: An official docs page names this item. | Runs eval cases against a plugin. Needs 2. or later. | Flags: --, --, --, --, -- (default haiku), -- (default case.), - (1 to 8, default 1), -- (exit 1 when a case scores below it, default 1.), -- (no help text), -- (runs a no-plugin baseline arm and reports the score delta), -- and --, -- (mock stand-ins for MCP servers, from the mocks/ folder of the eval dir; default record) with --, -- and -- (-- runs the scaffold_ of each case as you, and it is off by default), --, --, --, --, -- and -- (the HTML report goes to claude.ai by default when your account supports it), --. Also -- for CI. |
eval init [name] | Documented: An official docs page names this item. | Creates an eval suite. | --, - (the hidden -- is an alias), -- |
warning
claude plugin eval loads and runs the plugin on your machine, as you.
Run it only for plugins you trust. The sandbox limits a bad plugin. It does not guarantee safety.
Marketplace Subcommands
| Command | Status | What It Does | Flags and Notes |
|---|---|---|---|
marketplace add <source> | Documented: An official docs page names this item. | Adds a marketplace. | --, --, --, --. The hidden -- adds the marketplace as an install link does. -- (with --) adds nothing. It prints one JSON line. The line names the added marketplace that -- would reuse. The source is owner/, a git URL, an https URL, or a path. |
marketplace list | Documented: An official docs page names this item. | Lists marketplaces. | -- |
marketplace remove <name> (alias rm) | Documented: An official docs page names this item. | Removes the declaration. | --, --. On the last scope, it removes the cache. It also uninstalls the plugins from that marketplace. |
marketplace update [name] | Documented: An official docs page names this item. | Refreshes marketplaces. | -- needs a name. |
Session Commands
| Command | Status | What It Does | Notes |
|---|---|---|---|
/ (aliases /, /) | Documented: An official docs page names this item. | Opens the panel with the tabs Discover, Installed, Marketplaces, Stats, and Errors. | Subcommands: help, list [--, install, manage, stats, enable, disable, uninstall, configure, validate, tag, marketplace add|list|update|remove. Interactive sessions only. |
/ | Documented: An official docs page names this item. | Applies pending plugin changes without a restart. | Refuses a change to MCP tools that would break the prompt cache, unless you add --. Works in both modes. |
Session Flags
| Flag | Status | What It Does | Notes |
|---|---|---|---|
-- | Documented: An official docs page names this item. | Loads a folder or . for this session only. | The id is <name>@inline. A folder of plugins loads each child. Repeatable. The env var CLAUDE_ does the same. |
-- | Documented: An official docs page names this item. | Loads a . from a URL for this session only. | Repeatable. |
-- | Undocumented: Only the program shows this item. It can change without notice. | Loads an inline plugin without its MCP servers. | Hidden flag. The SDK form is skip. |
Managed disableSideloadFlags: true rejects --plugin-dir, --plugin-url, --agents, and --mcp-config.
Example
Install, configure, and update a plugin
claude plugin marketplace add example/team-tools
claude plugin install deploy-tools@team-tools --scope project --config REGION=eu-west-1
claude plugin details deploy-tools@team-tools
claude plugin disable deploy-tools@team-tools
claude plugin update deploy-tools@team-tools --yes
How It Works
Errors
Each row is a family of messages. The backticked text is the start that every message in the family shares.
| Start of Message | Status | What It Means | Cases |
|---|---|---|---|
mocks/, mocks:, mocks is not, ambiguous mock server, build | Undocumented: Only the program shows this item. It can change without notice. | claude plugin eval refused a mocks folder or a mock file. | A folder or file is a symbolic link, is unreadable, or has more entries than the cap. A directory is not named after the server segment of the tool name. A responder file is not named after the tool. A name holds __, the tool-name separator. A responder needs tools:. expect: or error: is in the wrong place. Two mocks claim the same server. |
case "${…}", case ${…}:, case., YAML parse failed | Undocumented: Only the program shows this item. It can change without notice. | claude plugin eval refused a case. | A plugins entry resolves outside the containment root or is not loaded. An add_ entry resolves outside the case directory. case. is not a YAML object. execution. has a key that is not an EVAL_ key. |
focus file | Undocumented: Only the program shows this item. It can change without notice. | claude plugin eval could not read a focus file. | The file does not exist, is unreadable, or is not a regular file. It has more than one hard link, is over the size limit, or changed during the read. |
git metadata file | Undocumented: Only the program shows this item. It can change without notice. | claude plugin eval refused a git metadata file. | The file is not a plain readable file, is not a regular file, or is larger than the byte limit. |
output base, output location, refusing to write, refusing to open through, refusing to use, append to ${…} made no progress, not a directory:, no variant directories, ${…}/ | Undocumented: Only the program shows this item. It can change without notice. | A report or scaffold step refused to write or read a path. | The path is outside the allowed root or holds a . or .. segment. It is a symbolic link or passes through one. It is not a regular file, has a second hard link, or is not a directory. |
Error:, Error:, plugin eval:, claude plugin eval can't, git on this host did not, git ${…}., judge call failed, No TTY available, results directory, ${…} case file(s) failed, Interrupted — finishing up, Terminated — finishing up, Note:, warning:, warning:, Publishing is unavailable, Skipped publishing, Publishing report to claude., Published: | Undocumented: Only the program shows this item. It can change without notice. | claude plugin eval could not run, or printed a notice. | The plugin cannot be evaluated where sessions load it. Git is missing or too old. The judge call failed. No TTY is available for the authoring interview. A results directory already existed. Case files failed to load. The run was interrupted. Publishing was unavailable or skipped. The result does not match the schema. |
the run created, the run made more, the run was granted artifact publishing, the run's artifact-, the case's scaffold, a corroborated artifact publish, the stub publish directory, the kept directory, the harness is running as root, directory modes do not, the directory modes, the sealed directory, home/, the operator's home, the home, Claude config, a cloud credential file, the Anthropic profile configs, a PATH directory could not, the organization policy snapshot, A shell tool was granted, ${…} could not be examined after, ${…} became a symlink, ${…} already exists; refusing, ${…} is a symlink, ${…} is a directory, not a file, ${…} could not be opened, ${…} changed while being opened, ${…} is not a regular file, ${…} is hard-, ${…} (this machine's managed settings, ${…} directory name, ${…} is on a network (UNC) path, ${…} was not written by this run, ${…} already exists and was not written, ${…} no longer holds, ${…} is no longer the directory, ${…} vanished from, ${…} is ${…} bytes (cap, ${…} changed while being read, ${…}/, ${…} is not a directory, case ${…}, recording name, value nested too deep | Undocumented: Only the program shows this item. It can change without notice. | claude plugin eval refused to run because a path, folder, or environment failed a safety check. | A file is a symbolic link, is hard-linked, is not a regular file, changed during the read, or is over its cap. A folder is not the one the harness created, has a glob character in its path, or is on a network (UNC) path. Folder modes did not take effect. The harness runs as root. A shell tool was granted, but the sandbox cannot exclude a home or credential path. The run created a name that is reserved for artifact publishes. The run was granted artifact publishing, but the child was not offered the stand-in tool. As a result, the local Artifacts server did not attach. |
${…}:, ${…}:, ${…}:, ${…}: | Undocumented: Only the program shows this item. It can change without notice. | A grader or responder file has bad frontmatter. | A key is not known. type: is missing (it is one of regex, tool_order, tool_used, file_exists, llm, baseline). The opening --- has no closing one. The YAML is invalid. |
--, --, --, --, --, Aborted — the command was not run | Undocumented: Only the program shows this item. It can change without notice. | claude plugin install refused --. | The value is not KEY=VALUE. The plugin's user does not declare the key, or more than one bundled MCP server declares it. A value is empty, not a number, or not a boolean (use true/false, 1/0, yes/no, on/off). The plugin failed to load after the install. |
This plugin has no ${…}, Plugin option | Undocumented: Only the program shows this item. It can change without notice. | A plugin option has no value or a bad one. | A required value is missing. A value is over 64 KB. A value must be a single line. A value must be true or false. |
Related Pages
- Plugins
- Marketplaces
- Plugin Loading
- CLI Subcommands and CLI Flags for the other commands