BrainMaps CLI Tool

The BrainMaps CLI tool provides both a command-line interface and a terminal user interface (TUI) for interacting with the BrainMaps API. It supports all major operations including file uploads, brain management, token management, and authentication.

Installation

Install the CLI tool using pip:

pip install brainmaps-cli

Or install from source:

git clone https://github.com/brainmaps/brainmaps-cli
cd brainmaps-cli
pip install -e .

First-Time Setup

Configure your API URL (if not using the default):

brainmaps config set-api-url https://api.brainmaps.science

brainmaps login
# You'll be prompted for:
# Email: your@email.com
# Password: ********

Configure S3 settings for file uploads:

brainmaps s3 configure \
  --bucket your-bucket-name \
  --region your-aws-region \
  --access-key-id your-aws-access-key \
  --secret-access-key your-aws-secret-key

Alternatively, you can use environment variables:

export BRAINMAPS_API_URL="https://api.brainmaps.science"
export AWS_REGION="your-aws-region"
export AWS_ACCESS_KEY_ID="your-aws-access-key"
export AWS_SECRET_ACCESS_KEY="your-aws-secret-key"
export AWS_BUCKET_NAME="your-bucket-name"

File Upload Guide

Quick Start

Upload a single file:

brainmaps upload file path/to/your/file.nii.gz

Supported File Types

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

Upload Process

The file is validated for supported formats
File is uploaded to S3 with progress bar
A FileUpload record is created in the database
You receive a JSON response with upload details

Example output:

{
  "id": "123",
  "name": "my_brain.nii.gz",
  "status": "uploaded",
  "file_size_mb": 256.5,
  "date_uploaded": "2023-12-23T12:34:56Z",
  "file": "https://bucket.s3.region.amazonaws.com/uploads/my_brain.nii.gz"
}

Common Operations

Authentication

# Login (interactive)
brainmaps login
 
# Logout
brainmaps logout
 
# Create a personal access token (for automation)
brainmaps token create "My Script Token"
 
# List your tokens
brainmaps token list
 
# Revoke a token
brainmaps token revoke <token-id>

Brain Management

# List all brains
brainmaps brain list
 
# Filter brains
brainmaps brain list --category "Human" --species "Homo sapiens"
 
# Get brain details
brainmaps brain get <brain-id>
 
# Create a new brain
brainmaps brain create \
  --name "My Brain" \
  --category "Human" \
  --species "Homo sapiens" \
  --file brain.tiff
 
# Update a brain
brainmaps brain update <brain-id> --name "New Name"
 
# Delete a brain
brainmaps brain delete <brain-id>

Configuration Management

# View S3 settings (sensitive info hidden)
brainmaps s3 show
 
# Update S3 settings
brainmaps s3 configure --bucket new-bucket --region new-region
 
# View current API URL
brainmaps config get-api-url
 
# Set new API URL
brainmaps config set-api-url https://new-api.brainmaps.science
 
# Set API token directly
brainmaps config set-token your-token

Error Handling

The CLI provides clear error messages:

# File type error
$ brainmaps upload file image.jpg
Error: Invalid file type. Supported formats: .nii, .nii.gz, .zarr, .tif, .tiff
 
# Authentication error
$ brainmaps brain list
Error: Authentication required (Status: 401)
 
# Not found error
$ brainmaps brain get nonexistent
Error: Brain not found (Status: 404)

Using in Scripts

Example script for automated uploads:

#!/bin/bash
 
# Configure CLI
brainmaps config set-api-url https://api.brainmaps.science
brainmaps config set-token your-token
brainmaps s3 configure \
  --bucket your-bucket \
  --region your-region \
  --access-key-id your-key \
  --secret-access-key your-secret
 
# Upload multiple files
for file in *.nii.gz; do
  echo "Uploading $file..."
  brainmaps upload file "$file"
done

Security Best Practices

Token Management:
- Use personal access tokens for scripts
- Regularly rotate tokens
- Never share or commit tokens
- Revoke unused tokens
File Upload Security:
- Verify file types before upload
- Files are scanned for viruses
- Access controlled by user permissions
- S3 URLs are signed and temporary
Configuration Security:
- Use environment variables in CI/CD
- Store config in user-only readable files
- Never log sensitive information
- Use separate tokens for different purposes

Troubleshooting

Upload Issues:

# Check S3 configuration
brainmaps s3 show
 
# Verify file type
file your_file.nii.gz
 
# Test API connection
brainmaps config get-api-url

Authentication Issues:

# Verify token
brainmaps token list
 
# Re-login if needed
brainmaps logout
brainmaps login

Common Errors:
- “Invalid file type”: Check file extension and format
- “AWS credentials not found”: Check S3 configuration
- “Token expired”: Re-login or use a new token
- “Network error”: Check API URL and connectivity

Getting Help

# Show general help
brainmaps --help
 
# Show help for specific command
brainmaps upload --help
brainmaps brain create --help
 
# Show version
brainmaps --version

For more help, visit the BrainMaps Documentation or join our Discord community.

Authentication Installation