CBRAIN CLI

A command-line interface to a CBRAIN service

This repository contains a UNIX command-line interface (CLI) for CBRAIN, a web-based neuroinformatics platform designed for collaborative brain imaging research. CBRAIN provides researchers with distributed computational resources, data management capabilities, and a framework for running neuroscience analysis pipelines across multiple high-performance computing environments.

The interface is implemented in Python using only standard libraries - no external dependencies required.

CBRAIN Access Options

There are two main ways to access CBRAIN:

1. McGill Production Portal (Recommended for Regular Users)

   • Access the McGill-supported CBRAIN production portal at: https://portal.cbrain.mcgill.ca/
   • No local installation required
   • Web-based interface for most common operations

2. Custom/Development Setup

   • Deploy CBRAIN on your lab cluster, cloud, or virtual machine
   • Suitable for organizations that require their own CBRAIN instance or which prefer to host CBRAIN themselves due to legal or corporate requirements
   • Local installation only needed for:
     • CLI software developers
     • Power users developing/debugging custom CLI scripts
   • Follow setup instructions at CBRAIN GitHub Repository if you need a local instance

Installation

This CLI tool uses pure Python with no external library dependencies, making installation straightforward.

Option 1: Direct Usage

1. Clone this repository:

   git clone https://github.com/aces/cbrain-cli.git
   cd cbrain-cli

2. Run directly:

   ./cbrain --help # Make the cbrain script executable by `chmod +x cbrain`

Option 2: Virtual Environment

For isolated usage:

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Initial Setup

After installation, you need to login to your CBRAIN instance:

cbrain login

When prompted for "Enter CBRAIN server URL prefix", enter:

• For McGill Production Portal: https://portal.cbrain.mcgill.ca
• For custom setup: Your CBRAIN instance URL

API Reference

This CLI interfaces with the CBRAIN REST API. For complete API documentation and specifications, refer to:

• CBRAIN API Documentation (Swagger)

CLI Usage

The main command is called "cbrain" and as is typical for such clients, works with a set of subcommand and options.

Basic Usage

To utilize the Cbrain cli, you can execute variations of the following command in your terminal:

cbrain -h     # view the cli options
cbrain [options] <MODEL> <ACTION> [id_or_args]

Output Formats:

• --json or -j: JSON format output
• --jsonl or -jl: JSON Lines format (one JSON object per line)

Available Commands

• version - Show CLI version
• login - Login to CBRAIN
• logout - Logout from CBRAIN
• whoami - Show current session
• file - File operations
• dataprovider - Data provider operations
• project - Project operations
• tool - Tool operations
• tool-config - Tool configuration operations
• tag - Tag operations
• background - Background activity operations
• task - Task operations
• remote-resource - Remote resource operations

Command Examples

Used cmds in the above GIF

• ./cbrain project switch 2
• ./cbrain project show
• ./cbrain tool show 2
• ./cbrain dataprovider show 4
• ./cbrain file show 4
• ./cbrain background show 15
• ./cbrain remote-resource show 2
• ./cbrain tag show 17
• ./cbrain task show 1

Used cmds in the above GIF

• ./cbrain file list
• ./cbrain project list
• ./cbrain background list
• ./cbrain dataprovider list
• ./cbrain remote-resource list
• ./cbrain tag list
• ./cbrain task list
• ./cbrain task list bourreau-id 3

Development

This is part of a GSoC (Google Summer of Code) 2025 project sponsored by INCF.

The lead developer is axif0, mentored by the developers of the CBRAIN project.

Continuous Integration

Continuous Integration (CI) tests and framework were initially configured by P. Rioux, providing automated validation of the codebase. This infrastructure follows best open source practices and ensures code quality through automated testing.

License

See LICENSE file for details.