xnatctl
A modern command-line interface for XNAT neuroimaging server administration.
What is xnatctl?
xnatctl is a command-line tool for managing neuroimaging data on XNAT servers.1 It lets you browse projects and subjects, download and upload imaging sessions, run processing pipelines, and perform administrative tasks -- all from your terminal. Whether you are a researcher downloading data for analysis or a system administrator managing hundreds of subjects, xnatctl provides a consistent, scriptable interface to your XNAT server.
Features
-
Resource-centric commands -- interact with XNAT the way you think about it:
xnatctl project list,xnatctl session download,xnatctl scan show. Every command follows the patternxnatctl <resource> <action> [args]. -
Profile-based configuration -- manage multiple XNAT servers with named profiles and switch between them instantly. Keep separate profiles for production, development, and collaboration servers in a single config file.
-
Consistent output formats -- resource-oriented commands support
--output json|tableand--quiet(IDs only), so you can pipe results into scripts or read them in a human-friendly table without changing your workflow. -
Parallel operations -- batch uploads and downloads run across multiple workers with real-time progress tracking. Large transfers stay fast without extra scripting.
-
Session authentication -- log in once with
xnatctl auth loginand your session token is cached locally. Expired tokens are refreshed automatically, so you stay authenticated without repeated prompts. -
Pure HTTP -- xnatctl talks directly to the XNAT REST API using httpx. Existing Python libraries like pyxnat and xnatpy inspired this project, but they are excellent Python libraries intended to be imported into your own code. xnatctl exists for the complementary use case: a CLI-first workflow where you want to explore resources, automate API interactions from shell scripts, and run common administrative tasks without writing a bespoke Python program.
The command structure and UX borrow from tools like
kubectlandairflowctl: resource-centric subcommands, consistent flags, and output you can read as a human or pipe into other tools. xnatctl ships as a standalone CLI that can be installed as a single binary (no Python environment required).
Installation
Standalone Binary (no Python required)
If you do not have Python installed or prefer a single executable, download a pre-built binary. On Linux and macOS, the install script auto-detects your OS and architecture:
# One-line install (Linux/macOS only, auto-detects platform)
curl -fsSL https://github.com/rickyltwong/xnatctl/raw/main/install.sh | bash
# Install a specific version
XNATCTL_VERSION=v0.1.0 curl -fsSL https://github.com/rickyltwong/xnatctl/raw/main/install.sh | bash
# Custom install directory (default: ~/.local/bin)
XNATCTL_INSTALL_DIR=/usr/local/bin curl -fsSL https://github.com/rickyltwong/xnatctl/raw/main/install.sh | bash
Or download manually from GitHub Releases:
| Platform | Asset |
|---|---|
| Linux (x86_64) | xnatctl-linux-amd64.tar.gz |
| macOS (x86_64) | xnatctl-darwin-amd64.tar.gz |
| Windows (x86_64) | xnatctl-windows-amd64.zip |
Linux / macOS:
tar -xzf xnatctl-<platform>-amd64.tar.gz
chmod +x xnatctl
mv xnatctl ~/.local/bin/
Windows (PowerShell):
Expand-Archive xnatctl-windows-amd64.zip -DestinationPath .
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\bin"
Move-Item xnatctl.exe "$env:LOCALAPPDATA\bin\"
Note: On Windows, make sure
%LOCALAPPDATA%\binis on your PATH. You can add it via Settings > System > About > Advanced system settings > Environment Variables, or see the Installation guide for a PowerShell command.
Python Package
If you already have Python 3.11+ and want to install xnatctl as a package, use pip or uv:
# From PyPI (recommended)
pip install xnatctl
# With uv
uv pip install xnatctl
# For DICOM utilities (optional -- adds pydicom and pynetdicom)
pip install "xnatctl[dicom]"
# From source
pip install git+https://github.com/rickyltwong/xnatctl.git
Docker
For containerized environments or CI pipelines where you want to avoid local installation entirely:
docker run --rm ghcr.io/rickyltwong/xnatctl:main --help
For full installation instructions including shell completion and troubleshooting, see the Installation guide.
Quick Start
Once installed, you can be up and running in four steps.
1. Create a configuration file. This stores your XNAT server URL and default settings so you do not have to pass them on every command:
xnatctl config init --url https://xnat.example.org
2. Authenticate. Log in with your XNAT credentials. The session token is cached locally, so subsequent commands authenticate automatically:
xnatctl auth login
3. Browse your data. List the projects you have access to and inspect their contents:
xnatctl project list
4. Download a session. Pull imaging data to your local machine for analysis. Use an experiment accession number or, if you have a default project set, a session label:
xnatctl session download -E XNAT_E00001 --out ./data
For a detailed walkthrough, see the Quick Start guide.
Commands
| Command | Description |
|---|---|
xnatctl config |
Manage configuration profiles |
xnatctl auth |
Authentication (login/logout/status) |
xnatctl project |
Project operations (list/show/create) |
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 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 (requires xnatctl[dicom]) |
For complete usage and examples, see the CLI Reference.
Configuration
Config file location: ~/.config/xnatctl/config.yaml
default_profile: production
output_format: table
profiles:
production:
url: https://xnat.example.org
username: myuser # optional -- can also use env vars
password_source: keyring # password lives in the OS keychain
verify_ssl: true
timeout: 30
default_project: MYPROJECT
development:
url: https://xnat-dev.example.org
ca_bundle: /etc/ssl/dev-ca.pem # trust a private CA, rather than
# switching verification off
Store the password in your OS keychain with xnatctl config set-password production (needs the xnatctl[keyring] extra); that is what writes
password_source: keyring. An inline password: still works, but xnatctl
warns when the file holding it is readable by other users.
Working with Profiles
Profiles let you store connection details for each XNAT server you work with. You can create, add, and switch profiles from the command line:
# Create an initial config (prompts for URL and optional defaults)
xnatctl config init --url https://xnat.example.org
# Add additional profiles
xnatctl config add-profile dev --url https://xnat-dev.example.org --no-verify-ssl
# Switch the active profile
xnatctl config use-context dev
# Show the active profile and config
xnatctl config show
Authentication Flow
Log in once and your session token is cached. xnatctl reuses the cached token and refreshes it automatically when it expires:
# Login and cache a session token
xnatctl auth login
# Check current user and session context
xnatctl whoami
Credential priority (highest to lowest):
--usernameon the command line, and--password-stdinfor the password- Environment variables (
XNAT_USER,XNAT_PASS) - Profile config (
username, pluspasswordor the OS keychain) - Interactive prompt
Passwords are never accepted as a command-line value.
--password secretis a usage error, because argv is visible inps,/proc/*/cmdline, and your shell history. Use--password-stdin,XNAT_PASS, a stored profile credential, or the prompt.
Session tokens are cached at ~/.config/xnatctl/.session (mode 0600) and used
automatically until they expire.
Environment Variables
You can override any profile setting with environment variables. This is especially useful for CI pipelines and non-interactive scripts:
| Variable | Description |
|---|---|
XNAT_URL |
Server URL |
XNAT_USER |
Username |
XNAT_PASS |
Password |
XNAT_TOKEN |
Session token (highest auth priority) |
XNAT_PROFILE |
Config profile name |
XNAT_VERIFY_SSL |
Override TLS verification (true/false) |
XNAT_TIMEOUT |
HTTP timeout in seconds |
XNATCTL_DEBUG |
1 enables debug logging, an httpx wire trace, and tracebacks |
Notes:
XNAT_TOKENtakes precedence over cached sessions and username/password credentials. Use it when you already have a valid token from another tool.XNAT_URLandXNAT_PROFILEoverride values fromconfig.yamlfor the current shell session.- Use
XNAT_USERandXNAT_PASSfor non-interactive authentication in CI jobs and automated scripts.
Documentation
Complete documentation is available in the docs/ directory. Topics include installation, key concepts, configuration, CLI reference, downloading, uploading, workflows, and XNAT compatibility.
Development
# Clone and install
git clone https://github.com/rickyltwong/xnatctl.git
cd xnatctl
uv sync --dev
# Run tests
uv run pytest tests/ -v
# Lint and format
uv run ruff check xnatctl scripts
uv run ruff format xnatctl scripts
# Type check
uv run mypy xnatctl
License
MIT
-
XNAT is an open source project produced by NRG at the Washington University School of Medicine. See
https://xnat.org/. ↩
Metadata
Release files for xnatctl 0.3.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.3.0.tar.gz | 590.6 kB | With provenance | Details for xnatctl-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xnatctl-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for xnatctl-0.3.0-py3-none-any.whl |
Total release size: 822.8 kB
Release files / xnatctl-0.3.0.tar.gz
| Download URL | xnatctl-0.3.0.tar.gz |
|---|---|
| Size | 590.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6fbac61c73c3dab40561dfd8702ce2fd50683bc45156eb86fc3d3c634c54a630
|
|
BLAKE2b-256 checksum How to use checksums |
7f158a9b0aa6b1b438c8552e0d8b770b1d5b4069816b0dbbeba80766dd185454
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
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 Aug 7, 2026.
Transparency logRelease files / xnatctl-0.3.0-py3-none-any.whl
| Download URL | xnatctl-0.3.0-py3-none-any.whl |
|---|---|
| Size | 232.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1680b3fbb45e5d2d667c543087eb565ead3332f1adf7531e0be1edfeaeee83ad
|
|
BLAKE2b-256 checksum How to use checksums |
f17ea348405b52caab66b09413a6b01ac869e4a6db86809f0bcd8b08e12afdb2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
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 Aug 7, 2026.
Transparency logSecurity for xnatctl 0.3.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.3.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 Aug 7, 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.