CLI Reference¶

This is the complete command reference for xnatctl. Every command family, sub-command, and option is documented here. If you are new to xnatctl, start with the Quick Start guide for a hands-on introduction.

Common Command Options¶

Most resource-oriented commands (for example project, subject, session, scan, resource, prearchive, pipeline, admin, and api) accept these common options:

Option	Description
`--profile TEXT` / `-p`	Select a configuration profile for this command. Overrides the default profile and the `XNAT_PROFILE` environment variable.
`--output TEXT` / `-o`	Output format: `json` or `table` (default: `table`). JSON is useful for scripting and piping into tools like `jq`. Not to be confused with the `--out` flag on download commands, which specifies a filesystem destination path.
`--quiet` / `-q`	Suppress non-essential output; print only IDs.
`--verbose` / `-v`	Enable verbose/debug logging (HTTP requests, retries, timing).
`--help`	Show the help message for any command or sub-command.

These options are command-level options and should be passed after the sub-command path. For example:

$ xnatctl project list --output json

Note

Top-level utility groups such as config, auth, completion, local, health, and dicom expose their own options and do not universally support --quiet or --verbose.

Command Summary¶

The table below lists every command family with a one-line description.

Command	Description
`config`	Manage configuration profiles and switch environments
`auth`	Authenticate and manage session tokens
`project`	List, inspect, and create projects
`subject`	Manage subjects within a project
`session`	List, inspect, download, and upload imaging sessions
`scan`	Manage individual scans within a session
`resource`	Manage file resources attached to sessions or scans
`prearchive`	Manage the prearchive staging area
`pipeline`	Run and monitor processing pipelines
`admin`	Administrative operations (catalogs, users, audit)
`api`	Raw REST API access (escape hatch)
`local`	Offline operations on downloaded data (extract ZIPs)
`dicom`	DICOM validation and inspection utilities
`whoami`	Show current user and authentication context
`health`	Server connectivity and version checks
`completion`	Generate shell completion scripts (bash/zsh/fish)

config¶

Use config to create and manage connection profiles. Each profile stores a server URL, default project, SSL settings, and timeout. Switch between profiles to target different XNAT environments without re-entering connection details.

config init – Create a configuration file with an initial profile
config add-profile – Add a named profile to an existing configuration
config use-context – Switch the active (default) profile
config show – Display the current configuration and all profiles
config current-context – Print the name of the active profile
config remove-profile – Remove a named profile

Set up xnatctl for the first time with your server URL:

$ xnatctl config init --url https://xnat.example.org

Add a development profile with SSL verification disabled:

$ xnatctl config add-profile dev --url https://xnat-dev.example.org --no-verify-ssl

Switch the active profile and review settings:

$ xnatctl config use-context dev
$ xnatctl config show

Tip

Set default_project when creating a profile (--project MYPROJ) to avoid passing -P on every command. See Configuration for full details.

auth¶

The auth commands handle authentication against an XNAT server. xnatctl caches a session token locally so you do not re-authenticate on every command. Tokens expire after 15 minutes of inactivity; xnatctl re-authenticates automatically.

auth login – Authenticate and cache a session token
auth logout – Invalidate the session on the server and clear the local cache
auth status – Show the current authentication state (cached session, env vars)
auth test – Test connectivity by making a live request to the server

$ xnatctl auth login
$ xnatctl auth status

Note

Credentials resolve in priority order: CLI arguments > environment variables (XNAT_USER, XNAT_PASS) > profile configuration > interactive prompt. Set XNAT_TOKEN to skip credential-based authentication entirely.

xnatctl also provides two top-level utility commands:

whoami – Show the authenticated user, server, profile, and auth mode
health ping – Check server connectivity, version, and latency

$ xnatctl whoami
$ xnatctl health ping

project¶

The project commands let you list accessible projects, inspect details (including subject and session counts), and create new projects. These are typically the first commands you run after authenticating.

project list – List all projects you have access to
project show – Display detailed information about a specific project
project create – Create a new project on the server
project transfer – Transfer project data to another XNAT instance
project transfer-check – Pre-flight connectivity and permissions check
project transfer-status – Show status of the last transfer run
project transfer-history – Show full transfer history for a project
project transfer-init – Generate a starter transfer configuration YAML

