@clidoc/cli

Validate your CLI's OpenCLI document and turn it into a Markdown reference, shell completions or MCP tools, all from one command-line tool. Node 22.12+; ESM only.

The CLI being documented provides its own docgen command (see @clidoc/yargs, @clidoc/commander, @clidoc/oclif), the human-facing entry point. Install clidoc globally to validate and render the resulting file:

npm install -g @clidoc/cli
mycli docgen --output cli.json
clidoc validate cli.json
clidoc markdown cli.json --output reference.md

mycli __opencli is the hidden, machine-facing discovery subcommand, matching upstream OpenCLI's Go libraries, including its -o/--out <file> flag (mycli __opencli --out cli.json); omitted, it writes to stdout like clidoc docgen/clidoc markdown do when their own --output is omitted. clidoc dogfoods this exact workflow on itself: clidoc docgen and clidoc __opencli both describe the clidoc binary. Invalid input or command usage exits with status 1. --help describes command arguments, and --version prints the installed package version.

Commands are separate files registered through yargs-file-commands, matching the hdrify approach. cliDocument() derives this tool's OpenCLI document from those same definitions. runCli(argv) supports embedding without exiting the calling process; it rejects on invalid input.

See the repository guide and command reference.

Why / compared to alternatives

• Hand-written reference pages drift from the real flags; this renders Markdown from a document generated from your command definitions.
• --help only can't be validated, searched as a site, or turned into completions and MCP tools. A validated OpenCLI document can.
• oclif readme is oclif-specific and writes into a README. clidoc works from an OpenCLI file, so any CLI that can emit one is covered.

Related packages

• @clidoc/core: the library behind these commands.
• Generate the document: @clidoc/yargs, @clidoc/commander, @clidoc/oclif.
• Publish it: @clidoc/docusaurus or @clidoc/vitepress.

Shell completion

Generate standalone Bash, Zsh, and Fish scripts for clidoc or any validated OpenCLI JSON/YAML document:

clidoc completion bash                    # clidoc itself; script on stdout
clidoc completion zsh -i mycli.json -o mycli.zsh
clidoc completion fish -o ~/.config/fish/completions/clidoc.fish

For Bash, activate with source <(clidoc completion bash). For Zsh, run source <(clidoc completion zsh) after autoload -Uz compinit; compinit. Use --binary name to register an alternative executable name. Generated scripts need neither Node nor clidoc at completion time. Regenerate them after CLI changes. See the completion guide for persistent installation, supported syntax, and limitations.

MCP tools and stdio server

clidoc mcp cli.json --output tools.json
clidoc mcp cli.json --serve --executable /absolute/path/to/mycli

Exporting does not execute the CLI. Serving requires an explicit trusted executable and validates every tool invocation. The bridge uses conventional long options and -- before positional arguments; see the MCP guide for the serialization contract, client configuration, limits, and supported spec features.

Library users can import compileMcpTools, createMcpServer, and serveMcp from @clidoc/cli/mcp.

License

MIT. See LICENSE.

Author

Ben Houston, Sponsored by Land of Assets.