💬 Super CLI - Conversational Interface (Beta)

AI-Powered Command-Line Interface for SuperOptiX

Experience a new way to interact with SuperOptiX through natural language and intelligent automation.

🎯 Overview

Super CLI is SuperOptiX's conversational interface that combines:

Natural Language Understanding - Talk to SuperOptiX naturally
Intelligent Command Generation - AI translates your intent to commands
MCP Client Integration - Built-in Model Context Protocol support
Model Flexibility - Switch between Ollama, OpenAI, Anthropic models
Beautiful UI - Engaging animations and visual feedback

Beta Feature

Super CLI is currently in beta. We're actively improving the experience based on user feedback!

🚀 Getting Started

Launch Super CLI

# Just type 'super' with no arguments
super

You'll see:

✨ Welcome to Super CLI ✨

┌─────────────────────────────────────┐
│  Super CLI                          │
│  The Official SuperOptiX CLI        │
│  Using: ollama (gpt-oss:120b)       │
└─────────────────────────────────────┘

┌──────── 💡 Quick Start ─────────────┐
│ Essential Commands:                 │
│   /help     Full command reference  │
│   /ask      Ask questions           │
│   /model    List models             │
│   /mcp      MCP server status       │
│   /exit     Exit CLI                │
│                                     │
│ Natural Language:                   │
│   "Build a developer agent"         │
│   "Evaluate my agent"               │
│   "Optimize with GEPA"              │
└─────────────────────────────────────┘

┌─ 💬 Message ─────────────────────────────────────────┐
│ ▶ _
└──────────────────────────────────────────────────────┘

🔐 Authentication

Super CLI supports secure authentication via GitHub OAuth for accessing cloud features and marketplace.

SuperOptiX › /login

What happens:

🔗 OAuth URL Generated - Secure PKCE-based authentication
🌐 Browser Opens - GitHub authorization page
✅ Authorize SuperOptiX - Grant profile access
🔑 Token Saved - Credentials stored securely locally

Example output:

🔑 Login to SuperOptiX

Click the URL below to open in your browser:

🔗 Click here to authenticate

Or copy and paste this URL:
https://fffpinwooyqblbpdxicq.supabase.co/auth/v1/authorize?...

💡 After authenticating, return here and wait...

⏳ Waiting for authentication...

🔑 Completing authentication...

✅ Successfully logged in!

👤 User: OllyLondon
📧 Email: ollybabalondon@gmail.com

Secure OAuth 2.0 with PKCE

SuperOptiX uses industry-standard OAuth 2.0 with PKCE (Proof Key for Code Exchange) for maximum security. Your GitHub password is never seen by SuperOptiX!

SuperOptiX › /whoami

Shows your current authentication status:

┌────────── 🔐 Authentication Status ──────────┐
│  👤 Logged in as                             │
│                                              │
│  Username: @OllyLondon                       │
│  Email: ollybabalondon@gmail.com             │
│  Name: Olly                                  │
│  Avatar: https://avatars.github...           │
│                                              │
│  Use /logout to sign out                     │
└──────────────────────────────────────────────┘

If not logged in:

⚠️  Not logged in
Run /login to authenticate with GitHub

Logout

SuperOptiX › /logout

What it does:

🚪 Revokes Token - Invalidates token on server
🗑️ Clears Credentials - Deletes local auth file
👋 Confirms Logout - Shows success message

Example output:

🚪 Signing out...

┌─────────────── 👋 See You Soon! ───────────────┐
│  ✅ Logged out successfully!                    │
│                                                 │
│  Goodbye, @OllyLondon!                          │
│                                                 │
│  Your credentials have been cleared.            │
│  To login again, use: /login                    │
└─────────────────────────────────────────────────┘

Security Best Practice

Always logout when using Super CLI on shared or public computers!

Switch Accounts

To switch between different GitHub accounts:

# 1. Logout from current account
SuperOptiX › /logout

# 2. Login with different account
SuperOptiX › /login
# (Authenticate with different GitHub account in browser)

For CI/CD environments or automated workflows:

SuperOptiX › /login --token YOUR_ACCESS_TOKEN

Keep Tokens Secure

Access tokens should be kept secret. Don't share them or commit them to version control!

Authentication Features

Feature	Description	Command
OAuth Login	Secure GitHub authentication	`/login`
Token Login	Direct token authentication	`/login --token <token>`
Check Status	View current user	`/whoami`
Logout	Sign out and clear credentials	`/logout`
Auto-Expiry	Tokens expire after 1 hour	Automatic
Server Revocation	Immediate token invalidation	On `/logout`

