> ## Documentation Index
> Fetch the complete documentation index at: https://acm-aa28ebf6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

<Info>
  All CLI documentation matches the actual backend implementation. For detailed setup and usage, visit [https://superbox.1mindlabs.org/docs](https://superbox.1mindlabs.org/docs)
</Info>

## Installation

```bash theme={null}
# 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

<Steps>
  <Step title="Authenticate">
    ```bash theme={null}
    superbox auth login --provider google
    # or
    superbox auth login --provider email
    ```

    Device flow for Google/GitHub is supported; email/password works too.
  </Step>

  <Step title="Init server config">
    ```bash theme={null}
    superbox init
    ```

    Creates `superbox.json` with name, repo URL, entrypoint, license, etc.
  </Step>

  <Step title="Publish with scans">
    ```bash theme={null}
    superbox push --name my-mcp
    ```

    Runs SonarCloud, tool discovery, Snyk, GitGuardian, and Bandit, then uploads to R2 registry.
  </Step>

  <Step title="Configure client">
    ```bash theme={null}
    superbox pull --name my-mcp --client cursor
    ```

    Clients supported: `vscode`, `cursor`, `antigravity`, `claude`, `chatgpt`.
  </Step>

  <Step title="View logs">
    ```bash theme={null}
    superbox logs --name my-mcp
    ```

    Prints `wrangler tail` instructions for streaming logs from the Cloudflare Worker.
  </Step>
</Steps>

## Available Commands

### Authentication

<CardGroup cols={2}>
  <Card title="auth register" icon="user-plus" href="/cli/auth">
    Create new account
  </Card>

  <Card title="auth login" icon="right-to-bracket" href="/cli/auth">
    Log in with email/Google/GitHub
  </Card>

  <Card title="auth status" icon="circle-info" href="/cli/auth">
    Check auth status
  </Card>

  <Card title="auth logout" icon="right-from-bracket" href="/cli/auth">
    Log out
  </Card>
</CardGroup>

### Server Management

<CardGroup cols={2}>
  <Card title="init" icon="wand-magic-sparkles" href="/cli/init">
    Initialize superbox.json
  </Card>

  <Card title="push" icon="cloud-arrow-up" href="/cli/push">
    Publish to registry with security scans
  </Card>

  <Card title="pull" icon="cloud-arrow-down" href="/cli/pull">
    Configure client for server
  </Card>

  <Card title="search" icon="magnifying-glass" href="/cli/search">
    List registry servers
  </Card>
</CardGroup>

### Testing & Debugging

<CardGroup cols={2}>
  <Card title="run" icon="ban" href="/cli/run">
    Deprecated
  </Card>

  <Card title="test" icon="flask" href="/cli/test">
    Test without registry
  </Card>

  <Card title="logs" icon="file-lines" href="/cli/logs">
    View Worker log instructions
  </Card>

  <Card title="inspect" icon="eye" href="/cli/inspect">
    Open repository in browser
  </Card>
</CardGroup>

## Command Reference

```bash theme={null}
# 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:

```bash theme={null}
# 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`:

```json theme={null}
{
  "id_token": "...",
  "refresh_token": "...",
  "email": "user@example.com",
  "provider": "google"
}
```

## Examples

<CodeGroup>
  ```bash Full Workflow theme={null}
  # 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
  ```

  ```bash Quick Test theme={null}
  # Test without publishing
  superbox test --url https://github.com/user/repo --client cursor
  ```

  ```bash Browse Servers theme={null}
  # Search and inspect
  superbox search
  superbox inspect --name weather-mcp
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/cli/installation">
    Setup guide
  </Card>

  <Card title="Authentication" icon="key" href="/cli/auth">
    Auth commands
  </Card>

  <Card title="Publishing" icon="upload" href="/cli/push">
    Publish servers
  </Card>

  <Card title="Backend Setup" icon="server" href="/backend/setup">
    Run local server
  </Card>
</CardGroup>

<Info>
  For complete documentation, visit [https://superbox.1mindlabs.org/docs](https://superbox.1mindlabs.org/docs)
</Info>