xnatctl CLI Reference

Description

--- name: xnatctl description: Use when running xnatctl commands, writing scripts that call xnatctl, troubleshooting XNAT CLI operations, or helping users with XNAT neuroimaging server administration via the command line. Triggers on mentions of xnatctl, XNAT CLI, session download/upload, prearchive, scan management, or XNAT project administration. --- # xnatctl CLI Reference Modern CLI for XNAT neuroimaging server administration. Resource-centric commands with consistent output formats, parallel operations, and profile-based configuration. ## Command Hierarchy ``` xnatctl config init | show | use-context | current-context | add-profile | remove-profile auth login | logout | status | test project list | show | create subject list | show | rename | delete session list | show | download | upload | upload-exam scan list | show | delete | download resource list | show | upload | download prearchive list | archive | delete | rebuild | move pipeline list | run | status | jobs | cancel admin refresh-catalogs | user add | audit dicom validate | inspect | list-tags | anonymize (requires xnatctl[dicom]) api get | post | put | delete (raw REST escape hatch) whoami health ping completion [bash|zsh|fish] ``` ## Global Options (all commands) | Flag | Short | Description | |------|-------|-------------| | `--profile` | `-p` | Named profile from config | | `--output` | `-o` | `json` or `table` (default: table) | | `--quiet` | `-q` | IDs only output | | `--verbose` | `-v` | Debug logging | ## Parent-Resource Options (session & scan commands) | Flag | Short | Purpose | Key Rule | |------|-------|---------|----------| | `--project` | `-P` | Project ID | Enables label lookup for -E | | `--subject` | `-S` | Subject ID/label | Used in `session list` (filter) and `session upload` | | `--experiment` | `-E` | Experiment ID or label | **Labels require -P** (explicit or via profile `default_project`) | **Critical**: `-E LABEL` without `-P` fails. `-E XNAT_E00001` (accession ID) works without `-P`. ## Quick Reference: Common Commands ### Setup & Auth ```bash # Initialize config with profile xnatctl config init --url https://xnat.example.org --profile myserver # Add another profile xnatctl config add-profile prod --url https://prod.xnat.org --project DEFAULT_PROJ # Switch profiles xnatctl config use-context prod # Login (prompts for credentials if not in config/env) xnatctl auth login -p myserver # Test connection xnatctl auth test ``` ### Projects & Subjects ```bash # List projects xnatctl project list # Show project details xnatctl project show MYPROJ # List subjects with filter (NOTE: colon syntax, not equals) xnatctl subject list -P MYPROJ --filter "label:CTRL_*" # Delete subject (with safety) xnatctl subject delete SUB001 -P MYPROJ --dry-run xnatctl subject delete SUB001 -P MYPROJ --yes ``` ### Sessions ```bash # List sessions in project xnatctl session list -P MYPROJ # Show session (by label - needs -P) xnatctl session show -P MYPROJ -E MR_Session_01 # Show session (by accession ID - no -P needed) xnatctl session show -E XNAT_E00001 # Download session - single ZIP (default) xnatctl session download -P MYPROJ -E MR_Session_01 --out ./data # Download session - parallel per-scan (workers > 1) xnatctl session download -P MYPROJ -E MR_Session_01 --out ./data -w 8 ``` ### Uploads ```bash # Upload DICOM directory (parallel batches) xnatctl session upload ./dicoms -P NEURO -S SUB001 -E SESS001 --workers 4 # Upload DICOM archive file xnatctl session upload ./archive.tar -P NEURO -S SUB001 -E SESS001 # Gradual per-file upload (parallel) xnatctl session upload ./dicoms -P NEURO -S SUB001 -E SESS001 --gradual --workers 16 # Upload exam root (DICOM + resources) # Directory structure: top-level dirs become resources, DICOMs found recursively xnatctl session upload-exam ./exam_root -P NEURO -S SUB001 -E SESS001 -w 4 # Attach resources only (skip DICOM upload) xnatctl session upload-exam ./exam_root -P NEURO -S SUB001 -E SESS001 --attach-only ``` **upload vs upload-exam**: `upload` handles DICOM files only. `upload-exam` handles a mixed directory (DICOMs + non-DICOM resource files like PDFs, spreadsheets). In upload-exam, top-level directories become session-level resources by name. ### Scans ```bash # List scans xnatctl scan list -E XNAT_E00001 # Delete specific scans (comma-separated with -s flag) xnatctl scan delete -E XNAT_E00042 -P BRAIN -s 1,3,5 --dry-run xnatctl scan delete -E XNAT_E00042 -P BRAIN -s 1,3,5 --yes # Delete ALL scans xnatctl scan delete -E XNAT_E00042 -s "*" --yes # Download scans as ZIP xnatctl scan download -E XNAT_E00001 -s 1,2,3 --out ./scans ``` ### Resources ```bash # List resources on session xnatctl resource list XNAT_E00001 # List resources on scan xnatctl resource list XNAT_E00001 --scan 1 # Upload file/directory as resource xnatctl resource upload XNAT_E00001 MY_RESOURCE ./data/ # Download resource xnatctl resource download XNAT_E00001 MY_RESOURCE --file ./output.zip ``` ### Prearchive **Note**: Prearchive commands use POSITIONAL args: `PROJECT TIMESTAMP SESSION_NAME` ```bash # List prearchive sessions xnatctl prearchive list xnatctl prearchive list --project MYPROJ # Archive (move to main archive) xnatctl prearchive archive MYPROJ 20240115_143022 SessionFolder # Delete from prearchive xnatctl prearchive delete MYPROJ 20240115_143022 SessionFolder --yes # Rebuild (refresh metadata) xnatctl prearchive rebuild MYPROJ 20240115_143022 SessionFolder # Move to different project xnatctl prearchive move MYPROJ 20240115_143022 SessionFolder TARGET_PROJ ``` ### Pipelines ```bash # List pipelines xnatctl pipeline list --project MYPROJ # Run pipeline and wait for completion xnatctl pipeline run dcm2niix -e XNAT_E00001 -P key1=val1 -P key2=val2 --wait # Check job status (with watch mode) xnatctl pipeline status JOB_ID --watch # Cancel job xnatctl pipeline cancel JOB_ID --yes ``` ### Admin ```bash # Refresh catalogs with parallel workers xnatctl admin refresh-catalogs MYPROJ -O checksum -O populateStats --parallel --workers 8 # Add user to project groups xnatctl admin user add jsmith Owners --projects MYPROJ # View audit log xnatctl admin audit -P MYPROJ --since 7d --limit 50 ``` ### Raw API (escape hatch) ```bash # GET with query parameters (use -P key=value, NOT query strings in path) xnatctl api get /data/projects/MYPROJ/subjects -P format=json # POST with data xnatctl api post /data/projects -d '{"ID":"NEW_PROJ","name":"New Project"}' # DELETE with confirmation skip xnatctl api delete /data/experiments/XNAT_E00001 --yes ``` ### DICOM Tools (requires `xnatctl[dicom]`) ```bash # Validate DICOM files xnatctl dicom validate ./dicoms -r # Inspect headers xnatctl dicom inspect ./scan.dcm -t PatientID -t Modality # Anonymize xnatctl dicom anonymize ./input ./output --patient-id ANON001 --remove-private -r ``` ## Configuration **Config file**: `~/.config/xnatctl/config.yaml` ```yaml default_profile: default output_format: table profiles: default: url: https://xnat.example.org verify_ssl: true timeout: 21600 # 6 hours (default for large transfers) default_project: MYPROJ username: admin # optional password: secret # optional ``` **Environment variables** (priority: CLI args > env vars > profile > prompt): | Variable | Purpose | |----------|---------| | `XNAT_TOKEN` | Session token (**highest auth priority**, skips credential prompt) | | `XNAT_URL` | Server URL (auto-creates `default` profile) | | `XNAT_USER` | Username | | `XNAT_PASS` | Password | | `XNAT_PROFILE` | Active profile | | `XNAT_VERIFY_SSL` | `true`/`false` | | `XNAT_TIMEOUT` | Timeout seconds | ## Gotchas 1. **`-o` is output FORMAT** (`json`/`table`), NOT output directory. Use `--out` for download destination. 2. **Filter uses colon**: `--filter "label:CTRL_*"` not `label=CTRL_*`. 3. **Scan IDs use `-s` flag**: `-s 1,3,5` (comma-separated) or `-s "*"` (all). NOT positional args. 4. **Prearchive uses positional args**: `PROJECT TIMESTAMP SESSION_NAME`. NOT `-P`/`-E` flags. 5. **API params use `-P key=value`**: NOT query strings appended to path. 6. **Workers flag varies**: session download uses `-w`, upload uses `--workers`. Both control parallelism. 7. **`-P` flag is overloaded**: In session/scan commands, `-P` means `--project`. In `api` and `pipeline` commands, `-P` means parameter (`key=value`). Context matters. 8. **Default timeout is 6 hours** (21600s) for large DICOM transfers. 9. **upload-exam waits for archive**: By default waits for XNAT to finish archiving before attaching resources. Control with `--wait-for-archive`/`--no-wait-for-archive`. 10. **`default_project` fallback**: If profile has `default_project`, `-P` can be omitted and session/scan commands auto-resolve. ## Safety Decorators Destructive commands include `--yes/-y` (skip confirmation) and `--dry-run` (preview only). **Always use `--dry-run` first** for delete/rename operations. Parallel commands include `--parallel/--no-parallel` and `--workers N`.

Security Status