Security & Privacy

What's Protected: - ✅ OAuth 2.0 with PKCE - Industry-standard security - ✅ No Password Storage - GitHub handles authentication - ✅ Local Credentials - Tokens stored in ~/.superoptix/auth.json - ✅ Limited Scopes - Only reads your profile (email, name, avatar) - ✅ Server Revocation - Logout invalidates tokens immediately

Your Data: - ✅ Profile Only - Email, username, avatar - ❌ No Repo Access - Can't read or modify repositories - ❌ No Write Permissions - Read-only profile access - ✅ Revocable Anytime - Logout or revoke in GitHub settings

Token Storage: - 📁 Location: ~/.superoptix/auth.json - 🔒 Permissions: User-only (600) - ⏱️ Expiry: Access token expires in 1 hour - 🔄 Refresh: Refresh token for seamless re-auth

Industry Standards

Super CLI follows the same authentication approach as GitHub CLI, Heroku CLI, and other modern CLI tools.

Troubleshooting

If you see "Port 54321 already in use":

# Check what's using the port
lsof -i :54321

# Kill the process (macOS/Linux)
kill -9 <PID>

# Try login again
SuperOptiX › /login

OAuth Callback Fails

If browser shows error after GitHub authorization:

Check Supabase Configuration:
Site URL should be http://localhost:54321
Redirect URLs should include http://localhost:54321/callback

Try Again:

SuperOptiX › /logout  # Clear any partial state
SuperOptiX › /login   # Fresh login attempt

Token Expired

If you see "Token expired" errors:

# Logout and login again
SuperOptiX › /logout
SuperOptiX › /login

Tip: Tokens expire after 1 hour. Re-login to get a fresh token.

💬 Natural Language Mode

Just Type What You Want

Super CLI understands natural language and translates it to the right commands.

Examples:

# Build an agent
SuperOptiX › build a developer agent

✨ Let me cook...
  ✓ Understood: build (developer)
🔧 Preparing the perfect command...
  ✓ Generated 1 command(s)
🚀 Launching your request...
✅ Agent created successfully!

# Evaluate an agent
SuperOptiX › evaluate my customer support agent

🤔 Analyzing your request...
  ✓ Understood: evaluate (customer_support)
⚙️ Tuning parameters...
  ✓ Generated 1 command(s)
⚡ Running the command...
✅ Evaluation complete!

# Optimize with GEPA
SuperOptiX › optimize the code review agent with GEPA

💡 Got an idea...
  ✓ Understood: optimize (code_review)
🗺️ Charting the course...
  ✓ Generated 1 command(s)
🧠 AI at work...
✅ Optimization complete!

Supported Intents

What You Say	What It Does
"build/create a agent"	Generates agent with SuperSpec
"compile "	Compiles agent playbook to pipeline
"evaluate/test "	Runs BDD evaluation
"optimize "	Optimizes agent with GEPA
"run with "	Executes agent with goal
"list agents"	Shows available agents
"show config"	Displays configuration

🔧 Slash Commands

Core Commands

# Get help
SuperOptiX › /help

# Ask questions about SuperOptiX
SuperOptiX › /ask how does GEPA optimization work?

# List available models
SuperOptiX › /model list

# Switch models
SuperOptiX › /model set gpt-4o-mini

# Show configuration
SuperOptiX › /config

# Exit
SuperOptiX › /exit

Agent Management

# List marketplace agents
SuperOptiX › /agents

# List compiled playbooks in current project
SuperOptiX › /playbooks

MCP Commands

# Check MCP server status
SuperOptiX › /mcp status

# List MCP servers
SuperOptiX › /mcp list

# Show available MCP tools
SuperOptiX › /mcp tools

# Add MCP server
SuperOptiX › /mcp add

# Enable/disable server
SuperOptiX › /mcp enable <server_name>
SuperOptiX › /mcp disable <server_name>

Utility Commands

# Show conversation history
SuperOptiX › /history

# Clear screen
SuperOptiX › /clear

🤖 Model Management

Built-in Support for Multiple Providers

Local Models (Ollama): - llama3.2:1b, llama3.2:3b - gpt-oss:20b, gpt-oss:120b - qwen2.5-coder:7b - Any Ollama model

Cloud Models (OpenAI): - gpt-4o, gpt-4o-mini - gpt-3.5-turbo

Cloud Models (Anthropic): - claude-3-5-sonnet-20241022 - claude-3-opus-20240229

List Available Models

SuperOptiX › /model list

Output:

🤖 Available Models

