Skip to content

Add Reference section for CLI commands - #76

Open
cdebled wants to merge 7 commits into
mainfrom
reference-cli-section
Open

Add Reference section for CLI commands#76
cdebled wants to merge 7 commits into
mainfrom
reference-cli-section

Conversation

@cdebled

@cdebled cdebled commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add a new reference/cli/ section documenting each command's full option spec (agent, fetch, mcp, serve, run, version) plus shared common-options, sourced from the last version of help.zon
  • Consolidate the four separate run-locally/commands/* usage guides into a single run-locally/commands.mdx page
  • Slim usage/agent.mdx down to a practical guide, linking to the new reference for exhaustive option/REPL-command detail
  • Update cross-links across the guide/usage pages to point at the new reference pages
  • Add a ## help section to reference/cli/index.mdx (previously undocumented) and the missing /save REPL command row to reference/cli/agent.mdx
  • Drop --cookie/--cookie-jar from reference/cli/mcp.mdx's own options block: help.zon duplicates them there (unlike .agent/.run), but they're identical to common-options.mdx, so the same dedup policy as fetch/serve applies

The option specs are copied verbatim from help.zon (the CLI's authoritative --help text). One deliberate exception: the real --help output for each command prints its own options followed by the common options in one combined block, but our docs split them — each command page shows only its own options, and the shared ones live once on common-options.mdx instead of being repeated on every command page.

This PR is part of a series splitting the new Reference section (CLI, MCP tools, HTTP API, PandaScript) into smaller pieces so each can be reviewed and merged on its own: #77 (MCP tools reference), #78 (PandaScript reference).

⚠️ To avoid live broken links, a few cross-references here temporarily point at the current usage guides instead of the reference pages another PR creates:

@cdebled
cdebled force-pushed the reference-cli-section branch from 3cf76c9 to 4b389ae Compare August 4, 2026 15:36

@arrufat arrufat left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked everything against browser main (f55aa1a66) and this one is fully up to date: every option block matches help.zon verbatim, including the newest flags (--block-urls, the mcp HTTP options, --save, the updated http defaults), and the REPL tables match SlashCommand.zig exactly, /stream and /searchEngine included. All new anchors resolve and no stale links to the deleted pages remain. Three small notes inline.

Comment thread src/content/reference/cli/mcp.mdx Outdated
Comment thread src/content/run-locally/commands.mdx
Comment thread redirects.mjs
'/cloud-offer/tools/mcp': '/usage/mcp',
'/cloud-offer/tools/api': '/usage/api',
'/run-locally/commands/fetch': '/run-locally/commands#fetch',
'/run-locally/commands/serve': '/run-locally/commands#serve',

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Take it or leave it: these are the first fragment redirects, and the stub JS in generate-redirects.mjs does location.replace(href + location.hash), so an old bookmarked anchor like /run-locally/commands/serve#options lands on …/commands#serve#options. Probably fine to ignore, just flagging since the generator predates fragment targets.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It requires just 1 line change in generate-redirect.js. Are you ok with this fix?
b455282:

<script>location.replace(${JSON.stringify(href)}${href.includes('#') ? '' : ' + location.hash'})</script>

@cdebled

cdebled commented Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Heads up: #72 edits the four files this PR deletes/consolidates. It'll need to be closed once this merges.

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.

2 participants