CLI command reference

Checked against the current source command registry (version 0.3.0, 17 September 2026). Install from the source checkout; the package is not currently published on public PyPI.

brainmaps --help
brainmaps upload image --help
brainmaps register run --help

Global options are --api-url, --version and --help. Use uv run brainmaps when running from the source checkout. There is no global --visual option and no ls, up, spec or dl shorthand.

Commands

The following command names come from the current Typer registry. Arguments and options belong to the individual command; its --help is the definitive syntax.

Authentication

Command	Purpose
`brainmaps signup`	Create a BrainMaps account and log in.
`brainmaps login`	Authenticate with BrainMaps API.
`brainmaps logout`	Revoke current session token and clear local auth.

Token

Command	Purpose
`brainmaps token list`	List personal access tokens for the current user.
`brainmaps token create`	Create a personal access token.
`brainmaps token revoke`	Revoke an existing token.
`brainmaps token register`	Register an existing token into local CLI config.

Admin

Command	Purpose
`brainmaps admin pending`	Show what awaits staff action: unapproved accounts and built releases.
`brainmaps admin approve`	Approve an account so uploads and other writes unlock.

Config

Command	Purpose
`brainmaps config set-api-url`	Set the default API URL.
`brainmaps config get-api-url`	Print configured API URL.
`brainmaps config set-token`	Store API token locally.
`brainmaps config show`	Show effective config values.

Species

Command	Purpose
`brainmaps species list`	List all species.
`brainmaps species search`	Request species search; the current API ignores the search filter.
`brainmaps species get`	Get details for one species.

Brain

Command	Purpose
`brainmaps brain list`	List brains.
`brainmaps brain get`	Show details for one brain.
`brainmaps brain create`	Create a brain from a new file upload or an existing upload.

File

Command	Purpose
`brainmaps file list`	List file uploads visible to the current user.
`brainmaps file get`	Get details for one file upload.

Upload

Command	Purpose
`brainmaps upload file`	Upload one imaging file, confirm its metadata, and queue conversion.
`brainmaps upload folder`	Upload a folder (including zarr datasets).
`brainmaps upload image`	Convert an imaging file to precomputed and upload it to S3 in one step.
`brainmaps upload list`	List recent uploads.

Convert

Command	Purpose
`brainmaps convert nifti`	Convert NIfTI to Neuroglancer precomputed format.
`brainmaps convert tiff-precomputed`	Convert TIFF or OME-TIFF to Neuroglancer precomputed format.
`brainmaps convert zarr-precomputed`	Convert Zarr or OME-Zarr to Neuroglancer precomputed format.
`brainmaps convert tiff-to-zarr`	Convert a TIFF stack to pyramidal Zarr.
`brainmaps convert tiff-to-omezarr`	Convert TIFF inputs to OME-Zarr.
`brainmaps convert validate-omezarr`	Validate an OME-Zarr folder layout and metadata.

S3

Command	Purpose
`brainmaps s3 configure`	Set or update S3 settings.
`brainmaps s3 show`	Print S3 configuration.
`brainmaps s3 preflight`	Write, verify, and optionally public-probe a tiny precomputed dataset.

Serve

Command	Purpose
`brainmaps serve precomputed`	Serve Neuroglancer precomputed datasets with browser-safe headers.

Atlas

Command	Purpose
`brainmaps atlas export-brainglobe`	Queue a BrainGlobe export as the atlas creator or a delegated administrator.
`brainmaps atlas publish-release`	Publish a built release as the atlas creator or a delegated administrator.
`brainmaps atlas import-brainglobe`	Import a BrainGlobe reference atlas, metadata first.

Ingest

Command	Purpose
`brainmaps ingest create`	Create ingest job metadata before/while local processing runs.
`brainmaps ingest list`	List ingest jobs.
`brainmaps ingest get`	Get one ingest job.
`brainmaps ingest artifact`	Attach artifact metadata to an ingest job.
`brainmaps ingest progress`	Update ingest status and/or progress.
`brainmaps ingest finalize`	Finalize an ingest job into FileUpload + Brain records.

Jobs

Command	Purpose
`brainmaps jobs list`	List your jobs (staff see everyone’s).
`brainmaps jobs get`	Show one job in full.
`brainmaps jobs retry`	Reset a failed or cancelled job to queued.
`brainmaps jobs cancel`	Cancel a queued or in-flight job.

Worker

Command	Purpose
`brainmaps worker run`	Claim and execute queued jobs (generic queue + atlas builds).

Register

Command	Purpose
`brainmaps register create`	Create a registration run record in the BrainMaps API.
`brainmaps register list`	List registration runs.
`brainmaps register get`	Show one registration run.
`brainmaps register progress`	Update registration run progress and/or metrics.
`brainmaps register artifact`	Attach a registration artifact URL to a run.
`brainmaps register batch`	Plan a platform-backed consensus-template registration batch.
`brainmaps register batch-run`	Execute stage 1 of a consensus-template batch plan.
`brainmaps register batch-publish`	Publish subject-level registration outputs from a completed stage-1 batch.
`brainmaps register group-publish`	Publish a completed local group registration workflow into the BrainMaps API.
`brainmaps register run`	Run a local registration workflow with standardized ANTSpyX conventions.
`brainmaps register group`	Build a consensus template and register each subject into template space.

Verify

Command	Purpose
`brainmaps verify matrix`	Generate a multi-format sample matrix and optionally publish it.

Current limitations

species get looks up an exact common name despite its current argument help saying ID. Species search is not implemented by the API filter.
brain list --category is currently ignored by the API. Use numeric --species instead.
There are no CLI brain update/delete, species-create or file-download commands. Add species through the website or API.
upload file --json skips metadata confirmation; it does not queue conversion by itself.
TIFF/Zarr-to-precomputed conversion selects the first channel/time/sample and can rescale values. Preserve existing multichannel Zarr with upload folder.
--transcriptomic marks a segmentation layer; it does not import a gene-expression matrix.
Local registration exists; generic queued registration is not a supported worker job kind.

See uploads, registration and workers for complete workflows.

Compute Jobs Brains