Installing and Setting Up the BrainMaps CLI

The BrainMaps CLI (Command Line Interface) allows you to interact with the BrainMaps platform directly from your terminal, enabling automation of common tasks like uploading brain scans, managing files, and interacting with the API.

Installation Options

Installing with pip

The simplest way to install the BrainMaps CLI is using pip:

pip install brainmaps-cli

Installing from Source

For the latest development version or to contribute:

# Clone the repository
git clone https://github.com/brainmaps/brainmaps-cli.git
cd brainmaps-cli
 
# Install in development mode
pip install -e .

Python Requirements

Python 3.8 or higher
Required packages are automatically installed by pip

First-time Setup

After installation, you’ll need to configure the CLI before first use:

1. Configure the API URL

First, tell the CLI where to find the BrainMaps API:

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

2. Authentication

You need to authenticate to access most features:

brainmaps login
# You'll be prompted for your email and password

3. Configure S3 Storage

To upload files, you’ll need to configure S3 credentials:

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

If you’re using a non-AWS S3-compatible service, you can also specify an endpoint URL:

brainmaps s3 configure \
  --endpoint-url https://your-s3-compatible-endpoint \
  --bucket your-bucket-name \
  --region your-region \
  --access-key-id your-access-key-id \
  --secret-access-key your-secret-access-key

Environment Variables

Instead of using the configuration commands, you can set environment variables:

# API Configuration
export BRAINMAPS_API_URL="https://api.brainmaps.science"
export BRAINMAPS_TOKEN="your_api_token"
 
# S3 Configuration
export AWS_REGION="us-east-1"
export AWS_ACCESS_KEY_ID="your_access_key"
export AWS_SECRET_ACCESS_KEY="your_secret_key" 
export AWS_BUCKET_NAME="your_bucket_name"
 
# Optional - Logging Level
export BRAINMAPS_LOG_LEVEL="INFO"  # DEBUG, INFO, WARNING, or ERROR

You can add these to your shell profile (.bashrc, .zshrc, etc.) for persistent configuration.

Verifying Installation

To verify your installation and configuration:

# Check the CLI version
brainmaps --help
 
# Test your authentication
brainmaps species list
 
# Verify S3 configuration
brainmaps s3 show

Troubleshooting

Authentication Issues

If you encounter authentication problems:

# Check if you're logged in
brainmaps token list
 
# If not, log in again
brainmaps login
 
# Or set a token directly
brainmaps config set-token your-token-value

S3 Configuration Issues

For S3 problems:

# Verify your current S3 configuration
brainmaps s3 show
 
# Reconfigure if needed
brainmaps s3 configure --bucket new-bucket --region new-region

Common Errors

“Invalid API URL”: Make sure your API URL is correct and includes the protocol (https://)
“Authentication required”: You need to log in before using most commands
“S3 configuration missing”: Configure S3 before attempting file uploads
“Invalid file type”: Make sure you’re using a supported file format

Next Steps

After setting up the CLI, you can:

Upload brain files with brainmaps upload file
List available species with brainmaps species list
Create brain entries with brainmaps brain create
Explore all commands with brainmaps --help

For detailed command usage, see the CLI Reference guide.

CLI Authentication CLI Reference