Report plugin CLI usage for unknown commands

Author: SqlRush

cmd/claude/main.go

@@ -335,9 +335,13 @@ func runPluginCLI(ctx context.Context, state *bootstrap.State, args []string, st
 	_ = ctx
 	if len(args) == 0 {
 		fmt.Fprintln(stderr, "ccgo plugin: missing subcommand")
+		fmt.Fprintln(stderr, pluginCLIUsage())
 		return 2
 	}
 	switch strings.ToLower(strings.TrimSpace(args[0])) {
+	case "help", "-h", "--help":
+		fmt.Fprintln(stdout, pluginCLIUsage())
+		return 0
 	case "list", "ls":
 		return runPluginListCLI(state, args[1:], stdout, stderr)
 	case "install", "i":
@@ -355,11 +359,16 @@ func runPluginCLI(ctx context.Context, state *bootstrap.State, args []string, st
 	case "marketplace", "marketplaces":
 		return runPluginMarketplaceCLI(state, args[1:], stdout, stderr)
 	default:
-		fmt.Fprintf(stderr, "ccgo plugin: unsupported subcommand %s\n", args[0])
+		fmt.Fprintf(stderr, "ccgo plugin: unknown subcommand %s\n", args[0])
+		fmt.Fprintln(stderr, pluginCLIUsage())
 		return 2
 	}
 }
 
+func pluginCLIUsage() string {
+	return "Usage: claude plugin <list|install|update|uninstall|validate|enable|disable|marketplace>"
+}
+
 func runPluginListCLI(state *bootstrap.State, args []string, stdout io.Writer, stderr io.Writer) int {
 	flags := flag.NewFlagSet("claude plugin list", flag.ContinueOnError)
 	flags.SetOutput(stderr)
@@ -665,9 +674,13 @@ func pluralWord(count int, singular string, plural string) string {
 func runPluginMarketplaceCLI(state *bootstrap.State, args []string, stdout io.Writer, stderr io.Writer) int {
 	if len(args) == 0 {
 		fmt.Fprintln(stderr, "ccgo plugin marketplace: missing subcommand")
+		fmt.Fprintln(stderr, pluginMarketplaceCLIUsage())
 		return 2
 	}
 	switch strings.ToLower(strings.TrimSpace(args[0])) {
+	case "help", "-h", "--help":
+		fmt.Fprintln(stdout, pluginMarketplaceCLIUsage())
+		return 0
 	case "add":
 		return runPluginMarketplaceAddCLI(state, args[1:], stdout, stderr)
 	case "list", "ls":
@@ -681,11 +694,16 @@ func runPluginMarketplaceCLI(state *bootstrap.State, args []string, stdout io.Wr
 	case "show", "info":
 		return runPluginMarketplaceShowCLI(state, args[1:], stdout, stderr)
 	default:
-		fmt.Fprintf(stderr, "ccgo plugin marketplace: unsupported subcommand %s\n", args[0])
+		fmt.Fprintf(stderr, "ccgo plugin marketplace: unknown subcommand %s\n", args[0])
+		fmt.Fprintln(stderr, pluginMarketplaceCLIUsage())
 		return 2
 	}
 }
 
+func pluginMarketplaceCLIUsage() string {
+	return "Usage: claude plugin marketplace <list|add|remove|update|plugins|show>"
+}
+
 func runPluginMarketplaceListCLI(state *bootstrap.State, args []string, stdout io.Writer, stderr io.Writer) int {
 	flags := flag.NewFlagSet("claude plugin marketplace list", flag.ContinueOnError)
 	flags.SetOutput(stderr)

cmd/claude/main_test.go

@@ -2198,6 +2198,87 @@ func TestRunPrintStreamJSONOutput(t *testing.T) {
 	}
 }
 
+func TestRunPluginCLIUsageForHelpAndUnknown(t *testing.T) {
+	configHome := t.TempDir()
+	t.Setenv("CLAUDE_CONFIG_DIR", configHome)
+	project := t.TempDir()
+
+	tests := []struct {
+		name       string
+		args       []string
+		wantCode   int
+		wantStdout []string
+		wantStderr []string
+		notStderr  []string
+	}{
+		{
+			name:       "plugin help",
+			args:       []string{"--cwd", project, "plugin", "help"},
+			wantCode:   0,
+			wantStdout: []string{"Usage: claude plugin <list|install|update|uninstall|validate|enable|disable|marketplace>"},
+		},
+		{
+			name:       "plugin missing",
+			args:       []string{"--cwd", project, "plugin"},
+			wantCode:   2,
+			wantStderr: []string{"ccgo plugin: missing subcommand", "Usage: claude plugin <list|install|update|uninstall|validate|enable|disable|marketplace>"},
+			notStderr:  []string{"unsupported"},
+		},
+		{
+			name:       "plugin unknown",
+			args:       []string{"--cwd", project, "plugin", "nope"},
+			wantCode:   2,
+			wantStderr: []string{"ccgo plugin: unknown subcommand nope", "Usage: claude plugin <list|install|update|uninstall|validate|enable|disable|marketplace>"},
+			notStderr:  []string{"unsupported"},
+		},
+		{
+			name:       "marketplace help",
+			args:       []string{"--cwd", project, "plugin", "marketplace", "help"},
+			wantCode:   0,
+			wantStdout: []string{"Usage: claude plugin marketplace <list|add|remove|update|plugins|show>"},
+		},
+		{
+			name:       "marketplace missing",
+			args:       []string{"--cwd", project, "plugin", "marketplace"},
+			wantCode:   2,
+			wantStderr: []string{"ccgo plugin marketplace: missing subcommand", "Usage: claude plugin marketplace <list|add|remove|update|plugins|show>"},
+			notStderr:  []string{"unsupported"},
+		},
+		{
+			name:       "marketplace unknown",
+			args:       []string{"--cwd", project, "plugin", "marketplace", "nope"},
+			wantCode:   2,
+			wantStderr: []string{"ccgo plugin marketplace: unknown subcommand nope", "Usage: claude plugin marketplace <list|add|remove|update|plugins|show>"},
+			notStderr:  []string{"unsupported"},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			code := run(tc.args, strings.NewReader(""), &stdout, &stderr)
+			if code != tc.wantCode {
+				t.Fatalf("exit=%d stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+			}
+			for _, want := range tc.wantStdout {
+				if !strings.Contains(stdout.String(), want) {
+					t.Fatalf("stdout missing %q: %q", want, stdout.String())
+				}
+			}
+			for _, want := range tc.wantStderr {
+				if !strings.Contains(stderr.String(), want) {
+					t.Fatalf("stderr missing %q: %q", want, stderr.String())
+				}
+			}
+			for _, unwanted := range tc.notStderr {
+				if strings.Contains(stderr.String(), unwanted) {
+					t.Fatalf("stderr contains %q: %q", unwanted, stderr.String())
+				}
+			}
+		})
+	}
+}
+
 func TestRunPluginListJSONAvailable(t *testing.T) {
 	configHome := t.TempDir()
 	t.Setenv("CLAUDE_CONFIG_DIR", configHome)

docs/cc-100-roadmap.md

@@ -51,6 +51,8 @@ M8 补充：CLI `plugin list` 现在会对 installed plugin roots 做显式加
 
 M8 补充：CLI `plugin marketplace add` 现在支持官方 `--sparse <path>` repeat 参数，会把 github/git marketplace source 写入 `sparsePaths`，并拒绝对 url/npm/directory/file source 使用 sparse。
 
+M8 补充：CLI `plugin help|-h|--help` 和 `plugin marketplace help|-h|--help` 现在输出稳定 usage；缺少子命令或未知子命令会返回 exit 2 并显示 usage，不再落入 `unsupported subcommand` 占位文案。
+
 M10 补充：plugin command/agent 的 allowed tool frontmatter 解析现在只在顶层逗号或空白处分隔，保留括号、方括号和引号内的逗号/空白，避免 `Bash(git commit -m "x,y")` 这类 tool pattern 被误拆。
 
 M8 补充：CLI `plugin marketplace list` 现在可列出 settings 中已配置的 marketplace；`--json` 输出按名称排序的 source/repo/url/path/package/sparsePaths/installLocation 结构，普通文本输出与无配置提示也已覆盖，并会显示 github/git sparse paths。CLI `plugin marketplace add [--scope user|project|local] [--type ...] <name> <source>` 和 `plugin marketplace remove [--scope user|project|local] <name>` 现在复用 `internal/config` settings 文件写入 helper，可按目标 scope 写入/删除 `extraKnownMarketplaces`，并在写入前复用 marketplace source validation，且 `installLocation` 会校验为 `user|project|local`。CLI `plugin marketplace update [name]` 现在可按全部或指定 marketplace 触发现有 URL/git/github/npm/settings cache 加载刷新路径，命名 update 会用轻量 settings 读取避免启动时提前刷新全部 marketplace。运行时插件发现现在会合并项目链 `.claude/plugins` 和用户级 `${CLAUDE_CONFIG_DIR}/plugins`，项目同名插件优先。CLI `plugin install --scope project|user|local <plugin>` 与 headless `/plugin install [--scope project|user|local] <plugin>` 现在复用 `internal/plugins` 共享安装 API，把 marketplace 插件复制到目标 scope 的 `plugins/<safe-name>`，未显式传 scope 时会尊重 marketplace `installLocation` 默认值，并保留冲突检测、重复安装识别和 symlink/non-regular file 拒绝。CLI `plugin update --scope project|user|local|all <plugin>` 与 headless `/plugin update [--scope project|user|local|all] [plugin]` 现在复用 `internal/plugins` 共享更新 API，把目标 scope 已安装同名插件替换为最新 marketplace 副本，未显式传 scope 的命名更新同样会尊重 marketplace `installLocation`。CLI `plugin enable|disable [--scope user|project|local] <plugin>` 与 `plugin disable --all --scope ...` 现在复用 `internal/config` settings 文件写入 helper，按目标 scope 更新 `enabledPlugins` 并覆盖基本参数冲突。

docs/claude-code-go-rewrite-plan.md

@@ -911,6 +911,7 @@ test/parity/                 # golden tests against TS/official behavior
 - 本轮补充：CLI `plugin list` 现在会显式展示 installed plugin root 的加载错误，坏 manifest 会作为 `failed to load` entry 出现在文本输出中，JSON 输出也会带 `errors`，不再被 `LoadPluginDirs` 静默跳过。
 - 本轮补充：CLI `plugin marketplace add` 现在支持官方 `--sparse <path>` repeat 参数，仅允许 github/git marketplace source 使用，并写入 settings source 的 `sparsePaths`。
 - 本轮补充：CLI `plugin marketplace show|info [--json] <plugin>` 现在可查看 configured marketplace 中单个插件详情，支持 name、`name@marketplace`、`name@version` 精确匹配，并输出 marketplace、version、source、description、installed version/path 和 available/installed/update 状态。
+- 本轮补充：CLI `plugin help|-h|--help` 与 `plugin marketplace help|-h|--help` 现在输出稳定 usage；缺少子命令或未知子命令返回 exit 2 并展示 usage，不再输出 `unsupported subcommand` 占位文案。
 
 - 本轮补充：bridge-safe 内置本地命令 `/summary`、`/release-notes`、`/files` 现在已注册并接入 no-query runner 路径；`/summary` 输出确定性的会话/历史消息计数、工具使用计数、估算 token 和最近用户/助手预览，`/files` 只读列出当前工作目录第一层条目而不读取文件内容，`/release-notes` 明确报告当前 Go runtime 未打包 release notes。完整 local-jsx UI surface 和其它本地命令 parity 仍需继续补。