Skip to content

SuperOptiX CLI Reference

Welcome to the comprehensive SuperOptiX CLI reference! This document covers all available commands, their options, and usage examples, reflecting the actual implementation.

Table of Contents

Getting Started

Basic Workflow

# 1. Initialize a new project
super init my_project
cd my_project

# 2. Generate an agent using SuperSpec DSL
super spec generate genies developer --namespace software

# 3. Compile the agent
super agent compile developer

# 4. Evaluate the agent
super agent evaluate developer

# 5. Run the agent
super agent run developer --goal "Implement a basic calculator"

Quick Reference

# Project management
super init <project_name>           # Initialize new project
super docs                          # Show comprehensive guide

# Agent lifecycle
super agent pull <name>             # Add pre-built agent
super agent compile <name>          # Compile agent to Python
super agent evaluate <name>         # Test agent with BDD
super agent run <name> --goal <goal> # Execute agent
super agent list                    # List project agents

# Model management
super model list                    # List installed models
super model install <model>         # Install model
super model run <model> <prompt>    # Run model with auto-installation
super model remove <model>          # Remove model
super model refresh                 # Refresh model cache
super model server <backend> <model> # Start local server

# DSL and development
super spec generate <tier> <name>   # Generate agent playbook
super spec validate <file>          # Validate playbook
super spec analyze <path>           # Analyze playbooks

# Multi-agent workflows
super orchestra create <name>       # Create orchestra
super orchestra run <name> --goal <goal> # Run orchestra

# Discovery and tools
super marketplace                   # Browse marketplace
super marketplace search <query>    # Search components
super marketplace install agent <name> # Install agent

# Monitoring and debugging
super observe dashboard             # Launch observability dashboard
super observe traces <agent_id>     # View execution traces

Core Commands

init

Initialize a new SuperOptiX project with the complete directory structure.

super init <project_name>

Arguments: - project_name - Name of the agentic system (required)

Options: - --verbose - Show detailed project setup information

Example: 

super init my_ai_project

docs

Display comprehensive SuperOptiX documentation with examples and getting started information.

super docs

Agent Management (agent or ag)

agent pull

Pull a pre-built agent into your project from the SuperOptiX library. This command has an alias pl.

super agent pull <name> [options]

Arguments: - name - Name of the pre-built agent to add (required)

Options: - --tier {oracles,genies} - Agent tier level (default: oracles) - --force - Force overwrite if agent already exists - --verbose - Show detailed agent information and guidance

agent compile

Compile an agent playbook into executable Python code. This command has an alias co.

super agent compile [name] [options]

Arguments: - name - Name of the agent to compile (optional if using --all)

Options: - --tier {oracles,genies} - Override playbook tier for compilation - --all - Compile all agents in the project - --abstracted - Use abstracted pipeline with SuperOptixPipeline base class - --verbose - Show detailed guidance and feature explanations

agent design

Interactively design an agent. This command has an alias de.

super agent design <agent> [options]

Arguments: - agent - Name of the agent to design (required)

Options: - --tier - Specify the agent tier for the designer

agent inspect

Show detailed information and metadata about an agent. This command has an alias in.

super agent inspect <name>

Arguments: - name - Name of the agent to inspect (required)

agent lint

Validate agent playbooks for syntax and best practices. This command has an alias li.

super agent lint [name] [options]

Arguments: - name - Name of the agent to lint (optional if using --all)

Options: - --all - Lint all agents in the project

agent list

List all agents in the project or pre-built agents available. This command has aliases ls and ps.

super agent list [options]

Options: - --pre-built - List all available pre-built agents from the library - --industry - Filter pre-built agents by industry

agent optimize

Optimize an agent pipeline using DSPy optimization techniques. This command has an alias op.

super agent optimize <name> [options]

Arguments: - name - Name of the agent to optimize (required)

Options: - --force - Force re-optimization even if an optimized version already exists. - --verbose - Show detailed guidance and optimization information

agent evaluate

Evaluate an agent using its BDD specification tests. This command has an alias ev.

super agent evaluate <name> [options]

Arguments: - name - Name of the agent to evaluate (required)

Options: - --auto-tune - Enable auto-tuning for evaluation metrics - --ignore-checks - Ignore non-essential checks during testing - --verbose, -v - Show detailed results for each BDD specification - --format {table,json,junit} - Output format for test results (default: table) - --save-report FILE - Save detailed test report to a file

agent run

Execute an agent with a specific goal. This command has an alias ru.

super agent run <name> --goal <goal>

Arguments: - name - Name of the agent to run (required) - --goal - Goal description for the agent (required)

Options: - --verbose - Show detailed execution information and guidance

agent rm

Remove an agent from your project.

super agent rm <name>

Arguments: - name - Name of the agent to remove (required)

This command will prompt for confirmation before deleting the agent's playbook and compiled pipeline files.

agent tier-status

Show tier status and capabilities of agents in the project. This command has an alias ts.

super agent tier-status

Model Intelligence System (model or md)

model list

List SuperOptiX models (installed by default). This command has an alias ls.

super model list [options]

Options: - --backend {ollama,mlx,huggingface,lmstudio} - Filter by backend - --size {tiny,small,medium,large} - Filter by size - --task {chat,code,reasoning,embedding} - Filter by task - --installed-only - Show only installed models (default) - --all - Show all available models - --verbose, -v - Show detailed information

model discover

Show SuperOptiX Model Discovery Guide. This command has an alias disc.

super model discover

model guide

Show SuperOptiX Model Installation Guide. This command has an alias g.

super model guide

model install

Install a SuperOptiX model. This command has an alias i.

super model install <model_name> [options]

Arguments: - model_name - Model name to install (required)

Options: - --backend, -b {ollama,mlx,huggingface,lmstudio} - Specify backend

model run

Run a prompt against a SuperOptiX model with automatic installation.

super model run <model_name> <prompt> [options]

Arguments: - model_name - Name of the model to run (required) - prompt - Prompt to send to the model (required)

Options: - --backend, -b {ollama,mlx,huggingface} - Backend to use (auto-detected if not specified) - --interactive, -i - Run in interactive mode - --max-tokens, -m - Maximum tokens to generate (default: 2048) - --temperature, -t - Temperature for generation 0.0-2.0 (default: 0.7)

Features: - Auto-installation: Automatically installs models if not found - Backend auto-detection: Finds the correct backend for the model - Interactive mode: Supports conversation mode with history - Real-time execution: Direct model execution without server setup

Supported Backends: - Ollama: Uses ollama run command - MLX: Downloads and uses MLX-LM directly - HuggingFace: Downloads and uses transformers pipeline directly - LM Studio: Not supported (designed for server mode)

Examples: 

# Single prompt execution
super model run llama3.2:3b "Write a Python function to add two numbers" --backend ollama

# Interactive mode
super model run llama3.2:3b "" --backend ollama --interactive

# Auto-detection with auto-installation
super model run mlx-community/Llama-3.2-3B-Instruct-4bit "Write a hello world program" --backend mlx

# HuggingFace with auto-installation
super model run microsoft/phi-1_5 "Write a simple calculator" --backend huggingface

model remove

Remove a model from a specific backend.

super model remove <model_name> [options]

Arguments: - model_name - Name of the model to remove (required)

Options: - --backend, -b {ollama,mlx,huggingface,lmstudio} - Backend to remove from (auto-detected if not specified)

  • --all-backends - Remove from all backends where it exists

Features: - Auto-backend detection: Automatically finds the backend containing the model - Intelligent removal: Removes model files and cache entries - Cross-backend support: Works with all supported backends - Safe removal: Confirms model existence before removal

Examples: 

# Remove from specific backend
super model remove llama3.2:3b --backend ollama

# Remove from all backends
super model remove llama3.2:3b --all-backends

# Force removal
super model remove llama3.2:3b

model refresh

Refresh the SuperOptiX model cache.

super model refresh

Description: Updates the local cache of available models by querying all backends and rebuilding the internal model registry.

Use cases: - After manually installing models outside of SuperOptiX - When models are deleted manually - To resolve cache inconsistencies - After backend updates or changes

Example: 

super model refresh

model info

Get detailed information about a SuperOptiX model. This command has an alias inf.

super model info <model_name>

Arguments: - model_name - Model name to get info about (required)

model backends

Show SuperOptiX backend status. This command has an alias b.

super model backends

model dspy

Create DSPy client for SuperOptiX model. This command has an alias d.

super model dspy <model_name> [options]

Arguments: - model_name - Model name for DSPy client (required)

Options: - --temperature, -t - Temperature for generation (default: 0.7) - --max-tokens, -m - Maximum tokens (default: 2048)

model server

Start local server for SuperOptiX models. This command has an alias srv.

super model server <backend> <model_name> [options]

Arguments: - backend - Backend type (mlx, huggingface, lmstudio) - model_name - Model name to start server for (required)

Options: - --port, -p - Port to run server on (default varies by backend)

Examples: 

# Start MLX server
super model server mlx mlx-community/Llama-3.2-3B-Instruct-4bit --port 8000

# Start HuggingFace server
super model server huggingface microsoft/Phi-4 --port 8001

# Start LM Studio server
super model server lmstudio llama-3.2-1b-instruct --port 1234

model convert

Convert HuggingFace model to MLX format (EXPERIMENTAL). This command has an alias c.

super model convert <hf_model> [options]

Arguments: - hf_model - HuggingFace model to convert (e.g., 'microsoft/phi-2')

Options: - --output, -o - Output path for converted model (default: model name) - --quantize, -q - Generate a quantized model - --bits - Bits per weight for quantization (default: 4) - --group-size - Group size for quantization (default: 64) - --quant-recipe - Mixed quantization recipe (mixed_2_6, mixed_3_4, mixed_3_6, mixed_4_6) - --dtype - Data type (float16, bfloat16, float32) - --upload - HuggingFace repo to upload converted model to - --dequantize - Dequantize a quantized model - --trust-remote-code - Trust remote code from HuggingFace

Note: This command is experimental and requires MLX backend to be available.

model quantize

Quantize or dequantize an MLX model (EXPERIMENTAL). This command has an alias q.

super model quantize <model_name> [options]

Arguments: - model_name - MLX model to quantize (required)

Options: - --output, -o - Output path for quantized model - --bits - Bits per weight for quantization (default: 4) - --group-size - Group size for quantization (default: 64) - --recipe - Mixed quantization recipe (mixed_2_6, mixed_3_4, mixed_3_6, mixed_4_6) - --dequantize - Dequantize instead of quantize

Note: This command is experimental and requires MLX backend to be available.

SuperSpec DSL (spec)

spec generate

Generate agent playbook templates with customizable features. This command has an alias gen.

super spec generate <tier> <name> [options]

Arguments: - tier - Agent tier: oracles or genies (required) - name - Agent name (required)

Options: - --namespace - Agent namespace (default: software) - --role - Agent role description (default: Assistant) - --description - Detailed agent description - --output - Output directory or file path - --format - Output format: yaml or json (default: yaml) - --memory/--no-memory - Enable/disable memory system (Genie only, default: true) - --tools/--no-tools - Enable/disable tool integration (Genie only, default: true) - --rag - Enable RAG/retrieval (Genie only, default: false)

spec validate

Validate agent playbook files. This command has an alias val.

super spec validate <files> [options]

Arguments: - files - One or more playbook files to validate (required)

Options: - --verbose, -v - Show detailed validation output - --format {table,json} - Output format (default: table)

spec analyze

Get insights about your playbooks. This command has an alias an.

super spec analyze <path> [options]

Arguments: - path - Directory or file path to analyze (required)

Options: - --pattern - File pattern to match (default: *.yaml) - --format {table,json} - Output format (default: table)

spec info

Show detailed agent information. This command has an alias inf.

super spec info <file>

Arguments: - file - Agent playbook file (required)

spec schema

Show DSL schema information. This command has an alias sch.

super spec schema [options]

Options: - --tier {oracles,genies} - Show features for specific tier

spec bootstrap

Bootstrap agents for a namespace. This command has an alias boot.

super spec bootstrap <namespace> [options]

Arguments: - namespace - Target namespace (required)

Options: - --output-dir - Output directory (default: ./generated_agents) - --tiers - Tiers to generate (default: both oracles and genies)

Orchestra Management (orchestra or orch)

orchestra create

Create a new orchestra definition file. This command has an alias cr.

super orchestra create <name>

Arguments: - name - Name of the orchestra to create (required)

Options: - --verbose - Show detailed orchestra configuration and guidance

orchestra list

List all orchestras in the project. This command has an alias ls.

super orchestra list