Basilica CLI Helper

Basilica CLI Helper

Rent GPUs and run ML training jobs on Basilica's decentralized compute platform.

This skill helps access high-performance GPUs through Basilica's CLI. Use this when needing to:

• Rent GPUs for machine learning training
• Run distributed training jobs
• Manage compute resources and costs
• Execute code on remote GPU instances

Claude Code TTY Limitation

IMPORTANT: The basilica up command requires interactive TTY selection, which fails in Claude Code's non-terminal environment.

Workaround: Use the bundled script

# List available GPUs (non-interactive)
python ~/​.claude/​skills/​basilica-cli-helper/​scripts/​basilica_up.py list

# Filter by GPU type and cloud
python ~/​.claude/​skills/​basilica-cli-helper/​scripts/​basilica_up.py list --gpu-type h100 --compute secure-cloud

# Rent by selection number (from list output)
python ~/​.claude/​skills/​basilica-cli-helper/​scripts/​basilica_up.py rent --select 1

# Rent by offering ID directly
python ~/​.claude/​skills/​basilica-cli-helper/​scripts/​basilica_up.py rent hyperstack-165

This script uses the Basilica REST API directly, bypassing the interactive selection.

Quick Reference

Essential Commands

Cloud Types

Basilica offers two compute sources:

Command Reference

Authentication

# Standard login (opens browser)
basilica login

# Device code flow (for WSL, SSH, containers)
basilica login --device-code

# Logout
basilica logout

# Check balance
basilica balance

Listing GPUs

# List all available GPUs
basilica ls

# Filter by GPU type
basilica ls h100
basilica ls a100

# Filter by cloud type
basilica ls --compute secure-cloud
basilica ls --compute community-cloud

# Additional filters
basilica ls --gpu-min 2 --gpu-max 8
basilica ls --price-max 5.00
basilica ls --memory-min 80
basilica ls --country US

# JSON output
basilica ls --json

Starting Rentals

Note: basilica up requires interactive TTY. In Claude Code, use the workaround script above.

In a terminal:

# Interactive GPU selection
basilica up

# Filter to GPU type (still requires selection)
basilica up h100
basilica up a100

# Specify cloud type
basilica up --compute secure-cloud
basilica up --compute community-cloud

# Detached mode (don't auto-connect)
basilica up -d

# Additional options
basilica up --gpu-count 4
basilica up --country US
basilica up --no-ssh  # Faster startup without SSH

Managing Rentals

# List active rentals
basilica ps

# Show rental history
basilica ps --history

# Filter by cloud type
basilica ps --compute secure-cloud

# Check specific rental
basilica status <rental-id>

# Terminate rental
basilica down <rental-id>

# Terminate all rentals
basilica down --all

# Restart container
basilica restart <rental-id>

Executing Code

# Execute command on rental
basilica exec "python train.py" --target <rental-id>

# If only one active rental, --target is optional
basilica exec "nvidia-smi"
basilica exec "pip install -r requirements.txt"

File Transfer

# Copy file to rental
basilica cp train.py <rental-id>:/​workspace/

# Copy directory to rental
basilica cp ./​project/ <rental-id>:/​workspace/​project/

# Download file from rental
basilica cp <rental-id>:/​workspace/​model.pth ./

# Download directory
basilica cp <rental-id>:/​workspace/​checkpoints/ ./​checkpoints/

SSH Access

# SSH into instance
basilica ssh <rental-id>

# Port forwarding (e.g., Jupyter)
basilica ssh <rental-id> -L 8888:localhost:8888

# Remote port forwarding
basilica ssh <rental-id> -R 9999:localhost:9999

Logs

# View logs
basilica logs <rental-id>

# Follow logs in real-time
basilica logs <rental-id> --follow

# Tail last N lines
basilica logs <rental-id> --tail 100

SSH Key Management

# Add SSH key
basilica ssh-keys add

