mant

Explanation reports retain separate owners, readable kinds and source coordinates. Plain output leaves original lines unframed; Markdown quotes them. Complete displayed definitions suppress duplicate Forms per record, while omitted bodies keep Forms and truly isolated empty declarations have a distinct notice. Consecutive native heads can instead carry explicitly recovered group context, with the original description provider and no inferred alias equivalence. Reports are for reading; JSON supplies the machine boundary. Environment names use a separate color family from headings and ordinary variables, without making color a semantic guarantee. The static pager restores styles on actual soft-wrap rows and resizes from logical source text rather than inserting hard newlines.

mant is ManT's local-first documentation command. It turns native man/mdoc pages and Markdown libraries into one catalog exposed as an interactive TUI, a deterministic structured CLI, and a read-only stdio MCP server. Every interface consumes the same normalized document model.

mant git                              # interactive reader in a terminal
mant gcc --outline                    # semantic hierarchy for an agent
mant tar --explain=--exclude          # collect documented option evidence
mant --input README.md --node 1       # select one Markdown section
mant git --format json --compact      # deterministic machine output
mant --mcp                            # read-only MCP over stdio

Install

Download a supported prebuilt GitHub Release through cargo-binstall:

cargo binstall mant

Or compile from crates.io:

cargo install mant --locked

Source builds require Rust 1.88+ and a C compiler. Linux and macOS additionally require zlib development headers; Windows uses the checked MSVC memory-parser configuration without a system zlib.

Targets without a matching archive fall back from cargo binstall to a Cargo source build. Public macOS archives remain disabled until they can be signed and notarized.

Interactive reader

An ordinary complete query opens the reader when standard input and output are terminals. Use --display tui to require it explicitly:

mant git
mant --input README.md --display tui

The reader provides a resizable outline, collapsible sections, semantic option nodes, settled-scroll following, typed in-page and cross-document links, back/forward history, full-document search, keyboard and mouse input, and optional tldr quick references before the full document. Ctrl+O opens the shared Markdown and native-manual catalog. The upper-right tab stack keeps successfully opened documents in first-open order and restores each tab's last selected semantic node. Safe external links are handed asynchronously to the platform URL handler; WSL uses the Windows handler when it is available, and the child process cannot read from or write into the TUI terminal streams. A success notice confirms that handoff started, not that a browser accepted it. Redirected output stays deterministic instead of emitting terminal control sequences.

Visual selections copy automatically, while the Edit menu can copy a complete semantic node as deterministic text or structurally complete CommonMark. Local sessions prefer the native clipboard and fall back to write-only OSC 52. WSL, SSH, and VS Code remote sessions prefer OSC 52 so compatible outer terminals and multiplexers can forward the copy to the user's clipboard. Right-clicking inside the document copies the retained visual selection again when the mouse event reaches ManT. OSC 52 payloads are limited to 400 KiB before Base64 encoding; native clipboard delivery retains the reader-wide 4 MiB limit. This terminal protocol has no acknowledgement, so a terminal that disables OSC 52 can silently ignore an emitted copy request.

Help, diagnostics, and tldr output share a terminal-aware colour policy. Use --color auto|always|never; automatic mode respects terminal capability, NO_COLOR, and TERM=dumb, while structured formats stay undecorated.

Document discovery follows the same rule: long terminal text is pageable, while short, redirected, JSON, and explicit --display direct output stays direct.

mant --list
mant --find git
mant --find git --display direct
mant --find git --format json

Structured queries for agents and scripts

Discover the document before selecting only the content that matters:

mant gcc --outline
mant ssh --explain=-L
mant git --tldr
mant gcc --node 4.2 --format markdown
mant tar --explain=--exclude
mant tar --search=--acls --context 1
mant git --search worktree --follow-links
mant --document git --document git-lfs --explain=--work-tree

Repeated --document values form an ordered query set. --follow-links adds typed native-manual and same-source Markdown destinations with bounded breadth-first traversal. Search and explain each use one global offset/nextOffset across the set. Explain orders direct entries, explicitly related entries, mentions in other entries and ordinary mentions before paging; within a class it preserves BFS document and original IR order. Explain preserves independent same-name owners, original forms/content, literal support and explicit alias relationships; it never chooses a first result as uniquely correct. Readable no-evidence queries succeed with an explicit outcome; partial source failures retain available evidence and coverage. Interactive search spans the same pre-resolved set while ordinary document discovery remains global.

Compact explanation output shows full direct/related definitions and bounded match windows for mentions. For example, GCC's -Q mentioning --help remains a mention, not an alias. All four category counts distinguish collected totals from this page; use the read coordinate with --node for complete original content. Group context is returned/displayed once on the same page, even when the strict original node has only its own head. Preview clipping, body omission and support omission are reported separately. Consumers of structured explain must resolve declaration-member content through the source-local support pool.

