Installation

You can install xnatctl in three ways: as a standalone binary (no Python required), as a Python package from PyPI, or via Docker. If you just want to use the CLI and do not need Python library access, the standalone binary is the fastest path.

Prerequisites

All you need is a terminal application (Terminal on macOS, PowerShell or Windows Terminal on Windows, any shell on Linux). If you choose the Python package method, you also need Python 3.11 or later installed on your system.

Python Package

Choose the Python package if you already have a Python 3.11+ environment, want to import xnatctl as a library in your own scripts, or need the optional DICOM utilities.

Install from PyPI (recommended):

$ pip install xnatctl

Install with uv (faster alternative to pip):

$ uv pip install xnatctl

With DICOM extras:

The dicom extra installs pydicom and pynetdicom, which enable the xnatctl dicom commands (validate, inspect, list-tags, anonymize) for local DICOM file operations and the xnatctl session upload-dicom C-STORE pathway. See DICOM Utilities for full command documentation:

$ pip install "xnatctl[dicom]"

Install from source:

If you want to track the development branch or contribute to xnatctl, you can install directly from the Git repository:

$ git clone https://github.com/rickyltwong/xnatctl.git
$ cd xnatctl
$ uv sync

Tip

It is good practice to install Python CLI tools inside a virtual environment to avoid conflicts with system packages. You can create one with python -m venv .venv and activate it before running pip install, or use uv which manages environments automatically.

Docker

If you are running xnatctl in a CI pipeline or prefer a fully isolated environment, you can use the Docker image. No local installation is required beyond Docker itself:

$ docker run --rm ghcr.io/rickyltwong/xnatctl:main --help

Verifying Your Installation

After installing xnatctl by any method, confirm that the binary is available and prints its version:

$ xnatctl --version

You should see output similar to xnatctl, version 0.1.1.

You can also run the built-in help to see the full list of available commands:

$ xnatctl --help

This prints the top-level command groups (project, session, auth, etc.). Many resource-oriented commands support common options like --output, --profile, and --quiet.

Shell Completion

xnatctl can generate tab-completion scripts for bash, zsh, and fish. Install the script for your shell to get auto-completion of commands, sub-commands, and options:

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

# Zsh (ensure ~/.zfunc is in your fpath)
$ mkdir -p ~/.zfunc
$ xnatctl completion zsh > ~/.zfunc/_xnatctl

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

Restart your shell after installing the completion script.

Troubleshooting

Below are solutions to common installation issues.

“command not found” after installing

Your shell cannot find the xnatctl binary because its install directory is not on your PATH.

Linux (bash):

$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
$ source ~/.bashrc

macOS (zsh):

$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc

Windows (PowerShell):

Add %LOCALAPPDATA%\bin to your user PATH permanently. Run this in an elevated (Administrator) PowerShell, or use Settings > System > About > Advanced system settings > Environment Variables:

$binDir = "$env:LOCALAPPDATA\bin"
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($currentPath -notlike "*$binDir*") {
    [Environment]::SetEnvironmentVariable("Path", "$currentPath;$binDir", "User")
}

After updating the PATH, close and reopen your terminal for the change to take effect.

“permission denied” when running the binary

The binary needs the executable permission bit set. This is handled automatically by the install script, but if you downloaded manually you may need to set it yourself:

$ chmod +x ~/.local/bin/xnatctl

SSL certificate errors

On some older systems the default CA certificate bundle may be outdated, causing SSL verification failures when connecting to your XNAT server. You can work around this by updating your system certificates or, as a temporary measure, disabling SSL verification in your xnatctl profile:

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

Warning

Disabling SSL verification removes protection against man-in-the-middle attacks. Only use --no-verify-ssl on trusted networks and update your system certificates as soon as possible.

Python version too old

xnatctl requires Python 3.11 or later. If pip install xnatctl fails with a resolver or syntax error, check your Python version:

$ python3 --version

If the version shown is older than 3.11, upgrade Python through your system package manager or download it from python.org.