Install the CLI

The current source version is 0.3.0 and requires Python 3.10 or later. Use Python 3.11 if you need BrainGlobe exports.

As of 17 September 2026, brainmaps-cli is not available on public PyPI. Install from a source checkout supplied by the project; repository access may be required. Do not rely on pip install brainmaps-cli until a release has been published.

Run from the workspace

Install uv, then:

cd /path/to/brainmaps/brainmaps-cli
uv sync
uv run brainmaps --help
uv run brainmaps config set-api-url https://api.brainmaps.xyz
uv run brainmaps login

Login prompts for your email and password. The examples elsewhere in these docs use brainmaps; when working from this checkout, prefix those commands with uv run.

Install the command on your PATH

Alternatively, install the checkout as a uv tool:

uv tool install --python 3.11 /path/to/brainmaps/brainmaps-cli
brainmaps --version
brainmaps config set-api-url https://api.brainmaps.xyz
brainmaps login

If your shell cannot find brainmaps, run uv tool update-shell and open a new terminal. To update a tool installation after updating the checkout, repeat the install command with --reinstall.

Optional capabilities

From the source checkout:

# Local ANTs registration and its interactive wizard
uv sync --extra registration --extra interactive
 
# BrainGlobe import/export tools, on Python 3.11+
uv sync --python 3.11 --extra brainglobe

Include all the extras you need in the same uv sync invocation. The bioformats extra supports workflows that need Bio-Formats; these also need the appropriate Java runtime.

There is no global --visual mode. Selected registration commands provide --interactive when the interactive extra is installed.

Configure the platform

New CLI configuration defaults to http://localhost:8000. Set the hosted API explicitly:

brainmaps config set-api-url https://api.brainmaps.xyz
brainmaps config get-api-url

Configuration is stored in ~/.brainmaps/config.json. For a single invocation use brainmaps --api-url URL …; BRAINMAPS_API_URL is also supported. Treat the configuration file as sensitive because it may contain authentication and storage credentials.

Continue with authentication, then uploading data.