Skip to content

feat(help): add hidden --help-json for machine-readable command tree#135

Open
crowlbot wants to merge 1 commit into
fix/unknown-flag-usage-errorfrom
feat/help-json
Open

feat(help): add hidden --help-json for machine-readable command tree#135
crowlbot wants to merge 1 commit into
fix/unknown-flag-usage-errorfrom
feat/help-json

Conversation

@crowlbot

Copy link
Copy Markdown
Contributor

--help is written for humans; an agent that wants to know which subcommands
exist, which flags each one takes, and which of those are required has to scrape
it. This adds a hidden --help-json global flag that dumps the command tree as
one JSON object on stdout and exits 0.

  • help-json.ts — serializes a Cliffy command: description, positional
    arguments, options (flags, required, collect, global, hidden, static
    default), examples, and subcommands recursively. Hidden commands/options are
    included but flagged, so the dump is the full surface.
  • Handled in main.ts before parse(), so introspecting a command that
    declares required options (setup-aws --help-json) doesn't trip validation.
  • Leading positional args address a subtree: deno deploy env list --help-json
    returns just that node. Inherited globals are materialized on every node, so a
    single node lists every flag it accepts.
  • Works on the standalone deno sandbox root too.
  • Declared as a hidden globalOption on both roots purely so it shows up in the
    dumped tree; the pre-parse interception is what implements it.

Tests in tests/cli_contract.test.ts (token-free): tree dump, global agent
flags present and marked global, every command/option has a description,
subtree resolution, required-option command introspects cleanly, sandbox root.

Also documents it in AGENTS.md.

Agents need to enumerate subcommands and flags without scraping the
human --help output. --help-json is intercepted before Cliffy parses,
so introspecting a command with required options (e.g. setup-aws) works.
@crowlbot crowlbot requested a review from crowlKats July 10, 2026 10:32
@crowlbot

Copy link
Copy Markdown
Contributor Author

CI here is red on three tests that are not caused by this PR:

  • the two tests/cli_contract.test.ts unknown-flag failures are pre-existing on main (cliffy 1.2 swallows unknown options into positional slots),
  • --help-json: every command and option has a description catches tunnel-login missing a .description().

Both are fixed in #136. Once that lands I will rebase this branch and CI should go green.

@crowlbot crowlbot changed the base branch from main to fix/unknown-flag-usage-error July 10, 2026 11:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant