CLI reference

The Rust binary is the source of truth for viewer startup.

dcmview [OPTIONS] <PATH> [PATH ...]

At least one DICOM file or directory path is required in normal use. Repeat paths to combine inputs in one temporary viewer.

Options

Option	Default	Description
<PATH>...	required	DICOM file or directory to inspect.
-p, --port <PORT>	0	HTTP port. 0 asks the operating system for an available port.
--host <ADDR>	127.0.0.1	Interface to bind. Non-loopback values broaden access to the unauthenticated server.
--no-browser	off	Print the viewer URL instead of opening the default browser.
--timeout <SECONDS>	none	Exit after this many seconds without API or browser requests.
--no-recursive	off	Scan only the top level of input directories.
--annotations <CSV>	none	Load an EMBED-style ROI CSV into memory without modifying it.
--filter <FIELD=VALUE>	none	Include only matching DICOM metadata; repeatable.
--tunnel	off	Start the optional SSH local-forward helper after viewer startup.
--tunnel-host <SSH_HOST>	none	SSH destination such as user@example.org; required with --tunnel.
--tunnel-port <PORT>	0	Local forwarded port; 0 reuses the viewer port.
-h, --help	—	Print help.
-V, --version	—	Print the version.

--startup-json and --vscode-bridge-client exist for wrapper and VS Code integration. They are hidden and are not ordinary user-facing options.

Metadata filters

Accepted field names are:

• patient_id
• patient_name
• study_description
• study_date
• study_uid
• series_description
• series_number
• series_uid
• modality

Field names are case-insensitive. Values use case-insensitive substring matching, and repeated filters use AND semantics.

dcmview \
  --filter Modality=CT \
  --filter PatientID=phantom \
  ./study

Readable DICOM objects that fail a filter are counted as filtered rather than skipped.

SSH helper options

The built-in helper runs only when --tunnel is present. --tunnel-host must also be set. A zero --tunnel-port uses the same numeric port as the bound viewer; a non-zero value chooses a different local forwarded port.

dcmview \
  --no-browser \
  --port 8888 \
  --tunnel \
  --tunnel-host user@workstation \
  ./study

The helper manages an SSH subprocess and readiness check. Failure to establish forwarding is reported without corrupting viewer shutdown. For the ordinary remote-server pattern, use the explicit SSH forwarding guide.

Exit behavior

The command exits non-zero when startup validation fails, no valid DICOM files are discovered, the server cannot bind, or an owned integration returns a failure. Once running, Ctrl+C, idle timeout, or an integration stop request begins graceful shutdown and cancels or joins discovery work.

Individual unreadable files, unsupported pixel layouts, and request-scoped decode errors do not normally stop a mixed dataset viewer.

Python module command

The module command mirrors the visible Rust options and forwards them to the resolved binary:

python -m dcmview_py [OPTIONS] <PATH> [PATH ...]

It runs in blocking mode and returns the binary’s exit status. See the Python reference for programmatic sessions.