Skip to main content

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 pattern xnatctl <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|table and --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 login and 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 kubectl and airflowctl: 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%\bin is 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):

  1. --username on the command line, and --password-stdin for the password
  2. Environment variables (XNAT_USER, XNAT_PASS)
  3. Profile config (username, plus password or the OS keychain)
  4. Interactive prompt

Passwords are never accepted as a command-line value. --password secret is a usage error, because argv is visible in ps, /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_TOKEN takes precedence over cached sessions and username/password credentials. Use it when you already have a valid token from another tool.
  • XNAT_URL and XNAT_PROFILE override values from config.yaml for the current shell session.
  • Use XNAT_USER and XNAT_PASS for 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

  1. 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)

Source distribution for xnatctl 0.3.0
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)

Table of built distributions (wheels) for xnatctl 0.3.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page