feat(cli): add an audience flag to hide unreleased commands

Merged
SA
2mo ago
+114-5

Summary

  • CLI commands and groups can be marked audience: "internal"; they only exist when SUPERSET_CLI_AUDIENCE=internal is set.
  • Marks plugins, mcp, skills and environments internal. Those features are flag-gated to staff or an allowlist in the app, but the CLI showed them to everyone.

Why / Context

The CLI had no way to ship a command without advertising it. Options could be .hidden(), but commands couldn't. This follows the Docker CLI's experimental gate: a label on the command, one check at the root, and an env var to opt in.

This controls what we show and support, not access. Anyone can set the env var, so anything sensitive stays gated on the server.

How It Works

  • audience?: "internal" | "public" on CommandConfig and group meta.ts, defaulting to public. If any node in a path — group or command — is internal, everything from that node down is internal; a public tag below it cannot re-expose anything. A group left with no visible commands is dropped.
  • defineConfig({ audiences }) returns the enabled set. The framework doesn't know the env var; packages/cli/cli.config.ts maps SUPERSET_CLI_AUDIENCE=internal to ["internal", "public"].
  • filterByAudience prunes the command list before buildTree, so help, interactive help, routing and "Did you mean" all read one filtered tree. Hidden commands fail with Unknown command and are never suggested.

Manual QA Checklist

  • cli-framework dev --help without the env var: plugins/mcp/skills/environments absent
  • cli-framework dev plugins list without the env var: Error: Unknown command: plugins
  • SUPERSET_CLI_AUDIENCE=internal cli-framework dev plugins --help works
  • Group-level tag hides the whole subtree (checked with a temporary tag on feedback, reverted)
  • A command tagged public inside the internal plugins group stays hidden: plugins list → Unknown command: plugins (temporary tag, reverted)

Testing

  • bun test packages/cli-framework packages/cli: 310 pass, including the new router.test.ts
  • tsc --noEmit for cli-framework and cli; biome on the desktop change
  • biome check on changed files

Known Limitations

  • The desktop's Plugins page (flag-gated to @superset.sh) shells out to superset plugins install|uninstall|enable|disable, so it runs those with SUPERSET_CLI_AUDIENCE=internal (apps/desktop/src/main/lib/plugin-installs.ts). Without that, staff who haven't set the variable would get installs that report success but never provision skills. It's a stopgap: SUPER-2435 moves the logic in-process and deletes the shell-out along with this override.
  • Options can't be tagged; .hidden() remains for those. ws create --cloud stays visible, and the server still gates it.
  • apps/docs/content/docs/cli/cli-reference.mdx still documents plugins, mcp and environments. We'll update docs as part of each launch.

Rollback

Revert the PR. Nothing is persisted.

Summary by cubic

Adds an audience flag so CLI commands and groups can be hidden unless SUPERSET_CLI_AUDIENCE=internal is set, and marks plugins, mcp, skills, and environments as internal.

  • Any internal group or command in a path hides everything below it; groups left with no visible commands are dropped.
  • Controls visibility only, not access: anyone can set the env var, so sensitive behavior stays gated server-side.
  • Hidden commands are pruned before help, routing, and "Did you mean" suggestions, making them appear not to exist.
  • The desktop's Plugins page shells out to superset plugins …, so it runs those calls with SUPERSET_CLI_AUDIENCE=internal; otherwise staff without the variable would get installs that report success but never provision skills. Stopgap until SUPER-2435 moves the logic in-process and removes the shell-out.

Summary by CodeRabbit

  • New Features
    • CLI commands can be shown or hidden by audience. Public runs display public commands by default, while internal runs can include internal commands.
    • Internal-only commands are now marked as such, including environment, MCP, plugin, and skill commands.
    • Commands nested under internal groups or commands remain hidden in public runs, even if individually marked public.