List projects as a table or JSON, inspect one, or create a new project:

$ xnatctl project list
$ xnatctl project list --output json
$ xnatctl project show MYPROJECT
$ xnatctl project create NEWPROJ --name "New Project" --pi Smith

Transfer a project to another XNAT server:

$ xnatctl project transfer-check -P SRC --dest-profile staging --dest-project DST
$ xnatctl project transfer -P SRC --dest-profile staging --dest-project DST --dry-run
$ xnatctl project transfer -P SRC --dest-profile staging --dest-project DST --yes

Tip

Use -q with project list to get a plain list of project IDs for scripting: xnatctl project list -q | head -5.

For detailed transfer documentation, configuration, and filtering options, see Transferring Data Between XNAT Servers.

subject¶

The subject commands manage subjects (participants) within a project. You can list, inspect, delete, and rename subjects. The rename sub-command supports mapping files, regex-based pattern matching, and per-project patterns files for bulk label normalization.

subject list – List subjects in a project (includes session counts)
subject show – Display subject details and associated sessions
subject delete – Delete a subject and all its sessions (requires confirmation)
subject rename – Rename subjects using a mapping file, regex, or patterns file

List and inspect subjects:

$ xnatctl subject list -P MYPROJ
$ xnatctl subject show SUB001 -P MYPROJ

Delete with a dry-run preview, then confirm:

$ xnatctl subject delete SUB001 -P MYPROJ --dry-run
$ xnatctl subject delete SUB001 -P MYPROJ --yes

Rename subjects using a patterns file (first matching rule wins):

$ xnatctl subject rename -P MYPROJ --patterns-file patterns.json --dry-run

Note

The rename command supports merging: if the target label already exists, xnatctl moves experiments from the source into the target rather than failing.

session¶

The session commands let you list, inspect, download, and upload imaging sessions (experiments). Sessions are the primary data containers in XNAT, holding scans and resources. This is the command family you will use most for day-to-day data management.

session list – List sessions, optionally filtered by subject or modality
session show – Display session details including scans and resources
session download – Download session data (scans and optional resources)
session upload – Upload DICOM data via REST import
session upload-exam – Upload a scanner exam-root directory (DICOM + top-level resources)
session upload-dicom – Upload DICOM files via C-STORE network protocol

Parent-resource options. The -E and -P flags identify experiments:

Option	Description
`-E` / `--experiment`	Experiment ID (accession number) or label. Required for `show`, `download`. Labels require `-P` so xnatctl can resolve them within a project.
`-P` / `--project`	Project ID. Enables label lookup with `-E`. Falls back to profile `default_project`.

Tip

If your profile has default_project set, you can pass -E with a session label without explicitly providing -P. See Configuration for details.

List MR sessions for a subject:

$ xnatctl session list -P MYPROJ --subject SUB001 --modality MR

Show session details by accession number or by label with project context:

$ xnatctl session show -E XNAT_E00001
$ xnatctl session show -E SESSION_LABEL -P MYPROJ

Download a session with parallel workers:

$ xnatctl session download -E XNAT_E00001 --out ./data --workers 8

Upload DICOM files via REST (batch or gradual per-file):

$ xnatctl session upload ./dicoms -P MYPROJ -S SUB001 -E SESS001
$ xnatctl session upload ./dicoms -P MYPROJ -S SUB001 -E SESS001 --mode gradual -w 40

Upload a scanner exam-root directory (DICOM + top-level resources):

$ xnatctl session upload-exam ./exam_root -P MYPROJ -S SUB001 -E SESS001

session upload-exam attaches top-level resources after the DICOM import. By default, it waits for the session to appear in the permanent archive before attaching resources.

Archive wait options (`session upload-exam`)¶
Option	Description
`--wait SECONDS`	Seconds to wait for the session to appear in the archive (default: `900`). Set to `0` to skip waiting.

Upload via DICOM C-STORE (requires the [dicom] extra):

$ xnatctl session upload-dicom ./dicoms --host xnat.example.org --called-aet XNAT

Note