Explanation pages default to 50 owners (--limit, maximum 256). --offset continues the result set; --explain-content-bytes bounds copied facts/forms, previews and original bodies (default 1 MiB, maximum 4 MiB). Omitted bodies retain their strict --node location. MCP's character pages remain independent.

All document queries, including --request-json, default to text and can explicitly select Markdown or JSON. Full reading still opens the TUI on an interactive terminal; redirected output is plain text. --preserve-anchors explicitly selects Markdown unless a format is given. A complete native roff manual also supports --format man for manual-only plain text without tldr content.

--display auto|direct|pager|tui independently controls presentation. Automatic full reading uses the TUI; other terminal-owned text queries use the built-in pager only when they exceed the screen. direct forbids either interactive interface. Explicit pager and tui require usable stdin/stdout terminals; JSON cannot be paged, and stdin documents/request JSON remain noninteractive. Explicit formats disable automatic TUI selection; Markdown and man can be paged only when explicitly requested. Doctor, help, and maintenance reports stay direct by default. The removed --ui and --no-pager flags are replaced by --display tui and --display direct. The default outline returns section topology plus compact entry coverage. --outline-entries none|summary|all|KINDS controls expansion, while --outline-root focuses the result on one exact section or semantic entry. Expanded entries preserve nested command/parameter/value relationships and keep exact aliases separate from complete authored forms. A stateless agent can start with the default summary, reuse a path or ID from that current response as --outline-root, expand only that subtree with --outline-entries, and finally pass a returned selector to --node. Do not guess from display titles, and rediscover after the underlying document changes. Entry paths remain source-order coordinates; generated native IDs avoid source-order collision suffixes and unrelated-section renumbering. Text projections use semantic ANSI styles on capable terminals and remain plain under redirection by default; --color always explicitly forces text styling. Markdown, JSON, man, and MCP never contain ANSI presentation styling. Terminal-bound Markdown masks control characters in dynamic document identities, while redirected full/excerpt Markdown preserves those data bytes exactly. The independent explanation text/CommonMark presentation always masks controls, including data supplied by unchecked in-process IR producers. Search results carry reusable outline selectors and exact generated-Markdown coordinates. Machine consumers can discover the authoritative contracts from the installed executable:

mant --doctor
mant --doctor --format json --compact
mant --schema request
mant --schema all --compact
mant --protocol-version

mant --doctor checks the effective local installation without network access, external processes, or mutations. Text is intended for people; JSON uses the independent mant.doctor/v1 report contract, discoverable with mant --schema doctor. Warnings keep a successful exit status, while a broken promised capability exits with status 1.

mant --mcp exposes read-only discovery, outline, excerpt, explanation, and search over stdio JSON-RPC. Its five tools return bounded plain text or CommonMark rather than serializing full AST envelopes. MCP stdout contains protocol messages only; use CLI JSON output to inspect lowering diagnostics. Malformed, excessively nested, and oversized input lines receive bounded errors without ending the session once the offending newline has been drained. Every successful tool result begins with a mant-page header reporting the Unicode-scalar character interval and full canonical body size. Clients select a bounded maxChars budget and resume statelessly with startChar; semantic maxResults and maxMatches limits remain separate from presentation paging. Discovery exposes literal or regex matching and case policy; search exposes visible or generated-Markdown scope. Both use result offset/nextOffset independently from character startChar/nextChar paging.

Document sources

On Linux, macOS, and Windows, ManT indexes raw, gzip, and zstd manual sources and parses their roff through bundled libmandoc. It does not require a system man or mandoc executable at runtime. A leaf manual-page symlink may point outside its indexed root, but directory symlinks are not traversed and every .so target must remain inside that root. Windows defaults to %APPDATA%\ManT\man, followed by the compatible %USERPROFILE%\.local\share\man fallback, and also honors configured manual paths. Its optional %APPDATA%\ManT\man.conf accepts direct and mandatory roots, bounded fragments, PATH mappings, quoted paths, and one-pass %NAME% expansion; mant --doctor reports malformed directives without stopping ordinary document lookup.

Reusable Markdown documents can be registered by relative path below:

• Linux: ${XDG_DATA_HOME:-$HOME/.local/share}/mant/documents
• macOS: ~/Library/Application Support/ManT/documents
• Windows: %APPDATA%\ManT\documents

