CLI reference

dicom-kb [--config PATH] [--version] COMMAND [ARGS]...

--config loads a YAML profile. Run dicom-kb COMMAND --help for the same information from the tool itself.

Shared query options

Every query command (element, iod, module, values, code, search, read) and mcp serve accepts:

Option	Meaning
--edition TEXT	Edition to query, e.g. 2026d. Defaults to the newest built edition.
--db PATH	A database file. Defaults to <cache-dir>/db/<edition>.sqlite.
--cache-dir PATH	The cache directory. Defaults to ~/.cache/dicom-standard-kb.

Query commands print markdown to standard output. A database built by an older version of the code is refused with a message to rebuild it.

Build commands

fetch

Downloads the current edition’s DocBook XML from NEMA into <cache-dir>/artifacts/<edition>/ and writes a manifest with each file’s SHA-256.

Option	Meaning
--part TEXT	A part to download, e.g. PS3.3. Repeatable. Defaults to all 20 parts.
--docbook-xml PART=PATH	Register a local DocBook file instead of downloading. Repeatable.
--edition TEXT	Edition label for --docbook-xml files. Required with that option.
--source-base-url TEXT	Base URL of the release. Defaults to https://dicom.nema.org/medical/dicom/current/.
--cache-dir PATH	Cache directory.
--force	Replace files already in the cache.

The edition label is read from the release listing, so fetch always takes whatever NEMA currently publishes.

build

Builds a SQLite knowledge base from fetched files.

Option	Meaning
--edition TEXT	Edition to build. Defaults to the newest fetched edition.
--db PATH	Output file. Defaults to <cache-dir>/db/<edition>.sqlite.
--cache-dir PATH	Cache directory.
--backend TEXT	Only sqlite is supported.
--force	Replace an existing database.

The build is staged and only replaces the live database when it completes. It logs gaps to <edition>.gaps.txt next to the database and prints the count per part.

build-fixture

Builds a small knowledge base from the synthetic fixtures in a source checkout. Takes --edition (default 2026b), --cache-dir, --db and --force.

Query commands

element NAME

A data element by tag, keyword or name, and the modules that use it. --iod TEXT shows its Type and nesting in one IOD instead.

iod NAME

An IOD by name, or by SOP Class name, UID or keyword, with its modules.

Option	Meaning
--expand	List the attributes of its M and C modules, macros expanded.
--type TEXT	Keep these Types, e.g. 1,1C, or required for 1, 1C, 2 and 2C. Implies --expand.
--usage TEXT	Module usages to list, default M,C. M,C,U adds U modules. Implies --expand.
--module TEXT	Only these modules, comma-separated. Implies --expand.
--page N	Read a later page.

module NAME

A module or macro by name, or a table such as C.7-5a. By default an outline: its own rows, each macro as one line, descriptions cut to their first sentence and condition.

Option	Meaning
--full	Expand macros in place, with full descriptions.
--type TEXT	Keep these Types, as for iod, with macros expanded.
--page N	Read a later page.

values NAME

An attribute’s Enumerated Values, Defined Terms and context groups. --within TEXT keeps only what applies in an IOD, module or macro. --page N reads a later page.

code QUERY

A context group (CID 4031), template (TID 1500), code value or name from PS3.16. --scheme TEXT names the coding scheme of a code value, e.g. DCM. --page N reads a later page.

search QUERY

Ranked sections and tables that match the words. --part TEXT limits it to one part, e.g. PS3.5. --limit N sets the number of hits (default 10, at most 30).

read REF

A section, table, annex, CID or TID (PS3.5 7.5.2, Table C.7-5a, CID 7010), a UID or UID keyword, or a VR code (OB). --page N reads a later page.

MCP tools describes each answer in more detail.

Other commands

mcp serve

Runs the MCP server over stdio. Takes the shared query options and fails at startup if the database is missing or stale. See Connect an MCP client.

doctor

Prints the version and the project’s legal notice.