CLI Introduction

SuperBox CLI - Manage MCP servers end to end

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": "[e-mail]",
  "provider": "google"
}

Examples

Full Workflow

# 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