Regular Markdown files are discovered recursively with their hierarchy. Personal documents/ may use leaf-file symlinks to regular files, including external targets; directory and broken links are ignored. Managed source caches never follow links. Git or direct archive sources configured in sibling sources.toml can be installed with mant --update-docs and selected with --source. Removed source tables are reported as orphaned installed data; preview cleanup with mant --prune-docs --dry-run and apply it with mant --prune-docs. An unqualified path or unique component suffix resolves root documents first. Sources then sort around native manuals at priority zero: positive sources win, manuals win a zero tie, and non-positive sources are fallbacks. Omitted source priority defaults to one. See the complete document-source guide.

When compatible local tldr data exists, a combined query that selects a native section 1 or 8 family page prepends it as reserved outline node 0. --tldr selects only that node, while --manual selects only native manual content and excludes the quick reference. --man-section selects an exact native full document without disabling a compatible command quick reference. Explicit tldr lookup compares embedded Markdown quick references using their document priority; cached tldr and native manuals share the built-in priority-zero baseline. Markdown without an embedded quick reference is skipped. Reads prefer installed-client caches and then ManT's private cache; mant --update-tldr updates through an installed client or the private checkout. If no full document exists, an ordinary query fails with an explicit mant NAME --tldr hint instead of opening a tldr-only reader.

One-off physical input uses mant --input PATH; Markdown and plain/gzip/zstd roff files are supported. Standard input additionally requires --input-format markdown|roff. Manual selectors accept mant 1 git, mant 'git(1)', and mant manual/1/git. A dotted selector such as git.1 remains an exact logical name and is never guessed to be a manual shorthand.

Crate architecture

Official/default builds enable all five capabilities. Custom Cargo builds can disable them with --no-default-features and opt in individually:

The minimal build retains Markdown, cached quick references, pure queries, direct text/JSON output, schema output and offline inspection. Native manual catalogs are read-only metadata and remain discoverable without roff; their presence does not promise that this build can parse those pages. A native read then returns an explicit capability error. CLI flags and display values for disabled execution capabilities are omitted, while versioned schemas continue describing the complete contract. Automatic display only chooses compiled capabilities; without an applicable reader or pager it writes directly.

mant::run_process is now synchronous and owns a runtime only for an explicitly selected MCP session. Native-process callers no longer await it; callers already inside an async runtime should use the narrower libraries rather than nesting the process entry point. mant::run remains the injectable stream interface.

• mant-ir defines the source-neutral in-memory document and quick-reference model.
• mant-protocol defines shared query contracts, logical projections, versioned JSON DTOs, and stable semantic labels.
• libmandoc-rs owns the cross-platform libmandoc parser boundary.
• mant-sources owns local Markdown discovery and optional source updates.
• mant-codec parses Markdown and optional native roff and encodes document Markdown.
• mant-loader owns bounded local acquisition, catalogs, caches, and linked-document snapshots.
• mant-query projects and searches already loaded IR without loading or rendering.
• mant-render formats content and DTO reports without querying or controlling a terminal.
• mant-engine composes complete validated requests over loading and pure queries.
• mant-ui provides the source-neutral Ratatui frontend.
• mant owns command-line, terminal-selection, and MCP process boundaries.

Within the command host, CLI input adaptation and output dispatch are separate from typed application navigation, system services, and process delivery. The crate root exposes stream and native-process entry points; the private process adapter alone chooses terminal delivery and owns native stdio policy. The native reader records each attempted terminal acquisition before executing it, including partial writes. Its backend and outer session share one cleanup ledger: restoration runs in reverse acquisition order, attempts every pending operation, retains the first error, and retries only failed releases on drop. The embeddable UI never acquires these process resources. Signal handlers only record termination; ordinary host code restores modes before applying the signal's exit behavior. Uncatchable signals cannot be recovered. CliHost/SystemHost retain the injectable service boundary; maintenance lives under the host rather than in the read-only engine. Schema output is an offline adapter, and CLI and MCP share DTO renderers without sharing CLI format types.

Creating a command host does not discover local sources. Complete requests and catalog filters are validated before its first document snapshot is captured; subsequent reads and discovery within that operation or reader session reuse the same snapshot. Help, schema output, malformed requests and direct stdin parsing do not initialize the resolver. There is no process-global document cache. Normal CLI requests use the engine's complete request pipeline, as MCP does, instead of independently combining loading and projection.

The package also exposes mant::run for deterministic single-invocation tests or embedding with explicit input/output streams, and mant::run_process for the real terminal-sensitive process including MCP. Most library users should prefer the narrower component crate matching their boundary instead of embedding the complete command host.

The complete user manual, protocol reference, and release archives live in the ManT repository. Compatibility and migration notes are recorded in the crate changelog.

License

Apache-2.0. Native builds also contain the separately attributed upstream mandoc sources distributed by libmandoc-rs; downloaded tldr-pages content is CC BY 4.0 and is attributed when rendered.