Local Models (Ollama):
  • llama3.2:1b           Fast, lightweight
  • gpt-oss:120b         Powerful reasoning
  • qwen2.5-coder:7b     Code specialist

Cloud Models (OpenAI):
  • gpt-4o-mini          Cost-effective, fast
  • gpt-4o               Most capable

Cloud Models (Anthropic):
  • claude-3-5-sonnet    Best for complex tasks

Switch Models

# Switch to local model
SuperOptiX › /model set gpt-oss:120b

# Switch to cloud model
SuperOptiX › /model set gpt-4o-mini

Notes: - Model used for CLI conversation only - Agents use their playbook-specified models - No interference between CLI and agent models

🔧 MCP Client Features

What is MCP?

Model Context Protocol - Industry standard for connecting AI models to external tools and data sources.

SuperOptiX Super CLI acts as an MCP client, allowing you to: - Connect to MCP servers (filesystem, databases, APIs) - Use MCP tools for knowledge access - Manage server configurations - Monitor server status

Check MCP Status

SuperOptiX › /mcp status

Output:

🔧 MCP Client Status

Status: Ready ✅

Active Servers:
  • filesystem - Local file access
    Status: Connected ✅
    Tools: 3 available

Available Tools:
  • read_file(path) - Read file contents
  • write_file(path, content) - Write to file
  • list_directory(path) - List files in directory

Manage MCP Servers

# List configured servers
SuperOptiX › /mcp list

# Add a server
SuperOptiX › /mcp add
# Interactive wizard will guide you

# Enable/disable server
SuperOptiX › /mcp enable filesystem
SuperOptiX › /mcp disable database

MCP Tools

# List available tools
SuperOptiX › /mcp tools

# Tools are automatically used by Super CLI when relevant
# For example, when you ask about code, it can read files via MCP

🎨 Visual Features

Engaging Animations

58+ Rotating Messages keep the experience fresh:

Thinking Phase: - "✨ Let me cook..." - "🧠 Neurons firing..." - "💫 Channeling the AI spirits..." - "🔮 Figuring this out..." - And 26+ more!

Preparing Phase: - "🔧 Preparing the perfect command..." - "🗺️ Charting the course..." - "🎯 Aiming for perfection..." - And 5+ more!

Executing Phase: - "🚀 Launching your request..." - "🔥 Executing with style..." - "⚡ Zapping it into existence..." - And 17+ more!

Progressive Status

✨ Let me cook...

  ✓ Understood: build (developer)

🔧 Preparing the perfect command...

  ✓ Generated 1 command(s)

🚀 Launching your request...

✅ Success!

Smooth, continuous animations until each step completes!

⚙️ Configuration

First-Time Setup

Super CLI runs a setup wizard on first launch:

super

You'll configure: 1. Model Provider - Ollama (local) or OpenAI/Anthropic (cloud) 2. Default Model - Which model to use for conversations 3. API Keys - For cloud providers (optional)

Wizard saves to: ~/.superoptix_config.json

View Configuration

SuperOptiX › /config

Shows: - Current model provider - Active model - API key status (masked) - MCP server status

Change Model

# Switch model anytime
SuperOptiX › /model set gpt-4o-mini

✅ Switched to: gpt-4o-mini
   Provider: openai

🧠 Knowledge Base

Ask About SuperOptiX

Super CLI has built-in knowledge about SuperOptiX features:

SuperOptiX › /ask how does GEPA optimization work?

Gets answers from: 1. Curated Knowledge - Pre-built Q&A (12 topics) 2. Documentation - Direct access to docs/ files 3. MCP Tools - Filesystem access for examples

Topics covered: - Memory optimization - RAG setup - Tool integration - GEPA algorithm - SuperSpec DSL - Agent tiers - Compilation process - Evaluation methods - Optimization levels - CLI commands - Fresh flag usage - Multi-agent orchestration

🎯 Use Cases

Quick Prototyping

SuperOptiX › build a customer support agent for e-commerce

✨ Working on it...
✅ Agent created successfully!

SuperOptiX › compile it

🔧 Assembling the pieces...
✅ Compiled!

SuperOptiX › evaluate the agent

🚀 Launching evaluation...
✅ Evaluation complete!
Score: 85%

Iterative Optimization

SuperOptiX › optimize customer_support with GEPA at high level

🧠 AI at work...
✅ Optimization complete!
Best score: 92%

SuperOptiX › evaluate it again

⚡ Running the command...
✅ Evaluation complete!
Score: 92% (improved 7%!)

Multi-Agent Workflows

SuperOptiX › create a software development team

