CLI reference

The executable is dicom-kb. From a source checkout, prefix examples with uv run.

Root command

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

Option	Meaning
--version	Print dicom-standard-kb <version> and exit.
--config PATH	Load a validated YAML profile with a top-level dicom_kb mapping. Must appear before the command.
--help	Show Typer help for the current command or group.

The application groups commands under lookup, iod, module, resolve, context, explain, mcp, and eval.

Diagnostics

doctor

dicom-kb doctor

Prints package version and the project legal notice. It does not inspect the cache or database.

Source acquisition

fetch

dicom-kb fetch [OPTIONS]

Fetches official artifacts or registers local DocBook XML and writes a source manifest.

Option	Type/default	Meaning
--edition TEXT	required unless profile/environment supplies it	current or a concrete 20YYx edition.
--docbook-xml PART=PATH	repeatable	Register a local DocBook XML file instead of official download.
--part PART	repeatable; baseline set when omitted	Official part to download. Input such as 6 normalizes to PS3.6.
--format FORMAT	repeatable; docbook_xml when omitted	docbook_xml, pdf, html, chtml, or targetdb.
--mirror-chtml-tree	false	Recursively mirror the selected per-part CHTML directory. Requires --format chtml.
--current-edition TEXT	none	Concrete edition used to resolve current when registering local artifacts.
--source-base-url URL	official current URL	Override the current-release base URL.
--archive-base-url URL	official archive root	Override the historical archive root.
--cache-dir PATH	configured/default cache	Local cache root.
--force	false	Overwrite conflicting cached artifacts and manifest.

Default DocBook parts:

PS3.3, PS3.4, PS3.5, PS3.6, PS3.7, PS3.8, PS3.10, PS3.16, PS3.18

Official current discovery requires one concrete edition to be identifiable. A concrete historical edition must appear in the official archive listing.

Output is a serialized source manifest.

Build commands

build-fixture

dicom-kb build-fixture [OPTIONS]

Registers repository-authored synthetic fixtures and builds SQLite.

Option	Default	Meaning
--edition TEXT	2026b	Synthetic fixture edition label.
--cache-dir PATH	default cache	Fixture artifact cache.
--db PATH	<cache>/db/<edition>.sqlite	Output database.
--force	false	Overwrite fixture artifacts, manifest, and database.
--max-unresolved-xref-rate FLOAT	unset	Fail above this 0–1 rate.
--max-unresolved-include-rate FLOAT	unset	Fail above this 0–1 rate.
--max-parse-warnings INTEGER	unset	Fail above this nonnegative count.
--allow-gate-failures	false	Keep exit status successful while retaining gate failures as warnings.

The command expects the repository’s tests/fixtures_synthetic tree to be available.

build

dicom-kb build [OPTIONS]

Builds a local SQLite knowledge base from cached DocBook artifacts.

Option	Default	Meaning
--edition TEXT	required unless configured	Concrete edition whose manifest will be loaded.
--cache-dir PATH	default cache	Cache containing the source manifest and artifacts.
--db PATH	<cache>/db/<edition>.sqlite	Output database.
--backend TEXT	sqlite	Storage backend. Any other value is rejected.
--force	false	Replace an existing target database.
quality-gate options	unset	Same options as build-fixture.

Output is a build summary with edition, database path, manifest digest, per-import summaries, metrics, gate failures, and warnings.

verify

dicom-kb verify [OPTIONS]

Verifies a source manifest, artifact checksums, and optional database metadata.

Option	Default	Meaning
--edition TEXT	required unless configured	Concrete edition to verify.
--cache-dir PATH	default cache	Cache root.
--db PATH	<cache>/db/<edition>.sqlite	Database to inspect.

The command exits nonzero when top-level verification status is failed.

Exact lookup commands

All query commands accept:

• --edition TEXT;
• --db PATH;
• --cache-dir PATH.

When --db is absent, the path resolves from configuration or <cache>/db/<edition>.sqlite.

lookup tag

dicom-kb lookup tag TAG_OR_KEYWORD [OPTIONS]

Looks up a PS3.6 data element by concrete tag, range tag, or keyword.

lookup uid

dicom-kb lookup uid UID_OR_KEYWORD [OPTIONS]

Looks up a PS3.6 UID registry entry by UID value or keyword.

lookup vr

dicom-kb lookup vr VR [OPTIONS]

Looks up a two-letter PS3.5 Value Representation.

lookup transfer-syntax

dicom-kb lookup transfer-syntax UID_OR_KEYWORD [OPTIONS]

Looks up a Transfer Syntax by UID value, name, or keyword and returns linked encoding details.

lookup media-type