# Add with specific file
basilica ssh-keys add --file ~/​.ssh/​id_rsa.pub

# List registered keys
basilica ssh-keys list

# Delete key
basilica ssh-keys delete

API Token Management

# Create API token
basilica tokens create <name>

# List tokens
basilica tokens list

# Revoke token
basilica tokens revoke <name>

Funding

# Show deposit address
basilica fund

# List deposit history
basilica fund list --limit 100

Common Workflows

PyTorch Training (Claude Code)

# 1. List available GPUs using workaround script
python ~/​.claude/​skills/​basilica-cli-helper/​scripts/​basilica_up.py list --compute secure-cloud

# 2. Rent GPU by selection number
python ~/​.claude/​skills/​basilica-cli-helper/​scripts/​basilica_up.py rent --select 1
# Note the rental ID from output

# 3. Copy training files
basilica cp train.py <rental-id>:/​workspace/
basilica cp requirements.txt <rental-id>:/​workspace/

# 4. Install dependencies and run training
basilica exec "pip install -r /​workspace/​requirements.txt" --target <rental-id>
basilica exec "python /​workspace/​train.py --epochs 10" --target <rental-id>

# 5. Download results
basilica cp <rental-id>:/​workspace/​model.pth ./

# 6. Terminate when done
basilica down <rental-id>

PyTorch Training (Terminal with TTY)

# 1. Start GPU rental (interactive selection)
basilica up h100 --compute secure-cloud -d
# Note the rental ID

# 2. Copy training files
basilica cp train.py <rental-id>:/​workspace/

# 3. Run training
basilica exec "python /​workspace/​train.py" --target <rental-id>

# 4. Download results and cleanup
basilica cp <rental-id>:/​workspace/​model.pth ./
basilica down <rental-id>

Jupyter Notebook

# 1. Start rental and SSH with port forward
basilica up h100 -d
basilica ssh <rental-id> -L 8888:localhost:8888

# 2. In SSH session, start Jupyter
jupyter lab --ip=0.0.0.0 --port=8888 --no-browser

# 3. Open http://localhost:8888 in browser

Check Costs

# Check current balance
basilica balance

# View rental history with costs
basilica ps --history

# Get deposit address if needed
basilica fund

Troubleshooting

"Selection failed: not a terminal"

This occurs when running basilica up in Claude Code. Use the workaround script:

python ~/​.claude/​skills/​basilica-cli-helper/​scripts/​basilica_up.py list
python ~/​.claude/​skills/​basilica-cli-helper/​scripts/​basilica_up.py rent --select <number>

"Not logged in"

basilica login
# Or for non-browser environments:
basilica login --device-code

"Insufficient balance"

basilica balance  # Check current balance
basilica fund     # Get deposit address

"No GPUs available"

basilica ls  # Check different GPU types
basilica ls --compute community-cloud  # Try community cloud

"SSH key not registered"

basilica ssh-keys add

"Connection timeout"

basilica status <rental-id>  # Check if still running
basilica logs <rental-id>    # Check for errors

GPU Selection Guide

Resources

• Basilica Homepage: https://basilica.ai
• CLI Help: basilica help <command>
• Version: Check with basilica --version

Scripts Reference

basilica_up.py

Non-interactive GPU rental script for Claude Code and other non-TTY environments.

# Show help
python ~/​.claude/​skills/​basilica-cli-helper/​scripts/​basilica_up.py --help

# List offerings
python ~/​.claude/​skills/​basilica-cli-helper/​scripts/​basilica_up.py list [--gpu-type TYPE] [--compute CLOUD]

# Rent by selection
python ~/​.claude/​skills/​basilica-cli-helper/​scripts/​basilica_up.py rent --select NUMBER

# Rent by offering ID
python ~/​.claude/​skills/​basilica-cli-helper/​scripts/​basilica_up.py rent OFFERING_ID

The script caches offering data to /​tmp/​basilica_offerings.json for the --select option.