📝 docs: document external subcommands and update CLI docs#1275
📝 docs: document external subcommands and update CLI docs#1275
Conversation
harehare
commented
Feb 14, 2026
harehare
commented
- Add docs/books/src/start/external_subcommands.md for external subcommands
- Update README.md, SUMMARY.md, sitemap.xml, and CLI reference for consistency
- Clarify how to add and use external subcommands
- List mq-edit in external tools
- Add docs/books/src/start/external_subcommands.md for external subcommands - Update README.md, SUMMARY.md, sitemap.xml, and CLI reference for consistency - Clarify how to add and use external subcommands - List mq-edit in external tools Closes #XXX (replace with actual issue if applicable)
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for external subcommands functionality to the mq project. The changes clarify how users can extend mq with custom subcommands and update the CLI reference to reflect the current state where docs and check are now external subcommands rather than built-in commands.
Changes:
- Added new documentation file
docs/books/src/start/external_subcommands.mdexplaining how to create and use external subcommands - Updated CLI documentation in README.md and
docs/books/src/reference/cli.mdto removedocsandcheckfrom built-in commands list - Added mq-edit to the external tools list and updated sitemap.xml and SUMMARY.md to include the new documentation page
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/books/src/start/external_subcommands.md | New documentation page explaining external subcommand functionality with examples and listing available external tools |
| docs/books/src/sitemap.xml | Added sitemap entry for the new external subcommands documentation page |
| docs/books/src/reference/cli.md | Removed docs and check from built-in commands list (now external subcommands) |
| docs/books/src/SUMMARY.md | Added "External Subcommands" entry to the table of contents under "Getting Started" section |
| README.md | Updated CLI reference to match current built-in commands, clarified external subcommands description, and added mq-edit to external tools list |
Comments suppressed due to low confidence (1)
README.md:388
- The external tools list has inconsistent punctuation. Lines 380-383 end with periods, but lines 384-388 are missing periods. All list items should have consistent punctuation - either all should end with periods or none should. Based on the first three entries having periods, the remaining entries should also end with periods.
- [mq-mcp](https://github.com/harehare/mq-mcp) - Model Context Protocol (MCP) server implementation for AI assistants
- [mq-task](https://github.com/harehare/mq-task) - Task runner using mq for Markdown-based task definitions
- [mq-tui](https://github.com/harehare/mq-tui) - Terminal User Interface (TUI) for interactive mq query
- [mq-update](https://github.com/harehare/mq-update) - Update mq binary to the latest version
- [mq-view](https://github.com/harehare/mq-view) - viewer for Markdown content
| - [mq-edit](https://github.com/harehare/mq-edit) - A terminal-based Markdown and code editor with WYSIWYG rendering and LSP support. | ||
| - [mq-mcp](https://github.com/harehare/mq-mcp) - Model Context Protocol (MCP) server implementation for AI assistants | ||
| - [mq-task](https://github.com/harehare/mq-task) - Task runner using mq for Markdown-based task definitions | ||
| - [mq-tui](https://github.com/harehare/mq-tui) - Terminal User Interface (TUI) for interactive mq query |
There was a problem hiding this comment.
The external tools list has inconsistent punctuation. The newly added mq-edit entry on line 383 ends with a period, but lines 384-386 (mq-mcp, mq-task, mq-tui) are missing periods. All list items should have consistent punctuation. Either add periods to lines 384-386 or remove the period from line 383 to match the existing entries.
| Enable streaming mode for processing large files line by line | ||
| --json | ||
|
|
||
There was a problem hiding this comment.
The --json flag is missing a description. While this appears to match the actual CLI output (the source code in crates/mq-run/src/cli.rs:146-147 lacks a doc comment), the documentation should provide a meaningful description. Based on similar flags like --csv ("Include the built-in CSV module"), this should likely say something like "Include the built-in JSON module" or describe what the flag does.
| Include the built-in JSON module |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Comments suppressed due to low confidence (1)
README.md:390
- The external tools list mixes punctuation/capitalization (some entries end with periods, others don’t, and
mq-viewis described as "viewer" while others start with a capital). For consistency/readability, please standardize these entries (e.g., all end with periods and use consistent sentence casing).
- [mq-check](https://github.com/harehare/mq-check) - A syntax and semantic checker for mq files.
- [mq-conv](https://github.com/harehare/mq-conv) - A CLI tool for converting various file formats to Markdown.
- [mq-docs](https://github.com/harehare/mq-docs) - A documentation generator for mq functions, macros, and selectors.
- [mq-edit](https://github.com/harehare/mq-edit) - A terminal-based Markdown and code editor with WYSIWYG rendering and LSP support.
- [mq-mcp](https://github.com/harehare/mq-mcp) - Model Context Protocol (MCP) server implementation for AI assistants
- [mq-task](https://github.com/harehare/mq-task) - Task runner using mq for Markdown-based task definitions
- [mq-tui](https://github.com/harehare/mq-tui) - Terminal User Interface (TUI) for interactive mq query
- [mq-update](https://github.com/harehare/mq-update) - Update mq binary to the latest version
- [mq-view](https://github.com/harehare/mq-view) - viewer for Markdown content
| Create an executable file with the `mq-` prefix in `~/.mq/bin/` or a directory on your `PATH`: | ||
|
|
||
| ```sh | ||
| # Create a custom subcommand | ||
| cat > ~/.mq/bin/mq-hello << 'EOF' | ||
| #!/bin/bash | ||
| echo "Hello from mq-hello!" | ||
| echo "Arguments: $@" | ||
| EOF | ||
| chmod +x ~/.mq/bin/mq-hello |
There was a problem hiding this comment.
The example creates ~/.mq/bin/mq-hello but doesn’t ensure ~/.mq/bin exists; on a fresh install this will fail with “No such file or directory”. Consider adding a mkdir -p ~/.mq/bin step (or explicitly stating the directory must exist) before writing the script.
| ## Command Resolution | ||
|
|
||
| When you run `mq <subcommand>`, mq searches for an executable named `mq-<subcommand>` in the following order: | ||
|
|
||
| 1. `~/.mq/bin/` directory | ||
| 2. Directories in `PATH` | ||
|
|
||
| The first match found is used. |
There was a problem hiding this comment.
The documented resolution order says ~/.mq/bin/ then PATH, but the current CLI implementation can also end up executing ./mq-<subcommand> when ~/.mq/bin does not exist (because it falls back to a relative path before checking PATH). Either document that current-directory behavior explicitly, or adjust the resolution logic so it only considers ~/.mq/bin (when present) and PATH as described here.
| Enable streaming mode for processing large files line by line | ||
| --json | ||
|
|
||
There was a problem hiding this comment.
The --json option is shown with an empty description in the CLI help snippet. Since --csv/--yaml/... are documented, this should also have a one-line description (e.g., matching the clap doc comment for the flag) to avoid a blank entry in the options list.
| Include the built-in JSON module |
