Query with the CLI

The dicom-kb CLI prints machine-readable JSON for query commands. Use it for ad hoc investigation, shell automation, and verifying the same resolver behavior exposed through Python and MCP.

Prerequisites

You need:

• a concrete edition label;
• a matching local SQLite knowledge base;
• the database at the conventional cache path or an explicit --db path.

The examples below use <concrete-edition>. Replace it with the edition stored in your source manifest and database.

Understand the command shape

A normal query has:

uv run dicom-kb <command> <input> \
  --edition <concrete-edition>

Add an explicit database when it is outside the default cache:

uv run dicom-kb <command> <input> \
  --edition <concrete-edition> \
  --db /path/to/dicom-kb.sqlite

A root configuration option must precede the subcommand:

uv run dicom-kb --config ./dicom-kb.yaml lookup tag Modality

Registry lookups

Data element by tag or keyword

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb lookup tag '(0008,0060)' \
  --edition "$EDITION"

uv run dicom-kb lookup tag Modality \
  --edition "$EDITION"

UID by value or keyword

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb lookup uid ExplicitVRLittleEndian \
  --edition "$EDITION"

IOD and SOP Class lookups

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb lookup iod 'CT Image' \
  --edition "$EDITION"

uv run dicom-kb lookup sop-class 'CT Image Storage' \
  --edition "$EDITION"

Use graph commands when you need composition rather than identity:

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb iod modules 'CT Image' \
  --edition "$EDITION"

uv run dicom-kb module attributes Patient \
  --edition "$EDITION"

See Explore IODs, modules, and attributes for a complete traversal.

Encoding and transport lookups

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb lookup vr PN \
  --edition "$EDITION"

uv run dicom-kb lookup transfer-syntax ExplicitVRLittleEndian \
  --edition "$EDITION"

uv run dicom-kb explain encoding 'Explicit VR Little Endian' \
  --edition "$EDITION"

The first two commands prefer structured facts. explain encoding returns a bounded explanation and optional text excerpt with a different evidence classification.

DICOMweb and media lookups

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb lookup dicomweb RetrieveStudy \
  --edition "$EDITION"

uv run dicom-kb lookup media-type application/dicom \
  --edition "$EDITION"

A DICOMweb transaction can also be addressed by its route template when the match is deterministic. Ambiguous route matches return candidates rather than choosing one silently.

Content-mapping lookups

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb lookup sr-template 1500 \
  --edition "$EDITION"

uv run dicom-kb lookup context-group 29 \
  --edition "$EDITION"

uv run dicom-kb lookup code CT \
  --scheme DCM \
  --edition "$EDITION"

Generated PS3.16 content is for local citation-preserving lookup. Do not turn these commands into a bulk terminology export.

Value terms

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb lookup enumerated-values PatientSex \
  --edition "$EDITION"

uv run dicom-kb lookup defined-terms Modality \
  --context 'CT Image' \
  --edition "$EDITION"

Provide context when one attribute has terms in more than one module, macro, IOD, or SOP Class usage.

Contextual requiredness

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb resolve attribute-context Modality \
  --iod 'CT Image' \
  --edition "$EDITION"

The documented alias calls the same resolver:

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb context attribute Modality \
  --iod 'CT Image' \
  --edition "$EDITION"

Do not infer a stricter requirement when effective_type is null. Follow the returned references and warnings.

Text search and retrieval

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb search-text 'transfer syntax' \
  --part PS3.6 \
  --limit 10 \
  --edition "$EDITION"

Retrieve one bounded section or anchor after search:

EDITION=2025e  # Replace with your concrete edition.
SECTION_OR_ANCHOR='replace-with-search-result'
uv run dicom-kb retrieve-text PS3.6 "$SECTION_OR_ANCHOR" \
  --max-chars 800 \
  --edition "$EDITION"

Interpret every response

Check these fields before using a result:

1. status
2. result
3. refs
4. warnings
5. classification
6. parse_confidence
7. trace.source_manifest_sha256

A command can complete normally with status: "not_found" or status: "validation_error". These are structured query outcomes, not permission to fill in the answer from memory.

See Response envelope and CLI reference for exact details.