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.

[psschwei]

Is the "how to test locally" info in AGENTS.md? If not, could you add it?

[psschwei]

Content layout — Is the single-page format with all commands right for the CLI's size, or should individual commands have their own pages?
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?

My two cents: I would put CLI reference in its own section and have each command be its own page. But it's not a strong opinion, so ok to go in a different direction too.

Content in general looks good and the page loads, so looks like a good addition.

[serjikibm]

The generated cli.md looked good. Compared it with some of the m <command> --help outputs and looked covered similar or enough detail.

However running netlify locally, clicking on the API Reference tab (to the right of Docs at the top bar) returns a 404. Not sure if it is a local env issue or not. The home page and other navigation actions work.

Clicking on the capital M on the left nav, brings you back to the Docs page

Is that the intended behavior, or is it supposed to stay on the API Reference page (vs. Docs)

[planetf1]

Is the "how to test locally" info in AGENTS.md? If not, could you add it?

@psschwei AGENTS.md points to tooling/docs-autogen/README.md where the tooling is described. However that was in need of updating. Doing so now. (I think I did, but lost it in a previous worktree)

[planetf1]

My two cents: I would put CLI reference in its own section and have each command be its own page. But it's not a strong opinion, so ok to go in a different direction too.

@psschwei That was one option I considered, but it felt like a lot of clicking for a fairly short reference. We do have a nav top right showing sections. Adding a page per command does mean deep-linking is possible (for better or worse)can you fix

I figured see what reviewers think and I'll go with consensus. Adding command per page will mean adding some code to update the nav.

Content in general looks good and the page loads, so looks like a good addition.
Agree!

[planetf1]

However running netlify locally, clicking on the API Reference tab (to the right of Docs at the top bar) returns a 404. Not sure if it is a local env issue or not. The home page and other navigation actions work.

@serjikibm Updated the docs on build process -- the API docs are also built in CI, so won't appear without running the build.

Did you get any errors during the build process?

I updated the code docs - See the tooling/docs-autogen/README.md - but the text in the pr should have been sufficient? I just reran here and got the api docs too

Clicking on the capital M on the left nav, brings you back to the Docs page

Is that the intended behavior, or is it supposed to stay on the API Reference page (vs. Docs)

I can say it's the 'coded' behaviour... So the 'm serve' is a standalone page in it's own right in the 'regular' documentation, not the reference. It has more detail than an auto-generated reference and existed before

Maybe that page should be renamed 'serve your mellea ap as an OpenAI compatible endpoint' -- except a shorter version. the m-serve command ref could point there? Names welcome. But yes, that is in docs section so I would expect the tab to change.

[psschwei]

LGTM
I'll approve, we can either have the discussion now or revisit if folks have an opinion once it merges. In theory, we also have some time for folks to chime in before @planetf1 's next work day starts, but in practice ... 😄

[planetf1]

My suggestion is that if this is a step forward and doesnt make things worse, let's get it in, and then I'd ask reviewers to raise issues on improvements/fixes

[planetf1]

rebased due to conflicts

[planetf1]

Ok. merging. please raise any followups as new issues.