docs: add CLI reference page and remove CLI from API docs (#704)

[planetf1]

Type of PR

• Bug Fix
• New Feature
• Documentation
• Other

Description

• Link to Issue: Fixes docs: add CLI reference and remove CLI internals from generated API docs #704

Objective

The cli/ package was included in the generated API reference docs, which is wrong — it's a user-facing tool, not a public Python API. Simultaneously, there was no single CLI reference; coverage was scattered across guide pages. This PR removes CLI internals from the API docs and adds a proper, auto-generated CLI reference page.

What the CLI reference looks like

A single page at Docs > Reference > CLI Reference documenting all m subcommands (serve, alora, decompose, eval, fix). Each command section includes:

• Summary and extended description
• Prerequisites (as a bulleted callout)
• Usage synopsis
• Arguments and options tables (flag, type, default, description)
• Output (what the command produces)
• A one-liner example
• Cross-links to the relevant guide page

All content is sourced from the Python source code — Typer metadata (help= strings, types, defaults) plus structured docstring sections (Prerequisites:, Output:, Examples:, See Also:). Output is standard Markdown, portable across doc frameworks.

CLI Reference - Mellea.pdf

• note the print format isn't clean, but that's a general mintlify-> edge->apple printing issue. Raise separate issue if seen as a problem.

How it is built and validated

Generation pipeline:

• New script tooling/docs-autogen/generate_cli_reference.py imports the Typer app, converts it to its underlying Click model via typer.main.get_command(), walks the command tree, and emits docs/docs/reference/cli.md.
• Integrated into build.py as Step 4, runs with --strict flag.
• --strict validates before writing — fails the build if any command is missing a summary, Prerequisites:, Output: section, or has options without help= text. No incomplete output is produced.
• Available standalone via uv run poe clidocs.

CI enforcement:

• docs-publish.yml runs build.py which now includes strict CLI reference generation.
• New CI step runs the 21 CLI reference unit tests covering Typer introspection, docstring parsing, generated output structure, and strict validation.
• markdownlint covers the generated page (it lands in docs/docs/reference/).

SEO: 17 Mintlify redirects for old /api/cli/* URLs (all submodules including serve/ and fix/).

Changes

Area	What
Remove cli from API docs	generate-ast.py PACKAGES, audit_coverage.py discovery/quality scope, dead discover_cli_commands() removed
New generator	generate_cli_reference.py — Typer introspection, --strict validation, proper title-cased See Also links, --help filtered from output, friendly error on missing extras
Tests	test_cli_reference.py — 21 tests
Build integration	build.py Step 4, pyproject.toml poe tasks, .gitignore
CI	docs-publish.yml — CLI reference test step
Docstring enrichment	All CLI commands: Prerequisites:, Output:, Examples:, See Also:
Cross-links	5 guide pages link back to CLI reference
Redirects	17 old /api/cli/* URLs → /reference/cli
Guidelines	CONTRIBUTING.md CLI docstring convention (including Examples:), AGENTS.md coding standards
Docs-autogen README	Prerequisites, pipeline overview, file structure updated
Glossary	Removed dead m decompose entry (CLI reference now covers it)

Testing

• 21 unit tests added (tooling/docs-autogen/test_cli_reference.py)
• Strict validation passes (--strict flag)
• markdownlint clean on generated output
• All pre-commit hooks pass (ruff, mypy, codespell, markdownlint, MDX validation)
• Local Mintlify preview verified
• Ensure existing tests and GitHub automation passes (a maintainer will kick off the GitHub automation when the rest of the PR is populated)

How to test locally

Full details in tooling/docs-autogen/README.md.

# Install (same as CI)
uv sync --all-extras --group dev

# Generate the CLI reference page (with strict validation)
uv run poe clidocs

# Or generate everything (API docs + CLI reference) via the full pipeline
uv run poe apidocs

# Run the CLI reference tests
uv run pytest tooling/docs-autogen/test_cli_reference.py -v

# Preview locally (requires Node.js LTS, v22 or earlier)
cd docs/docs && npx mintlify dev
# Open http://localhost:3000/reference/cli

Key pages to verify:

• CLI Reference: /reference/cli — all commands, flags, examples, cross-links
• API Reference tab: no cli entries should remain
• Cross-links from guide pages (See Also footers): /guide/m-decompose, /integrations/m-serve, /advanced/lora-and-alora-adapters, /evaluation-and-observability/evaluate-with-llm-as-a-judge, /how-to/refactor-prompts-with-cli
• Redirects: /api/cli/m should redirect to /reference/cli

Questions for reviewers

1. Content layout — Is the single-page format with all commands right for the CLI's size, or should individual commands have their own pages?
2. Navigation — The CLI reference sits under Docs > Reference (alongside the glossary). The API Reference has its own top-level tab. Is this placement correct, or should the CLI reference live elsewhere?
3. Maintenance process — The page is auto-generated from Typer metadata and docstrings, with --strict CI enforcement. Does this approach make sense for keeping docs in sync with minimal overhead?
4. Docstring quality — Do the enriched CLI command docstrings (Prerequisites, Output, Examples, See Also) look reasonable? Any commands where the descriptions should be expanded or clarified?
5. CLI redirects — which of the cli redirects do we need to keep? @abrahamdaniels (noticed you'd mentioned this on some new issues) ?

[github-actions]

The PR description has been updated. Please fill out the template for your PR to be reviewed.