dicom-kb lookup media-type MEDIA_TYPE_OR_CONTEXT [OPTIONS]

Looks up parsed media-type constraints by media type or service context.

lookup dicomweb

dicom-kb lookup dicomweb NAME_OR_ROUTE [OPTIONS]

Looks up a PS3.18 DICOMweb transaction by transaction name or route template.

lookup sr-template

dicom-kb lookup sr-template TID_OR_NAME [OPTIONS]

Looks up a PS3.16 SR template by TID or exact name.

lookup context-group

dicom-kb lookup context-group CID_OR_NAME [OPTIONS]

Looks up a PS3.16 context group by CID or exact name.

lookup code

dicom-kb lookup code CODE_VALUE [--scheme SCHEME] [OPTIONS]

Looks up a parsed PS3.16 coded concept by code value and optional coding scheme designator.

lookup iod

dicom-kb lookup iod IOD_NAME [OPTIONS]

Looks up a PS3.3 IOD by name or keyword.

lookup sop-class

dicom-kb lookup sop-class UID_OR_NAME_OR_KEYWORD [OPTIONS]

Looks up a PS3.4 SOP Class and linked IOD records.

lookup enumerated-values

dicom-kb lookup enumerated-values ATTRIBUTE [--context CONTEXT] [OPTIONS]

Looks up parsed enumerated values by attribute tag, keyword, or name. Context can narrow by exact imported module, macro, IOD, or SOP Class identity.

lookup defined-terms

dicom-kb lookup defined-terms ATTRIBUTE [--context CONTEXT] [OPTIONS]

Uses the same input model as enumerated-value lookup but preserves defined_term as a distinct term kind.

Graph commands

iod modules

dicom-kb iod modules IOD_NAME [OPTIONS]

Lists PS3.3 module-use rows for an IOD.

module attributes

dicom-kb module attributes MODULE_NAME [--expand-macros | --no-expand-macros] [OPTIONS]

Lists PS3.3 attribute and include rows for a module. Macro expansion defaults to false.

Context commands

resolve attribute-context

dicom-kb resolve attribute-context ATTRIBUTE [--iod IOD] [--sop-class SOP_CLASS] [OPTIONS]

Resolves applicable attribute-use rows and a bounded effective type.

context attribute

dicom-kb context attribute ATTRIBUTE [--iod IOD] [--sop-class SOP_CLASS] [OPTIONS]

Documented alias for the same resolver and response.

Explanation and text commands

explain encoding

dicom-kb explain encoding TOPIC [OPTIONS]

Returns a cited PS3.5 encoding explanation for a topic, VR, or Transfer Syntax name.

search-text

dicom-kb search-text QUERY [--part PART] [--limit INTEGER] [OPTIONS]

Searches persisted DocBook text with SQLite FTS5.

Option	Default
--part PART	no part filter
--limit INTEGER	10

retrieve-text

dicom-kb retrieve-text PART SECTION_OR_ANCHOR [--max-chars INTEGER] [OPTIONS]

Retrieves a bounded persisted-text excerpt by DICOM part and DocBook xml:id, HTML anchor, or section number.

--max-chars defaults to 800 unless overridden by environment or profile.

MCP command

mcp serve

dicom-kb mcp serve --edition EDITION [--db PATH] [--cache-dir PATH]

Validates the database, registers all query tools, and runs FastMCP over stdio. MCP support requires the optional dependency.

Evaluation commands

eval run

dicom-kb eval run --out PATH [OPTIONS]

Runs committed agent-regression cases.

Option	Default	Meaning
--out PATH	required	Transcript JSON destination.
--edition TEXT	required unless configured	Database edition.
--db PATH	default database	Local knowledge base.
--cache-dir PATH	default cache	Cache root.
--case ID / --cases ID	repeatable; all cases	Select case ids.
--agent TEXT	reference	reference or external.
--external-command TEXT	none	Command receiving JSON stdin and emitting AgentRun JSON stdout.
--external-provider TEXT	none	Optional provider label.
--external-model TEXT	none	Optional model label.
--external-timeout FLOAT	300	External command timeout in seconds.

eval score

dicom-kb eval score TRANSCRIPT [OPTIONS]

Scores one run, a run list, or an object containing a top-level runs list.

Option	Default	Meaning
--output PATH	stdout	Write JSON report to a file.
--fail-on-issues / --no-fail-on-issues	fail enabled	Control nonzero exit when any run fails scoring.

Query output

All lookup, graph, context, explanation, and text commands serialize the common response envelope as indented JSON with null fields omitted.

status: "not_found" and status: "validation_error" are normal structured query outcomes. Operational failures such as a missing database, invalid CLI option, failed build gate, or missing MCP dependency produce a nonzero command exit.