xnatctl
A modern command-line interface for XNAT neuroimaging server administration.
xnatctl lets you browse projects and subjects, download and upload imaging
sessions, run processing pipelines, and perform administrative tasks -- all
from your terminal, in the resource-centric style of kubectl:
xnatctl <resource> <action> [args].
Get Started
1. Install
Pick one:
# Standalone binary, no Python required (Linux/macOS, auto-detects platform)
curl -fsSL https://github.com/rickyltwong/xnatctl/raw/main/install.sh | bash
# Python package (needs Python 3.11+)
pip install xnatctl
A Docker image is also published (ghcr.io/rickyltwong/xnatctl:main) for CI
pipelines and containerized environments. Windows binaries, manual downloads,
Docker usage, shell completion, and troubleshooting are covered in the
Installation guide.
2. Connect to your server
xnatctl config init --url https://xnat.example.org # create a config profile
xnatctl auth login # log in; the session token is cached
xnatctl project list # verify: list projects you can access
3. Download a DICOM session
Find a session, then pull its imaging data to your machine:
# List the sessions in a project
xnatctl session list -P MYPROJECT
# Download one session by accession number (or by label, with -P)
xnatctl session download -E XNAT_E00001 --out ./data --extract
With --extract you get one directory per scan with the DICOM files ready
for analysis; without it, the downloaded ZIP archives are kept as-is.
4. Download a session-level resource
Sessions can carry non-DICOM resources (behavioral data, physio logs, derived outputs). List what a session has, then fetch one by label:
# See which resources the session carries
xnatctl resource list XNAT_E00001
# Download one resource as a ZIP
xnatctl resource download XNAT_E00001 LINKED_DATA -f linked_data.zip
That is the core loop. The Quick Start guide continues from here with uploads, batch operations, and scripting patterns.
Commands
xnatctl config # Manage configuration profiles
xnatctl auth # Authentication (login/logout/status)
xnatctl project # Project operations (list/show/create/transfer)
xnatctl subject # Subject operations (list/show/rename/delete)
xnatctl session # Session operations (list/show/download/upload)
xnatctl scan # Scan operations (list/show/delete/download)
xnatctl resource # Resource operations (list/upload/download)
xnatctl prearchive # Prearchive management (list/archive/delete/move)
xnatctl pipeline # Pipeline execution (list/run/status/cancel)
xnatctl xsync # Cross-server sync (sync/status/history)
xnatctl admin # Administrative operations (users/catalogs/audit)
xnatctl api # Raw API access (escape hatch for any endpoint)
xnatctl local # Offline operations (extract downloaded ZIPs)
xnatctl dicom # DICOM utilities (validate/inspect/anonymize/modify)
xnatctl whoami | health | completion # identity, server ping, shell completion
Resource-oriented commands support --output json|table and --quiet (IDs
only), so the same command works interactively and in scripts. Full usage and
examples are in the CLI Reference.
Configuration
Profiles live in ~/.config/xnatctl/config.yaml and store connection details
per server:
default_profile: production
profiles:
production:
url: https://xnat.example.org
username: myuser # optional -- can also use env vars
password_source: keyring # password lives in the OS keychain
default_project: MYPROJECT
development:
url: https://xnat-dev.example.org
ca_bundle: /etc/ssl/dev-ca.pem # trust a private CA instead of
# switching verification off
xnatctl config add-profile dev --url https://xnat-dev.example.org # add a server
xnatctl config use-context dev # switch profiles
xnatctl config set-password production # store password in the OS keychain
Credential priority, highest first: XNAT_TOKEN (an existing session token,
skips login entirely), then --username with --password-stdin, then
XNAT_USER/XNAT_PASS environment variables, then the profile config, then
an interactive prompt. Environment variables are the natural fit for CI jobs
and non-interactive scripts.
Passwords are never accepted as a command-line value.
--password secretis a usage error, because argv is visible inpsand your shell history. Use--password-stdin,XNAT_PASS, a stored profile credential, or the prompt.
Use as a Python library
xnatctl is CLI-first, but the same client and service layer is fully
importable, and the top-level xnatctl namespace is a semver-covered surface
(see the Stability policy):
import xnatctl
with xnatctl.XNATClient.from_profile("prod") as client:
client.downloads.download_resource(
"XNAT_E00001", "DICOM", "./data", extract=True
)
from_profile resolves credentials from a saved config profile the same way
the CLI does, and the client logs in on entry when a password is available and
no session token is cached yet. The core resource types each have a bound
accessor on the client -- client.projects, client.subjects,
client.sessions, client.scans, client.resources, client.downloads,
client.uploads, client.prearchive, client.pipelines, client.admin,
client.hierarchy, client.exam_uploads -- and errors come back as typed
exceptions:
try:
client.projects.get("MYPROJECT")
except xnatctl.SessionExpiredError:
... # re-authenticate and retry
Full reference: API docs.
Features
- Resource-centric commands --
xnatctl project list,xnatctl session download,xnatctl scan show. - Profile-based configuration -- one config file for all your servers;
switch with
--profileorconfig use-context. - Consistent output --
--output json|tableand--quiet, built for both humans and pipes. - Parallel operations -- batch uploads and downloads fan out across
multiple workers (
--workers) with real-time progress. - Cached authentication -- log in once and the session token is cached; commands re-authenticate automatically when stored credentials allow it.
- Pure HTTP -- talks directly to the XNAT REST API via httpx, no dependency on pyxnat or xnatpy. xnatctl is CLI-first -- and ships as a single binary with no Python environment required -- but the same client and services are also a supported Python library; see Use as a Python library above.
Development
git clone https://github.com/rickyltwong/xnatctl.git
cd xnatctl
uv sync --dev
uv run pytest tests/ -v # tests
uv run ruff check xnatctl tests scripts # lint
uv run mypy xnatctl # type check
Support policy
- Python: 3.11-3.13, tracking CI. A version is dropped within one MINOR release of its CPython end-of-life.
- XNAT: 1.8.x and later. See the XNAT Compatibility guide for what is actually tested versus expected to work.
- Releases: cut on demand by the maintainer, no fixed cadence. This is a single-maintainer project; plan around that when depending on it.
- Security reports: see SECURITY.md.
License
MIT
Metadata
Release files for xnatctl 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xnatctl-0.6.0.tar.gz | 1.1 MB | With provenance | Details for xnatctl-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xnatctl-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for xnatctl-0.6.0-py3-none-any.whl |
Total release size: 1.6 MB
Release files / xnatctl-0.6.0.tar.gz
| Download URL | xnatctl-0.6.0.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f939286eb65050c04290c833721a89a2dd314ed82074b28132105d420a68644a
|
|
BLAKE2b-256 checksum How to use checksums |
d05443d77f5382b202eeeed639c0912136c5cc26944223e6e717b92239c45ed2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logRelease files / xnatctl-0.6.0-py3-none-any.whl
| Download URL | xnatctl-0.6.0-py3-none-any.whl |
|---|---|
| Size | 520.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
09e4498828cf9dbf896eabd05b05471b76b82e9c80aa7a88ac4714b41fe8a6c4
|
|
BLAKE2b-256 checksum How to use checksums |
9e420b757583cfa475effd635fcf81465f5fb9f722014464bca3ca20f6d89eb0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logSecurity for xnatctl 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for xnatctl-0.6.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.