Skip to main content

​
Overview

The SuperBox CLI is a Python (Click) tool for managing MCP servers from initialization to deployment. Commands map directly to the backend implementation in superbox.ai/src/superbox/cli.
All CLI documentation matches the actual backend implementation. For detailed setup and usage, visit https://superbox.1mindlabs.org/docs

​
Installation

# Clone backend repository
git clone https://github.com/areebahmeddd/superbox.ai.git
cd superbox.ai

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# or .\.venv\Scripts\Activate.ps1 (Windows)

# Install CLI
python -m pip install -e .[cli]

​
Quick Start

1

Authenticate

superbox auth login --provider google
# or
superbox auth login --provider email
Device flow for Google/GitHub is supported; email/password works too.
2

Init server config

superbox init
Creates superbox.json with name, repo URL, entrypoint, license, etc.
3

Publish with scans

superbox push --name my-mcp
Runs SonarCloud, tool discovery, Snyk, GitGuardian, and Bandit, then uploads to R2 registry.
4

Configure client

superbox pull --name my-mcp --client cursor
Clients supported: vscode, cursor, windsurf, claude, chatgpt.
5

View logs

superbox logs --name my-mcp
Prints wrangler tail instructions for streaming logs from the Cloudflare Worker.

​
Available Commands

​
Authentication

auth register

Create new account

auth login

Log in with email/Google/GitHub

auth status

Check auth status

auth logout

Log out

​
Server Management

init

Initialize superbox.json

push

Publish to registry with security scans

pull

Configure client for server

search

List registry servers

​
Testing & Debugging

run

Deprecated

test

Test without registry

logs

View Worker log instructions

inspect

Open repository in browser

​
Command Reference

# Authentication
superbox auth register
superbox auth login [--provider email|google|github]
superbox auth status
superbox auth refresh
superbox auth logout

# Server management
superbox init
superbox push [--name NAME] [--force]
superbox pull --name NAME --client CLIENT
superbox search
superbox inspect --name NAME

# Testing & debugging
superbox test --url URL --client CLIENT
superbox logs --name NAME [--follow]

​
Configuration

The CLI expects a .env file in your working directory for Cloudflare/Firebase config: 
# Cloudflare
CLOUDFLARE_ACCOUNT_ID=your_account_id

# Cloudflare R2
CLOUDFLARE_R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
CLOUDFLARE_R2_ACCESS_KEY_ID=your_r2_key
CLOUDFLARE_R2_SECRET_ACCESS_KEY=your_r2_secret
CLOUDFLARE_R2_BUCKET_NAME=superbox-mcp-registry

# Cloudflare Worker URL
CLOUDFLARE_WORKER_URL=https://superbox-executor.<your-subdomain>.workers.dev

# Scanners (for push command)
SONAR_TOKEN=your_token
SONAR_ORGANIZATION=your_org
GITGUARDIAN_API_KEY=your_key
SNYK_API_TOKEN=your_snyk_api_token

​
Token Storage

Authentication tokens are stored in ~/.superbox/auth.json: 
{
  "id_token": "...",
  "refresh_token": "...",
  "email": "user@example.com",
  "provider": "google"
}

​
Examples

# Register and login
superbox auth register
superbox auth login --provider google

# Initialize and publish
superbox init
superbox push --name weather-mcp

# Configure client
superbox pull --name weather-mcp --client cursor

# Monitor
superbox logs --name weather-mcp --follow

​
Next Steps

Installation

Setup guide

Authentication

Auth commands

Publishing

Publish servers

Backend Setup

Run local server
For complete documentation, visit https://superbox.1mindlabs.org/docs