Skip to main content

xnatctl

PyPI CI Python License: MIT

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 secret is a usage error, because argv is visible in ps and 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 --profile or config use-context.
  • Consistent output -- --output json|table and --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.5.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.5.0
File Size Uploaded Provenance Actions
xnatctl-0.5.0.tar.gz 1.1 MB With provenance Details for xnatctl-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xnatctl 0.5.0
File Interpreter ABI Platform Actions
xnatctl-0.5.0-py3-none-any.whl Python 3 none any Details for xnatctl-0.5.0-py3-none-any.whl

Total release size: 1.6 MB

Release files / xnatctl-0.5.0.tar.gz

Download URL xnatctl-0.5.0.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
8d38f38c56bc8a9f9866d07b429ef4efb55fb6289c743e59a61ac138e6a8b598
BLAKE2b-256 checksum
How to use checksums
3194d3c1f6d85b81b359b087a7a86c6c05ceeae389104c19b88613e3cb098373
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 Aug 27, 2026.

Transparency log

Release files / xnatctl-0.5.0-py3-none-any.whl

Download URL xnatctl-0.5.0-py3-none-any.whl
Size 518.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ea442a79be346a95b48e7a61c986de85ad2ab3f671e3b89a50d3f7a1826401de
BLAKE2b-256 checksum
How to use checksums
731a09e0d60bc278b0c7e7e25d2560f99c53bfc731319f9dcb970559cedb0ce6
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 Aug 27, 2026.

Transparency log

Security for xnatctl 0.5.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.5.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 27, 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