Configure shared defaults

Use a YAML profile when several commands should share the same concrete edition, cache, and database.

Create a profile

dicom-kb.yaml

dicom_kb:
  edition: 2025e
  artifact_dir: /data/dicom-standard-kb
  database_url: sqlite:////data/dicom-standard-kb/db/2025e.sqlite
  max_text_excerpt_chars: 800
  require_citations: true

The top-level key must be dicom_kb. Unknown keys are rejected. The 2025e value is a concrete historical example; replace it with the edition recorded by your build.

An absolute Unix SQLite path uses four slashes after the scheme:

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

Only local sqlite:/// URLs are accepted by the current profile model.

Pass the profile before the subcommand

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

The --config option belongs to the root command. Do not place it after lookup tag.

Override one value

CLI values take precedence:

uv run dicom-kb --config ./dicom-kb.yaml lookup tag Modality \
  --edition 2025e

The complete precedence order is:

CLI option
environment variable
YAML profile
built-in default

Use environment variables

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

Then run a command without repeating those options:

uv run dicom-kb lookup tag Modality

Understand policy-oriented profile fields

The schema also accepts policy fields such as:

dicom_kb:
  allow_text_retrieval: true
  require_edition_pin: true
  allow_network_fetch: false
  use_synthetic_fixtures_only: false
  require_dicom_download_for_integration: true
  publish_generated_db: false

In the documented source state, current CLI command paths do not use these fields as enforcement switches. Treat them as validated profile metadata unless the selected release documents additional enforcement.

require_citations is special: the profile rejects false, so a profile cannot disable citation requirements.

See Configuration reference for every field, environment variable, validation rule, and current runtime effect.