CLI Overview

Compozy provides a comprehensive command-line interface (CLI) for managing AI workflow orchestration. The CLI offers complete control over projects, workflows, executions, and MCP servers with both interactive TUI and automation-friendly JSON output.

Available Commands

CLI Architecture

The Compozy CLI follows a modular command structure that maps directly to the system's core components:

Loading diagram...

Command Categories

1
Project Management
compozy init - Initialize new Compozy projects with scaffolding
compozy config - Configuration management and diagnostics
2
Server Operations
compozy dev - Run development server with hot reload
compozy start - Start production server
compozy auth - Authentication and API key management
3
Workflow Management
compozy workflow list - List available workflows
compozy workflow get - Get workflow details
compozy workflow execute - Execute workflows
4
MCP Integration
compozy mcp-proxy - Run MCP proxy server for external tools

Global Options

The CLI provides consistent global options across all commands:

Output and Formatting

# Output format control
--format json|tui|auto    # Output format (default: auto)
-o, --output              # Alias for --format
--mode auto|json|tui      # CLI mode (default: auto)
--color-mode auto|on|off  # Color mode (default: auto)
--no-color                # Disable color output
-q, --quiet               # Suppress non-essential output

Configuration and Environment

# Configuration options
-c, --config path         # Path to configuration file
--cwd path                # Working directory for the project
--env-file path           # Path to environment variables file

# API connection
--server-url url          # Server URL for Compozy API (default: http://localhost:5001)
--base-url url            # Base URL for Compozy API (default: http://localhost:5001)
--api-key key             # Compozy API key for authentication
--timeout duration        # Timeout for API requests (default: 30s)

Server Configuration

# Server settings
--host string             # Host to bind server to (default: 0.0.0.0)
--port int                # Port to run server on (default: 5001)

# Database configuration
--db-host string          # Database host (default: localhost)
--db-port string          # Database port (default: 5432)
--db-name string          # Database name (default: compozy)
--db-user string          # Database user (default: postgres)
--db-password string      # Database password
--db-conn-string string   # Database connection string
--db-ssl-mode string      # Database SSL mode (default: disable)

Authentication and Security

# Authentication
--auth-enabled            # Enable authentication for API endpoints
--auth-workflow-exceptions strings  # Workflow IDs exempt from auth

# CORS configuration
--cors                    # Enable CORS (default: true)
--cors-allow-credentials  # Allow credentials in CORS (default: true)
--cors-allowed-origins strings  # Allowed CORS origins
--cors-max-age int        # CORS preflight max age (default: 86400)

Logging and Debugging

# Logging
--log-level level         # Log level: debug, info, warn, error (default: info)
-d, --debug               # Enable debug output and verbose logging

# Advanced options
--interactive             # Force interactive mode
--page-size int           # Default page size (default: 50)

Usage Patterns

Basic Usage

# Initialize a new project
compozy init my-project

# Start development server
compozy dev

# List workflows
compozy workflow list

# Execute a workflow
compozy workflow execute my-workflow

JSON Output for Automation

# Get machine-readable output
compozy workflow list --format json
compozy workflow get my-workflow -o json

# Quiet mode for scripting
compozy workflow execute my-workflow --quiet --format json

Configuration Management

# Use custom configuration
compozy dev --config /path/to/config.yaml

# Set working directory
compozy workflow list --cwd /path/to/project

# Use environment file
compozy start --env-file .env.production

Server Management

# Start on custom port
compozy start --port 8080

# Enable debug logging
compozy dev --debug --log-level debug

# Custom database connection
compozy start --db-host localhost --db-port 5433

Interactive vs Automation Modes

The Compozy CLI intelligently adapts its behavior based on the execution environment, providing optimal user experience for both human operators and automated systems.

Loading diagram...

1
Interactive Mode (TUI)
Automatically activated when running in a terminal with TTY support:
- Rich text user interface with colors and formatting
- Interactive prompts and confirmations for safety
- Real-time progress indicators for long operations
- Human-friendly error messages with suggestions
2
Automation Mode (JSON)
Optimized for CI/CD pipelines and scripting environments:
- Structured JSON output for easy parsing
- No interactive prompts that could block execution
- Machine-readable error messages with error codes
- Standardized exit codes for success/failure detection

# Force JSON mode explicitly
compozy workflow list --mode json

# Automation-friendly workflow execution
compozy workflow execute my-workflow --quiet --format json --timeout 300s

# Silent operation for CI/CD
compozy workflow execute my-workflow --quiet --no-color --format json

Error Handling

The CLI provides consistent error handling:

Exit Codes

0 - Success
1 - General error
2 - Configuration error
3 - Authentication error
4 - Network/connection error
5 - Validation error

Error Formats

# Human-readable errors (TUI mode)
Error: Failed to connect to server at http://localhost:5001
Suggestion: Check if the server is running or verify the --server-url flag

# JSON errors (automation mode)
{
  "error": "connection_failed",
  "message": "Failed to connect to server",
  "details": {
    "url": "http://localhost:5001",
    "timeout": "30s"
  }
}

Environment Variables

The CLI respects environment variables for common configuration:

# Core configuration
COMPOZY_CONFIG_PATH      # Configuration file path
COMPOZY_API_KEY          # API key for authentication
COMPOZY_SERVER_URL       # Server URL
COMPOZY_LOG_LEVEL        # Logging level

# Database configuration
COMPOZY_DB_HOST          # Database host
COMPOZY_DB_PORT          # Database port
COMPOZY_DB_NAME          # Database name
COMPOZY_DB_USER          # Database user
COMPOZY_DB_PASSWORD      # Database password
COMPOZY_DB_CONN_STRING   # Full connection string

# MCP proxy configuration  
MCP_PROXY_HOST           # MCP proxy host
MCP_PROXY_PORT           # MCP proxy port
MCP_PROXY_BASE_URL       # MCP proxy base URL

# LLM provider keys
OPENAI_API_KEY           # OpenAI API key