Use --dry-run on download and upload commands to preview what would happen without transferring data.

For detailed transfer workflows, see Downloading Data and Uploading Data.

scan¶

The scan commands manage individual scans within a session. These commands follow the same -E / -P convention as session commands for identifying the parent experiment.

scan list – List scans with type, series description, and quality
scan show – Display scan details and attached resources
scan delete – Delete one or more scans (supports parallel deletion)
scan download – Download specific scans by ID

List scans and show details:

$ xnatctl scan list -E XNAT_E00001
$ xnatctl scan show -E SESSION_LABEL 1 -P MYPROJ

Delete scans with dry-run preview:

$ xnatctl scan delete -E XNAT_E00001 --scans 1,2,3 --dry-run

Download specific scans or all scans at once:

$ xnatctl scan download -E XNAT_E00001 -s 1,2 --out ./data --extract
$ xnatctl scan download -E XNAT_E00001 -s '*' --out ./data

Tip

Use -r / --resource with scan download to download a specific resource type (e.g., -r DICOM or -r NIFTI).

For more download patterns, see Downloading Data.

resource¶

The resource commands manage file collections attached to sessions or scans. Resources are labeled containers (e.g., DICOM, NIFTI, BIDS) that hold files.

resource list – List resources at session or scan level
resource show – Display resource details and file listing
resource upload – Upload a file or directory to a resource
resource download – Download a resource as a ZIP archive

List resources at session and scan level:

$ xnatctl resource list XNAT_E00001
$ xnatctl resource list XNAT_E00001 --scan 1

Upload files and download resources:

$ xnatctl resource upload XNAT_E00001 NIFTI ./file.nii.gz
$ xnatctl resource upload XNAT_E00001 DICOM ./dicoms --scan 1
$ xnatctl resource download XNAT_E00001 DICOM --file ./dicom.zip
$ xnatctl resource download XNAT_E00001 DICOM --file ./scan1.zip --scan 1

Note

When uploading a directory, xnatctl archives it and extracts it server-side. The resource label is created automatically if it does not already exist.

prearchive¶

The prearchive is a staging area where XNAT holds uploaded data before formal archiving. Data lands here via DICOM C-STORE or REST import with the prearchive flag. You review sessions and either archive them into the project hierarchy or delete them. For more on this concept, see Key Concepts.

prearchive list – List sessions in the prearchive
prearchive archive – Move a session into the permanent archive
prearchive delete – Permanently delete a prearchive session
prearchive rebuild – Rebuild/refresh a session (re-parses headers)
prearchive move – Move a session to a different project

List and archive prearchive sessions:

$ xnatctl prearchive list --project MYPROJ
$ xnatctl prearchive archive MYPROJ 20240115_120000 Session1
$ xnatctl prearchive archive MYPROJ 20240115_120000 Session1 --subject SUB001

Move a session to another project:

$ xnatctl prearchive move MYPROJ 20240115_120000 Session1 OTHERPROJ

Tip

The three positional arguments (PROJECT, TIMESTAMP, SESSION_NAME) uniquely identify a prearchive entry. Find them with prearchive list.

pipeline¶

The pipeline commands discover, launch, monitor, and cancel processing pipelines on the XNAT server. Pipelines are server-side workflows (e.g., dcm2niix, FreeSurfer) that operate on experiments.

pipeline list – List available pipelines
pipeline run – Launch a pipeline on an experiment
pipeline status – Check a job’s status
pipeline jobs – List pipeline jobs with optional filters
pipeline cancel – Cancel a running job

List pipelines and run one with parameters:

$ xnatctl pipeline list --project MYPROJ
$ xnatctl pipeline run dcm2niix --experiment XNAT_E00001 --wait
$ xnatctl pipeline run myproc -e XNAT_E00001 --param param1=value1

Check status or watch a job until completion:

$ xnatctl pipeline status JOB123
$ xnatctl pipeline status JOB123 --watch
$ xnatctl pipeline jobs --status Running
$ xnatctl pipeline cancel JOB123 --yes

admin¶

The admin commands provide server administration operations. These typically require elevated privileges on the XNAT server.

