Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] `--plugin-dir` docs still describe directory-only input after v2.1.128 added `.zip` plugin archives [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#56150•Fetched 2026-05-05 05:56:53
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×3
RAW_BUFFERClick to expand / collapse

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/cli-reference

Section/Topic

--plugin-dir in the CLI flags reference, plus related --plugin-dir guidance in Headless mode and plugin development docs

Current Documentation

The docs currently say:

--plugin-dir | Load plugins from a directory for this session only. Each flag takes one path. Repeat the flag for multiple directories: --plugin-dir A --plugin-dir B

The related pages use the same directory-only wording:

| A plugin directory | --plugin-dir <path> |

Use the --plugin-dir flag to test plugins during development. This loads your plugin directly without requiring installation.

What's Wrong or Missing?

In v2.1.128, --plugin-dir now accepts .zip plugin archives in addition to directories, but the current documentation still describes the flag as directory-only input.

That leaves the CLI reference and supporting plugin docs outdated in two ways:

A. The accepted argument type is described too narrowly

Users are told the flag loads plugins from "a directory" and the Headless page labels it as "A plugin directory," which no longer matches the current behavior.

B. There is no .zip archive example anywhere in the related docs

The docs do not show that --plugin-dir can point to a packaged .zip plugin archive, so users have no discoverable example for the new input form.

Suggested Improvement

Update the directory-only wording anywhere --plugin-dir is described.

Before:

Load plugins from a directory for this session only. Each flag takes one path. Repeat the flag for multiple directories: --plugin-dir A --plugin-dir B

After:

Load plugins from a directory or .zip plugin archive for this session only. Each flag takes one path. Repeat the flag for multiple plugins, for example: --plugin-dir ./my-plugin --plugin-dir ./dist/my-plugin.zip

Also update the Headless table row from "A plugin directory" to "A plugin directory or .zip plugin archive," and add at least one plugin-doc example that shows a .zip archive path.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageLine(s)Context
https://code.claude.com/docs/en/cli-reference86--plugin-dir says it loads plugins from a directory and repeats for multiple directories
https://code.claude.com/docs/en/headless57Bare-mode flag table labels the input as "A plugin directory"
https://code.claude.com/docs/en/plugins118-121, 296-315Plugin testing examples only show directory paths and repeated directory flags
https://code.claude.com/docs/en/plugins-reference606-609Plugin loading modes mention claude --plugin-dir but do not mention .zip archives

Total scope: 4 pages affected

The changelog entry for v2.1.128 says --plugin-dir now accepts .zip plugin archives in addition to directories, so the current directory-only wording appears outdated across the main CLI and plugin docs.

extent analysis

TL;DR

Update the documentation for --plugin-dir to reflect that it accepts both directories and .zip plugin archives.

Guidance

  • Review the affected pages listed in the issue and update the documentation to include .zip plugin archives as a valid input type for --plugin-dir.
  • Update the CLI reference to use the suggested improved wording: "Load plugins from a directory or .zip plugin archive for this session only."
  • Add examples to the plugin documentation that demonstrate using --plugin-dir with .zip archives.
  • Verify that the updated documentation is consistent across all affected pages.

Example

The updated documentation for the CLI reference could look like this:

Load plugins from a directory or .zip plugin archive for this session only. Each flag takes one path. Repeat the flag for multiple plugins, for example: --plugin-dir ./my-plugin --plugin-dir ./dist/my-plugin.zip

Notes

The updates should be made to the specific lines and pages mentioned in the issue to ensure consistency and accuracy of the documentation.

Recommendation

Apply the suggested improvements to the documentation to ensure that users have accurate and up-to-date information about the --plugin-dir flag.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#installation#request error#file not found#serialization error#model compatibility

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] `--plugin-dir` docs still describe directory-only input after v2.1.128 added `.zip` plugin archives [1 participants]