💡 Got an idea...
✅ Created developer, qa_engineer, devops_engineer

SuperOptiX › compile all of them

🔨 Building it now...
✅ All agents compiled!

SuperOptiX › create an orchestra for them

🎵 Orchestrating the plan...
✅ Orchestra created!

📖 Command Reference

Natural Language

Command Pattern	Example	What It Does
`build/create <name>`	"build a developer agent"	Generate agent with SuperSpec
`compile <name>`	"compile developer"	Compile playbook to pipeline
`evaluate <name>`	"evaluate my agent"	Run BDD tests
`optimize <name>`	"optimize with GEPA"	GEPA optimization
`run <name> with <goal>`	"run developer with goal X"	Execute agent

Slash Commands

Command	Description
`/help`	Full command reference with examples
`/ask <question>`	Ask about SuperOptiX features
`/login`	Login with GitHub OAuth
`/login --token <token>`	Login with access token
`/logout`	Logout and clear credentials
`/whoami`	Show current logged-in user
`/model list`	List available models
`/model set <name>`	Switch to different model
`/config`	Show current configuration
`/agents`	List marketplace agent templates
`/playbooks`	List compiled playbooks (requires project)
`/mcp status`	Check MCP server status
`/mcp list`	List MCP servers
`/mcp tools`	Show available MCP tools
`/history`	Show conversation history
`/clear`	Clear screen
`/exit` or `/quit`	Exit Super CLI

🔒 Security & Privacy

Local-First by Default

Super CLI prioritizes local models: - Uses Ollama by default (runs on your machine) - No data sent to cloud unless you choose cloud models - MCP servers run locally - All data stays on your machine

Cloud Models (Optional)

If you choose OpenAI or Anthropic: - Your conversations go to their APIs - You control the API keys - Keys stored locally in ~/.superoptix_config.json - You can delete anytime

MCP Security

MCP servers have controlled access: - Filesystem server: Read/write permissions you grant - Each server can be enabled/disabled - Full audit trail of tool usage - You control what data is accessible

🎨 Visual Features

Animations

Continuous feedback during processing: - Thinking animations while parsing intent - Preparing animations while generating commands - Executing animations while running commands - Smooth transitions between steps

58+ rotating messages: - "✨ Let me cook..." - "🧠 Neurons firing..." - "🔥 Warming up the engines..." - Different every time for engagement!

Clean Output

Focus on results, not technical details: - ✅ Success indicators - ❌ Clear error messages - 📊 Relevant information only - No command clutter

⚙️ Advanced Features

Conversation Context

Super CLI remembers your session: - Recent interactions - Current agent you're working on - Project state

Example:

SuperOptiX › build a developer agent
✅ Created!

SuperOptiX › compile it
# Knows "it" refers to developer agent
✅ Compiled!

SuperOptiX › evaluate
# Knows which agent to evaluate
✅ Evaluated!

Hybrid Knowledge Access

Super CLI uses multiple knowledge sources:

Curated Q&A - Pre-built answers for common questions
Documentation Access - Reads from docs/ directory
MCP Tools - Filesystem access for examples and code

Combines all three for comprehensive answers!

Model Isolation

Important: Super CLI's model is separate from agent models!

CLI model: Used for conversation and intent parsing
Agent models: Specified in playbooks, used during execution

No interference: Changing CLI model doesn't affect your agents!

🚀 Best Practices

Choose the Right Model

For CLI Conversation: - Local (Ollama): gpt-oss:120b - Great balance of speed and capability - Cloud (OpenAI): gpt-4o-mini - Fast and cost-effective - Cloud (Anthropic): claude-3-5-sonnet - Best for complex reasoning

For Agents: - Configure in playbook YAML - Can use different model than CLI - Independent of CLI model choice

Use Natural Language

Good: - "build a developer agent" - "evaluate my agent" - "optimize with GEPA at high level"

Also works (slash commands): - "/agents" - Quick reference - "/help" - Full documentation - "/ask " - Specific questions

Leverage MCP

Enable filesystem server:

SuperOptiX › /mcp status
SuperOptiX › /mcp enable filesystem

Now Super CLI can: - Read your code files - Access examples - Provide context-aware answers

🔧 Troubleshooting

CLI Won't Start

Check installation:

pip show superoptix | grep Version
# Should show: Version: 0.1.2 or higher

Reinstall if needed:

pip install --upgrade superoptix

Model Not Found

For Ollama models:

# List available
ollama list

# Pull model if needed
ollama pull gpt-oss:120b

For cloud models:

