npu-docs-cli

Portable command-line search for offline AscendC, CCE, CANN Runtime, and PTO-ISA documentation.

It is designed for operator developers and coding agents that need fast, scriptable access to local documentation without running an MCP server.

What It Does

• Searches the SQLite FTS5 indexes produced by huawei-csl/npu-coding-mcp.
• Reads the original Markdown sections from the corresponding documentation directory.
• Searches and reads PTO-ISA Markdown files directly.
• Emits human-readable output by default or JSON with --json.
• Has no runtime dependencies and does not require an Ascend device.

This project contains the query client only. It intentionally does not redistribute CANN documentation or generated indexes. Those files have their own source and licensing terms and should be obtained from the upstream documentation project or official sources.

Install

python3 -m venv .venv
.venv/bin/pip install .

For development:

.venv/bin/pip install -e '.[dev]'

Prepare Documentation Data

The easiest setup downloads the public data bundle into the user cache:

npu-docs init
npu-docs search ascendc Matmul -n 5
npu-docs api runtime aclrtMalloc

By default init downloads the data/ directory from the upstream huawei-csl/npu-coding-mcp repository into ~/.cache/npu-docs/data. It downloads the documentation once and reuses it on later runs. Select only the domains you need:

npu-docs init --domain ascendc
npu-docs init --domain cce --domain runtime

For offline, mirrored, or enterprise environments, use a local data root or an archive URL:

npu-docs --data-root /path/to/data search ascendc Matmul -n 5
npu-docs init --source-url https://mirror.example/npu-coding-mcp-main.tar.gz

The data root must contain matching pairs such as:

ascendc_docs/       ascendc_index.db
cce_docs/           cce_index.db
runtime_docs/       runtime_index.db

You can set NPU_DOCS_DATA_ROOT instead of passing --data-root:

export NPU_DOCS_DATA_ROOT=/path/to/npu-coding-mcp/data

For PTO-ISA, pass the docs/ directory of a local cann/pto-isa checkout:

npu-docs --data-root /path/to/data --pto-docs /path/to/pto-isa/docs search isa TMATMUL -n 5
npu-docs --data-root /path/to/data --pto-docs /path/to/pto-isa/docs section isa isa/TMATMUL_MX.md

NPU_DOCS_PTO_DOCS can be used instead of --pto-docs.

Commands

# Full-text search
npu-docs --data-root ./data search ascendc '双缓冲' -n 8
npu-docs --data-root ./data search cce vadd -n 8
npu-docs --data-root ./data search runtime stream -n 8

# API-focused lookup
npu-docs --data-root ./data api ascendc Matmul
npu-docs --data-root ./data api cce vadd
npu-docs --data-root ./data api runtime aclrtMalloc

# Read a section; path comes from search output
npu-docs --data-root ./data section ascendc '06_API参考/.../Cast.md'

# Browse documentation
npu-docs --data-root ./data chapters ascendc
npu-docs --data-root ./data tree ascendc '06_API参考'

# Machine-readable output
npu-docs --data-root ./data --json search ascendc Matmul -n 3

Global options must appear before the subcommand, as shown above. Paths are treated as relative to the selected documentation root and are checked against path traversal.

Agent Integration

A Skill or shell wrapper can call the CLI directly. This avoids MCP server lifecycle and tool-discovery overhead while retaining deterministic, pipe-friendly output:

npu-docs --data-root "$NPU_DOCS_DATA_ROOT" api ascendc Matmul

License

The CLI code is MIT licensed. The default data bundle is downloaded from the upstream npu-coding-mcp repository at runtime and is not included in this source distribution. The CLI records the source URL in npu-docs-source.json; consult the upstream repository and official documentation source for the data terms.