guidesCLI Reference

BrainMaps CLI Reference

The BrainMaps CLI provides a comprehensive set of commands for interacting with the BrainMaps platform directly from your terminal. This reference documents all available commands and their parameters.

Global Options

brainmaps --help  # Show global help with all command groups

Authentication

# Login interactively
brainmaps login
# With parameters
brainmaps login --email your@email.com --password yourpassword
 
# Logout and remove stored tokens
brainmaps logout

Token Management

# List all personal access tokens
brainmaps token list
 
# Create a new personal access token
brainmaps token create "My Script Token"
 
# Revoke a token
brainmaps token revoke <token-id>
 
# Register an existing token
brainmaps token register <platform-token>

Brain Management

# List all brains
brainmaps brain list
 
# List with filtering
brainmaps brain list --category "cephalopods" --species "octopus vulgaris"
 
# Get details of a specific brain
brainmaps brain get <brain-id>
 
# Create a new brain
brainmaps brain create \
  --name "My Brain Dataset" \
  --category "cephalopods" \
  --species "octopus vulgaris" \
  --file /path/to/brain.tiff \
  --color "#FF5733" \
  --verbose
 
# Update a brain
brainmaps brain update <brain-id> \
  --name "New Name" \
  --category "new-category" \
  --species "new-species"
 
# Delete a brain
brainmaps brain delete <brain-id>

S3 Configuration

# Configure S3 storage settings
brainmaps s3 configure \
  --bucket your-bucket-name \
  --region your-aws-region \
  --access-key-id your-access-key \
  --secret-access-key your-secret-key \
  --endpoint-url your-custom-endpoint  # Optional for non-AWS S3
 
# View current S3 configuration
brainmaps s3 show

Configuration Management

# Set the API URL
brainmaps config set-api-url https://api.brainmaps.science
 
# Get the current API URL
brainmaps config get-api-url
 
# Set an API token directly
brainmaps config set-token your-token-value

File Upload Operations

# Upload a single file
brainmaps upload file /path/to/file.tiff \
  --species 1 \
  --color "#FF5733" \
  --verbose
 
# Upload a folder (useful for ZARR folders)
brainmaps upload folder /path/to/zarr/folder \
  --species 1 \
  --color "#FF5733" \
  --verbose
 
# List recent uploads
brainmaps upload list --limit 20

File Management

# List all uploaded files
brainmaps file list
 
# Get file details
brainmaps file get <file-id>
 
# Download a file
brainmaps file download <file-id> --output /path/to/save/file

Species Management

# List all species
brainmaps species list
 
# Search for species
brainmaps species search "octopus"
 
# Get species details
brainmaps species get <species-id>

Supported File Types

The BrainMaps CLI supports the following file formats:

  • .nii - NIfTI format
  • .nii.gz - Compressed NIfTI
  • .zarr - Zarr format directories
  • .tif/.tiff - TIFF format

Environment Variables

The CLI supports the following environment variables for configuration:

Environment VariableDescription
BRAINMAPS_API_URLURL of the BrainMaps API
BRAINMAPS_TOKENAuthentication token
AWS_REGIONAWS region for S3 storage
AWS_ACCESS_KEY_IDAWS access key for S3 uploads
AWS_SECRET_ACCESS_KEYAWS secret key for S3 uploads
AWS_BUCKET_NAMES3 bucket name for file storage
BRAINMAPS_LOG_LEVELLog level (DEBUG, INFO, WARNING, ERROR)

Command Aliases

The CLI supports several command aliases for convenience:

AliasFull Command
lslist
upupload
specspecies
dldownload

Error Handling

Most commands will return clear error messages with HTTP status codes when applicable. Examples:

Error: Authentication required (Status: 401)
Error: Brain not found (Status: 404)
Error: Invalid file type. Supported types: .nii, .nii.gz, .zarr, .tif, .tiff

Example Workflows

Complete Brain Upload Workflow

# 1. Login
brainmaps login
 
# 2. Configure S3 credentials (if not already done)
brainmaps s3 configure --bucket my-bucket --region us-east-1 \
  --access-key-id my-key --secret-access-key my-secret
 
# 3. Find the appropriate species
brainmaps species search "octopus"
 
# 4. Upload the brain file
brainmaps upload file octopus_brain.tiff --species 5 --color "#3366FF"
 
# 5. View your uploaded files
brainmaps upload list
 
# 6. Create a brain entry with the uploaded file
brainmaps brain create --name "Octopus Brain 123" \
  --category "cephalopods" --species "octopus vulgaris" \
  --file octopus_brain.tiff
 
# 7. View your brains
brainmaps brain list
CLI InstallationCLI Uploading Data
BrainMaps Documentation