Configuration

Pass a YAML profile with the root --config option:

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

Profile shape

dicom_kb:
  edition: 2025e
  artifact_dir: /data/dicom-standard-kb
  database_url: sqlite:////data/dicom-standard-kb/db/2025e.sqlite
  allow_text_retrieval: true
  max_text_excerpt_chars: 800
  require_citations: true
  require_edition_pin: true
  allow_network_fetch: false
  use_synthetic_fixtures_only: false
  require_dicom_download_for_integration: true
  publish_generated_db: false

The top-level document and dicom_kb mapping reject unknown fields. The 2025e value is a concrete historical example; replace it with the edition recorded by your build.

Field reference

Field	Type and validation	Current effect
`edition`	string or null	Supplies the default edition for command paths that resolve an edition.
`artifact_dir`	path or null	Supplies the local cache directory.
`database_url`	local `sqlite:///` URL or null	Supplies an explicit database path. Other schemes and nonlocal URLs are rejected.
`allow_text_retrieval`	boolean or null	Accepted policy metadata; no direct CLI enforcement call site in the documented source state.
`max_text_excerpt_chars`	integer at least 1 or null	Supplies the default text-retrieval cap.
`require_citations`	boolean or null; `false` rejected	A profile cannot disable citation requirements.
`require_edition_pin`	boolean or null	Accepted policy metadata; current acquisition/build commands already require concrete storage but this field is not a separate runtime gate.
`allow_network_fetch`	boolean or null	Accepted policy metadata; does not currently disable `fetch` by itself.
`use_synthetic_fixtures_only`	boolean or null	Accepted policy metadata; does not currently switch command availability.
`require_dicom_download_for_integration`	boolean or null	Accepted policy metadata; integration tests use their own environment controls.
`publish_generated_db`	boolean or null	Accepted policy metadata; does not authorize or perform publication. Generated database redistribution remains prohibited by project policy.

Recheck the policy-field column for each stable release because additional enforcement may be added later.

Environment variables

Current CLI resolution reads:

Variable	Meaning
`DICOM_KB_EDITION`	Default edition.
`DICOM_KB_CACHE_DIR`	Default cache directory.
`DICOM_KB_DATABASE_URL`	Local SQLite URL for an explicit database.
`DICOM_KB_MAX_TEXT_EXCERPT_CHARS`	Default maximum excerpt characters.

Examples:

export DICOM_KB_EDITION=2025e
export DICOM_KB_CACHE_DIR=/data/dicom-standard-kb
export DICOM_KB_DATABASE_URL=sqlite:////data/dicom-standard-kb/db/2025e.sqlite
export DICOM_KB_MAX_TEXT_EXCERPT_CHARS=800

Precedence

For values supported by all layers:

CLI option > environment variable > YAML profile > built-in default

An explicit --db path overrides DICOM_KB_DATABASE_URL and database_url. An explicit --cache-dir overrides the environment and artifact_dir.

Built-in defaults

Setting	Default
Cache	`~/.cache/dicom-standard-kb`
Conventional database	`<cache>/db/<edition>.sqlite`
Text excerpt maximum	`800` characters
Text search result limit	`10`
Module macro expansion	disabled
Storage backend	`sqlite`
MCP transport	`stdio`
External agent timeout	`300` seconds
Synthetic fixture edition	`2026b`

Most commands do not have a universal edition default. Supply a profile, environment value, or CLI option.

SQLite URL examples

Absolute POSIX path:

sqlite:////data/dicom-standard-kb/db/2025e.sqlite

Home-relative path after shell expansion should be written as the resulting local path. The model requires a local sqlite:/// URL and rejects a URL with a network location.

Profile errors

The CLI rejects:

invalid YAML;
a non-mapping root;
a missing dicom_kb envelope;
unknown fields;
database_url with a non-SQLite or nonlocal form;
max_text_excerpt_chars below 1;
require_citations: false.

A profile can be syntactically valid while containing policy metadata that is not an active runtime switch. Use this reference rather than inferring enforcement from a field name.