# Set API key
export OPENAI_API_KEY=your-key
# Or configure in setup wizard

MCP Server Not Working

Check server status:

SuperOptiX › /mcp status

Restart server:

SuperOptiX › /mcp disable filesystem
SuperOptiX › /mcp enable filesystem

📊 Comparison: Traditional CLI vs Super CLI

Feature	Traditional CLI	Super CLI
Syntax	Exact commands required	Natural language
Examples	`super spec generate genies dev --namespace software`	"build a developer agent"
Learning Curve	Medium (learn commands)	Low (just talk)
Flexibility	Fixed syntax	Understands variations
Feedback	Text output	Animated, visual
Model Support	Agent models only	CLI + Agent models
MCP	Manual integration	Built-in client
Knowledge	External docs	Built-in Q&A + docs

Both available - use what fits your workflow!

🎯 Common Workflows

Build → Compile → Evaluate → Optimize

SuperOptiX › build a developer agent
✅ Created!

SuperOptiX › compile it
✅ Compiled!

SuperOptiX › evaluate the agent
✅ Evaluated! Score: 78%

SuperOptiX › optimize with GEPA
✅ Optimized! Score: 91%

SuperOptiX › evaluate again
✅ Evaluated! Score: 91%

Agent Discovery

SuperOptiX › /agents
📦 Available Agents

🔹 Software Development
  • developer, qa_engineer, devops_engineer

🔹 Customer Support
  • customer_support, sales_agent

SuperOptiX › /ask tell me about the developer agent
📚 The developer agent...

MCP Integration

SuperOptiX › /mcp status
🔧 MCP Client Ready ✅

SuperOptiX › /ask show me an example of RAG optimization
📚 Reading from docs/guides/rag.md...
(Uses MCP filesystem access)

🔮 Future Enhancements

Coming Soon

🎯 Multi-turn conversations (context across sessions)
🧠 Learning from your patterns
🔌 More MCP server integrations
🌐 Remote MCP server support
📊 Visual dashboards in terminal
🎨 Customizable themes
🗣️ Voice input support

Feedback Welcome!

Super CLI is in beta - we want your input!

💬 Join our Discord: SuperagenticAI
🐛 Report issues: GitHub Issues
💡 Feature requests: Discussions

CLI Complete Guide - Traditional CLI reference
MCP Tools Guide - MCP integration details
GEPA Optimization - Optimization strategies
Agent Development - Building agents

✨ Summary

Super CLI brings conversational AI to your terminal:

💬 Natural language - just talk
🤖 Model flexibility - local or cloud
🔧 MCP client - built-in tool access
🎨 Beautiful UI - engaging animations
📚 Knowledge access - built-in docs
🚀 Production ready - stable and tested

Experience the future of AI development tools!

super  # Launch and explore!

💬 Super CLI - Conversational Interface (Beta)

🎯 Overview

🚀 Getting Started

Launch Super CLI

🔐 Authentication

Login with GitHub

First Time Login

Check Login Status

Logout

Switch Accounts

Token-Based Login (Advanced)

Authentication Features

Security & Privacy

Troubleshooting

Can't Login - Port Already in Use

OAuth Callback Fails

Token Expired

💬 Natural Language Mode

Just Type What You Want

Supported Intents

🔧 Slash Commands

Core Commands

Agent Management

MCP Commands

Utility Commands

🤖 Model Management

Built-in Support for Multiple Providers

List Available Models

Switch Models

🔧 MCP Client Features

What is MCP?

Check MCP Status

Manage MCP Servers

MCP Tools

🎨 Visual Features

Engaging Animations

Progressive Status

⚙️ Configuration

First-Time Setup

View Configuration

Change Model

🧠 Knowledge Base

Ask About SuperOptiX

🎯 Use Cases

Quick Prototyping

Iterative Optimization

Multi-Agent Workflows

📖 Command Reference

Natural Language

Slash Commands

🔒 Security & Privacy

Local-First by Default

Cloud Models (Optional)

MCP Security

🎨 Visual Features

Animations

Clean Output

⚙️ Advanced Features

Conversation Context

Hybrid Knowledge Access

Model Isolation

🚀 Best Practices

Choose the Right Model

Use Natural Language

Leverage MCP

🔧 Troubleshooting

CLI Won't Start

Model Not Found

MCP Server Not Working

📊 Comparison: Traditional CLI vs Super CLI

🎯 Common Workflows

Build → Compile → Evaluate → Optimize

Agent Discovery

MCP Integration

🔮 Future Enhancements

Coming Soon

Feedback Welcome!

📖 Related Documentation

✨ Summary