Suppose CLI

System simulator with what-if analysis, optimization, and AI-assisted design

Suppose CLI is a command-line tool for simulating system behavior, running what-if scenarios, and optimizing complex systems. Use it to analyze performance, costs, reliability, and other metrics across different configurations - or let AI help you design systems from scratch.

Installation

npm install -g suppose-cli

Quick Start

1. Authenticate

suppose login

2. Analyze a system

suppose analyze system.yaml

3. Chat with AI agent

suppose chat "create an API gateway system"

Commands

Authentication

• suppose login - Authenticate with Suppose (opens browser)
• suppose logout - Log out from Suppose
• suppose whoami - Show current user information

Analysis

• suppose analyze <file> - Analyze a YAML system diagram
• suppose whatif <file> - Run what-if analysis with parameter changes
• suppose optimize <file> - Run multi-objective optimization
• suppose sweep <file> - Run parameter sweep analysis
• suppose validate <file> - Validate a YAML system diagram

AI Agent

• suppose chat <message> - Chat with AI agent for YAML creation/modification

Examples

Analyze a System

suppose analyze system.yaml

What-If Analysis

suppose whatif system.yaml -c "api.latency=15" -c "cache.cost=0.001"

Optimization

suppose optimize system.yaml \
  -p "api.latency=5:20" \
  -p "cache.size=1:10" \
  -o "latency,cost,reliability"

Parameter Sweep

suppose sweep system.yaml -p "cache.latency" --start 1 --end 20 --step 1

AI Chat

suppose chat "create a 3-tier web application with load balancer"
suppose chat "add caching to reduce database load" -f system.yaml

Output Formats

All commands support JSON output for scripting and CI/CD:

suppose analyze system.yaml --json > results.json

Using stdin

All file-based commands support reading from stdin using - as the file path:

cat system.yaml | suppose analyze -
echo "..." | suppose analyze - --json
suppose analyze - < system.yaml

This is especially useful for agents and scripts that generate YAML dynamically.

Agent-Friendly Usage

Suppose CLI is optimized for use by AI coding agents (like Claude Code, GitHub Copilot, etc.) with:

Structured Error Messages

Errors are actionable and include suggestions:

$ suppose analyze nonexistent.yaml

Error [FILE_NOT_FOUND]: File not found: nonexistent.yaml
The specified file does not exist or is not accessible.

💡 Suggestion: Check the file path and ensure the file exists. Use "-" to read from stdin.

JSON Error Format

Use --json to get structured errors for programmatic handling:

$ suppose analyze nonexistent.yaml --json
{
  "code": "FILE_NOT_FOUND",
  "message": "File not found: nonexistent.yaml",
  "details": "The specified file does not exist or is not accessible.",
  "suggestion": "Check the file path and ensure the file exists. Use \"-\" to read from stdin.",
  "exitCode": 1
}

Exit Codes

• 0 - Success
• 1 - General error (authentication, validation, API error)
• 2 - Invalid arguments or usage

Check exit codes to determine command success:

if suppose analyze system.yaml --json > output.json; then
  echo "Analysis succeeded"
else
  echo "Analysis failed with exit code $?"
fi

Verbose Mode

Use -v or --verbose for detailed operation logs:

suppose analyze system.yaml -v
# Reading from: system.yaml
# Output format: text
# YAML size: 1024 bytes
# Analyzing system...

Complete Agent Workflow Example

# 1. Check authentication status
if ! suppose whoami --json > /dev/null 2>&1; then
  echo "Not authenticated. Please run: suppose login"
  exit 1
fi

# 2. Create YAML dynamically and analyze it
cat <<EOF | suppose analyze - --json > analysis.json
boxes:
  - name: api
    latency:
      typical: 10ms
      variance: 2ms
    cost:
      typical: 0.0001
      variance: 0.00001
    reliability:
      typical: 0.999
      variance: 0.001
topology:
  - box: api
    in: ["request: bytes"]
    out: ["response: bytes"]
EOF

# 3. Check if analysis succeeded
if [ $? -eq 0 ]; then
  echo "Analysis complete! Results in analysis.json"
  cat analysis.json | jq '.latency_ms'
else
  echo "Analysis failed"
  exit 1
fi

# 4. Run what-if analysis
suppose whatif - -c "api.latency=15" --json < system.yaml > whatif.json

# 5. Optimize parameters
suppose optimize - \
  -p "api.latency=5:20" \
  -p "api.cost=0.0001:0.001" \
  -o "latency,cost" \
  --json < system.yaml > optimization.json

Common Agent Patterns

Pattern 1: Generate and Validate

# Generate YAML, then validate it
echo "$GENERATED_YAML" | suppose validate - --json

Pattern 2: Iterate Until Valid

# Keep trying different configurations
for latency in 5 10 15 20; do
  suppose whatif system.yaml -c "api.latency=$latency" --json
done

Pattern 3: Use AI to Design

# Let AI create the system design
suppose chat "create a microservices architecture with API gateway, 3 services, and database" --json > design.json

# Extract YAML from response
cat design.json | jq -r '.yaml_result.content' > system.yaml

# Validate and analyze
suppose validate system.yaml && suppose analyze system.yaml --json

Environment Variables

• SUPPOSE_API_URL - Custom API URL (default: https://api.suppose.dev)
• SUPPOSE_ACCESS_TOKEN - Access token for authentication
• SUPPOSE_ID_TOKEN - ID token for authentication

Configuration

Configuration is stored in ~/.suppose/ directory.

CI/CD Integration

Suppose CLI is designed for CI/CD pipelines:

# Set tokens via environment variables
export SUPPOSE_ID_TOKEN="your-token"

# Analyze in CI
suppose analyze system.yaml --json --quiet

License

MIT

Support

For issues and feature requests, visit: https://github.com/suppose/suppose-cli