Plugin commands reference - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. 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.
The tables below list each subcommand’s commonly used options, not every option. Run claude plugin --help in your shell to see which subcommands your version has, and claude plugin <subcommand> --help for a subcommand’s full option list. These cases are covered on other pages: Install and manage steps, and where /plugin runs : see Install and manage plugins What a command changes on disk and which scope takes precedence : see Plugin loading reference What an error message means : see Troubleshoot plugins 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 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 arguments : a <plugin> argument is a plugin name or name@marketplace . When two marketplaces offer the same name, use the qualified form. configure takes only the qualified form.
Scopes : --scope takes user , project , or local , and names the settings file the command writes to. update also takes managed . In a terminal, success lines leave out Successfully , as in Installed plugin: . When stdout or stderr isn’t a terminal, Successfully stays. plugin init Scaffold a new plugin at ~/.claude/skills/<name>/ . Unless your administrator has blocked skills-directory plugins , 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 . claude plugin init < nam e > [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 . 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: 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 marketplace allowlist without the skills-dir source, or a blocklist that names it. The message is Plugins from ~/.claude/skills/ are blocked by your organization's managed settings . plugin install Install a plugin from one of your marketplaces. i is an alias for install . claude plugin install < plugi n > [options] Most plugins install without a prompt.
For a plugin whose marketplace entry runs a command to install it or sets a headersHelper for its download , 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 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 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 -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 --accept-command <sha256> Accept the displayed install command whose sha256 a previous --json run reported in shownCommand , in place of -y . Can’t be combined with -y . See 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 . Requires Claude Code v2.1.268 or later --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 .
Requires Claude Code v2.1.292 or later Run claude plugin install --help in your shell to see every option your version supports. 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 To share a plugin with everyone who clones the project, run claude plugin install with --scope project and commit .claude/settings.json . Then have each person add the marketplace and run the same command in their own clone: 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 JSON result format 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. JSON result for marketplace commands On plugin marketplace add , plugin marketplace remove , and plugin marketplace update , --json prints one JSON object on the last line of stdout with command , outcome , and message fields. The following is the result of claude plugin marketplace remove your-marketplace --json : { "command" : "marketplace-remove" , "outcome" : "ok" , "marketplace" : "your-marketplace" , "message" : "Successfully removed marketplace: your-marketplace" } The command value is marketplace-add , marketplace-remove , or marketplace-update .
The fields below appear only when they apply: marketplace : the name of the marketplace the command acted on failureCode : a code for
The rest of this page is on the live site.