admin refresh-catalogs – Refresh catalog XMLs for experiments in a project
admin user add – Add a user to one or more XNAT groups
admin audit – View the audit log (depends on server configuration)

Refresh catalogs with checksum generation and stale entry cleanup:

$ xnatctl admin refresh-catalogs MYPROJ --option checksum --option delete
$ xnatctl admin refresh-catalogs MYPROJ --experiment XNAT_E00001

Add a user to project groups and view audit entries:

$ xnatctl admin user add jsmith --projects PROJ1,PROJ2 --role member
$ xnatctl admin audit --project MYPROJ --limit 20

Note

Catalog refresh runs in parallel by default (4 workers). Use --workers 1 for sequential execution or --workers N to control concurrency.

For detailed admin workflows, prerequisites, and workarounds for tasks not yet exposed as CLI commands, see Site Administration.

api¶

The api commands provide a raw REST escape hatch for XNAT endpoints not covered by dedicated commands. This is useful for one-off queries, automation, or accessing newer API endpoints that xnatctl does not yet wrap.

api get – GET request to any endpoint
api post – POST with optional JSON body or file payload
api put – PUT with optional JSON body or file payload
api delete – DELETE (requires confirmation or --yes)

Query, create, update, and delete resources directly:

$ xnatctl api get /data/projects
$ xnatctl api get /data/projects/MYPROJ/subjects --params columns=ID,label -o json
$ xnatctl api post /data/projects --data '{"ID": "NEWPROJ"}'
$ xnatctl api put /data/projects/MYPROJ --data '{"description": "Updated"}'
$ xnatctl api delete /data/projects/MYPROJ/subjects/SUB001 --yes

Tip

api get automatically formats XNAT ResultSet responses as tables in table output mode, so you get readable output without extra processing.

dicom¶

The dicom commands provide local DICOM file utilities that do not require an XNAT connection. They require the optional [dicom] extra (pip install xnatctl[dicom]).

dicom validate – Validate files for required tags and structural integrity
dicom inspect – Inspect DICOM headers for a single file
dicom list-tags – List all tags present in a file
dicom anonymize – Remove or replace identifying tags

Install and use DICOM utilities:

$ pip install "xnatctl[dicom]"
$ xnatctl dicom validate /path/to/dicoms -r
$ xnatctl dicom inspect /path/to/file.dcm
$ xnatctl dicom inspect /path/to/file.dcm --tag PatientID --tag Modality
$ xnatctl dicom anonymize /input/dir /output/dir -r --patient-id ANON001

Note

These commands are independent of the XNAT server. Use them to pre-validate or anonymize files before uploading with session upload or session upload-dicom.

For detailed documentation on each DICOM command, installation of the optional extra, and workflow examples, see DICOM Utilities.

local¶

The local commands perform offline operations on previously downloaded data. They do not require an XNAT connection.

local extract – Extract ZIP files from downloaded sessions into organized directory structures

Extract downloaded session ZIPs:

$ xnatctl local extract ./data/XNAT_E00001
$ xnatctl local extract ./data --recursive
$ xnatctl local extract ./data --recursive --no-cleanup
$ xnatctl local extract ./data --recursive --dry-run

Tip

Use local extract when you downloaded sessions without --extract and want to extract them later. The --cleanup flag (on by default) removes ZIP files after successful extraction.

completion¶

The completion commands generate shell auto-completion scripts for bash, zsh, and fish. Once installed, pressing Tab completes command names, options, and sub-commands.

completion bash – Generate bash completion script
completion zsh – Generate zsh completion script
completion fish – Generate fish completion script

Install completions for your shell:

# Bash
$ xnatctl completion bash > ~/.local/share/bash-completion/completions/xnatctl

# Zsh (add ~/.zfunc to fpath in .zshrc first)
$ mkdir -p ~/.zfunc
$ xnatctl completion zsh > ~/.zfunc/_xnatctl

# Fish
$ xnatctl completion fish > ~/.config/fish/completions/xnatctl.fish

After installing, restart your shell or source your shell config file for completions to take effect.

Getting Help¶

You can get help for any command by appending --help:

$ xnatctl --help
$ xnatctl session --help
$ xnatctl session download --help