CLI quickstart¶

This page provides a minimal, task-oriented introduction to the BrkRaw command-line interface. The examples are intended for first-time users who want to inspect and convert Paravision datasets from the terminal.

Inspect a dataset (brkraw info)¶

Print a structured overview of a Paravision dataset, including study-level and scan-level information.

brkraw info /path/to/study

This command works with dataset directories, zip archives, and Paravision-exported .PvDatasets files.

To include detailed scan and reconstruction information:

brkraw info /path/to/study --scope full

Inspect scan parameters (brkraw params)¶

Search acquisition or reconstruction parameters across scans.

brkraw params /path/to/study PVM_RepetitionTime

Limit the search to a specific scan:

brkraw params /path/to/study PVM_RepetitionTime --scan-id 3

This is useful for verifying protocol settings before conversion.

Convert a scan to NIfTI (brkraw convert)¶

Convert a single scan using the default reconstruction.

brkraw convert /path/to/study --scan-id 3

Specify a reconstruction ID and output directory:

brkraw convert /path/to/study \
    --scan-id 3 \
    --reco-id 1 \
    --out ./nifti_out

Output filenames and directory structure are controlled by the configured layout entries and templates.

Generate sidecar metadata¶

Write metadata sidecars alongside the converted NIfTI files.

brkraw convert /path/to/study \
    --scan-id 3 \
    --reco-id 1 \
    --write-metadata

The content of sidecar metadata is determined by context maps, rules, and specs.

Convert multiple scans (batch-style usage)¶

Convert all available scans in a dataset using a shell loop.

for sid in 1 2 3 4; do
    brkraw convert /path/to/study \
        --scan-id $sid \
        --reco-id 1 \
        --out ./nifti_out
done

For large-scale automation, consider using the Python API.

Manage addons (brkraw addon)¶

List installed addons (rules, specs, hooks):

brkraw addon list

Add a new addon:

brkraw addon add /path/to/spec.yaml

Remove an installed addon:

brkraw addon remove spec.yaml

When to use the CLI¶

The CLI is best suited for:

Interactive inspection of datasets
One-off or small batch conversions
Verifying metadata and scan IDs
Running conversions in shell-based workflows

For complex logic, conditional processing, or large-scale automation, use the Python API instead.