CLI Reference: Command-Line Interface

# Install from repository
git clone https://github.com/cascade-platform/cascade.git
cd cascade
make install
 
# Or with binary
curl -sSL https://releases.cascade.io/install.sh | bash
 
# Verify installation
cascade version
# cascade version v1.0.0 (commit: abc123, built: 2025-10-29)

cascade [OPTIONS] COMMAND [ARGS]
 
OPTIONS:
  --config FILE              Config file path (default: ~/.cascade/config.yaml)
  --namespace NS             Namespace (default: default)
  --output FORMAT            Output format: json, table, yaml (default: table)
  --debug                    Enable debug logging
  --json                     Output as JSON (shorthand for --output json)
  --help, -h                 Show help
  --version, -v              Show version

# Deploy app from file
cascade app apply -f loan-application.cdl.yaml
 
# Deploy with manifest
cascade app apply -f app-manifest.json --namespace production
 
# Validate without deploying
cascade app apply -f app.yaml --dry-run
 
# Output
Application "loan-application" deployed (v1.0.0)
├─ Workflows: 3
├─ Activities: 12
├─ Policies: 5
└─ Schemas: 8

cascade app apply [options]
  -f, --file FILE            Application file (required)
  --namespace NS             Target namespace
  --dry-run                  Validate only, don't deploy
  --wait                     Wait for deployment to complete
  --timeout DURATION         Deployment timeout (default: 5m)
  --force                    Force redeploy (skip validation)

# List applications in current namespace
cascade app list
 
# Output (table format)
NAME                    VERSION    STATUS      WORKFLOWS    ACTIVITIES
loan-application        v1.0.0     healthy     3            12
insurance-claims        v2.1.0     healthy     8            25
expense-approval        v1.5.0     healthy     2            7
 
# List all namespaces
cascade app list --all-namespaces
 
# JSON output
cascade app list --json
[
  {
    "name": "loan-application",
    "version": "v1.0.0",
    "status": "healthy",
    "workflows": 3,
    "deployed_at": "2025-10-29T10:00:00Z"
  }
]
 
# Watch in real-time
cascade app list --watch

# Delete application
cascade app delete loan-application
 
# Confirm deletion
cascade app delete loan-application --confirm
 
# Delete all workflows (keep app structure)
cascade app delete loan-application --workflows-only
 
# Timeout
cascade app delete loan-application --timeout 2m

# Inspect application
cascade app inspect loan-application
 
# Output
Application: loan-application
├─ Version: v1.0.0
├─ Status: healthy
├─ Deployed: 2025-10-29 10:00:00 UTC
├─ Namespace: default
│
├─ Workflows (3)
│ ├─ ProcessLoan
│ ├─ EvaluatePolicy
│ └─ SendNotification
│
├─ Activities (12)
│ ├─ validate_application
│ ├─ check_credit
│ ├─ evaluate_policy
│ └─ ...
│
├─ Policies (5)
│ ├─ urn:cascade:policy:approval_rules
│ ├─ urn:cascade:policy:compliance_checks
│ └─ ...
│
└─ Schemas (8)
  ├─ urn:cascade:schema:loan_application
  └─ ...
 
# Get specific section
cascade app inspect loan-application --workflows
cascade app inspect loan-application --activities
cascade app inspect loan-application --policies

# Start workflow with input
cascade process start \
  --app loan-application \
  --workflow ProcessLoan \
  --input '{"amount": 50000, "applicant_id": "alice"}'
 
# Output
Workflow started successfully
├─ Process ID: wf-abc123def456
├─ Workflow: ProcessLoan
├─ Status: running
├─ Started: 2025-10-29T15:23:45Z
└─ First state: ReceiveApplication
 
# Read input from file
cascade process start \
  --app loan-application \
  --workflow ProcessLoan \
  --input-file loan-input.json
 
# With timeout
cascade process start \
  --app loan-application \
  --workflow ProcessLoan \
  --input '{"amount": 50000}' \
  --timeout 30m
 
# Get process ID only (for automation)
cascade process start \
  --app loan-application \
  --workflow ProcessLoan \
  --input '{}' \
  --quiet
# wf-abc123def456

# List all running processes
cascade process list
 
# Output
ID                          APP                   WORKFLOW            STATUS        STARTED
wf-abc123def456             loan-application      ProcessLoan         running       10 mins ago
wf-xyz789qwe012             loan-application      ProcessLoan         completed     2 hours ago
wf-qwe345rty678             insurance-claims      EvaluateClaim       waiting       1 hour ago
 
# List with filters
cascade process list --status running
cascade process list --app loan-application
cascade process list --workflow ProcessLoan
cascade process list --status completed --since 24h
 
# Show more details
cascade process list --details
# Shows: state, progress, error (if any)
 
# JSON output
cascade process list --json
cascade process list --app loan-application --json | jq '.[] | select(.status=="waiting")'

# Inspect process
cascade process inspect wf-abc123def456
 
# Output
Process: wf-abc123def456
├─ Workflow: ProcessLoan (loan-application)
├─ Status: waiting
├─ Started: 2025-10-29T15:23:45Z
├─ Duration: 10 minutes
│
├─ Current State: ManagerApproval (HumanTask)
│ ├─ Entered: 2025-10-29T15:30:00Z
│ ├─ Timeout: 24h
│ ├─ Assignee: role:loan_manager
│ └─ Awaiting: User approval
│
├─ Execution History
│ ├─ ReceiveApplication (Task) ✅ 30ms
│ ├─ ValidateLoan (Task) ✅ 120ms
│ ├─ EvaluatePolicy (EvaluatePolicy) ✅ 15ms
│ ├─ RouteByAmount (Choice) ✅ 2ms
│ └─ ManagerApproval (HumanTask) ⏳ 10m running
│
├─ Context Variables (10)
│ ├─ applicant_id: alice
│ ├─ loan_amount: 50000
│ ├─ credit_score: 720
│ └─ ...
│
└─ Errors: None

# Approve and resume workflow
cascade process signal wf-abc123def456 \
  --action approve \
  --data '{"approved_by": "manager@company.com", "notes": "Looks good"}'
 
# Reject workflow
cascade process signal wf-abc123def456 \
  --action reject \
  --data '{"reason": "Credit score too low"}'
 
# Generic signal
cascade process signal wf-abc123def456 \
  --signal-name payment_received \
  --data '{"amount": 50000, "reference": "TXN123"}'
 
# Show available actions
cascade process signal wf-abc123def456 --list-actions
# Actions for ManagerApproval (HumanTask):
# - approve
# - reject
# - request_more_info

# Cancel workflow
cascade process cancel wf-abc123def456
 
# Cancel with reason
cascade process cancel wf-abc123def456 --reason "User requested cancellation"
 
# Force cancel (don't wait for cleanup)
cascade process cancel wf-abc123def456 --force
 
# Output
Process wf-abc123def456 cancelled successfully
├─ Status changed: running → cancelled
├─ Last state: ManagerApproval
└─ Cancelled at: 2025-10-29T15:35:20Z

# Retry entire workflow
cascade process retry wf-abc123def456
 
# Retry from specific state
cascade process retry wf-abc123def456 --from-state EvaluatePolicy
 
# Retry with updated input
cascade process retry wf-abc123def456 --input '{"credit_score": 750}'
 
# Output
Process retry initiated
├─ New Process ID: wf-new789abc123
├─ Original Process: wf-abc123def456
├─ Retry From: EvaluatePolicy
└─ Status: running

# Show logs for process
cascade logs wf-abc123def456
 
# Output
[15:23:45.123] ReceiveApplication: starting
[15:23:45.200] ReceiveApplication: activity execute (validate_application)
[15:23:45.230] ReceiveApplication: ✅ completed in 30ms
[15:23:45.231] ValidateLoan: starting
[15:23:45.301] ValidateLoan: activity execute (check_credit)
[15:23:45.351] ValidateLoan: ✅ completed in 120ms
[15:30:00.000] ManagerApproval: starting (HumanTask)
[15:30:00.010] ManagerApproval: ⏳ waiting for user input
 
# With filters
cascade logs wf-abc123def456 --level error  # Only errors
cascade logs wf-abc123def456 --grep "policy"  # Search logs
cascade logs wf-abc123def456 --tail 50  # Last 50 lines
 
# Follow logs in real-time
cascade logs wf-abc123def456 --follow

# View execution trace
cascade trace wf-abc123def456
 
# Output (tree format)
ProcessLoan (0-10010ms)
├─ ReceiveApplication (0-30ms) ✅
│  └─ validate_application (5-30ms) ✅
│      └─ External API call (10-25ms) ✅
├─ ValidateLoan (30-150ms) ✅
│  └─ check_credit (35-150ms) ✅
│      └─ Credit Bureau API (40-145ms) ✅
├─ EvaluatePolicy (150-165ms) ✅
│  └─ OPA evaluation (152-164ms) ✅
│      └─ Policy exec (153-163ms) ✅
├─ RouteByAmount (165-167ms) ✅
│  └─ Choice evaluation (165-167ms) ✅
└─ ManagerApproval (167-10010ms) ⏳
   └─ Awaiting user input (167-10010ms) ⏳
 
# Export as JSON
cascade trace wf-abc123def456 --json > trace.json
 
# View with metrics
cascade trace wf-abc123def456 --metrics
# Shows: min, max, avg latency per operation

# View metrics
cascade metrics wf-abc123def456
 
# Output
Performance Metrics
├─ Total Duration: 10m 5s
├─ State Count: 8
├─ Activities: 5
├─ Average Activity Latency: 85ms
│
├─ Slowest Operations
│ ├─ ManagerApproval: 9m 50s ⏳
│ ├─ check_credit: 120ms ✅
│ ├─ evaluate_policy: 15ms ✅
│ └─ validate_application: 30ms ✅
│
└─ Error Rate: 0%
 
# Compare multiple workflows
cascade metrics wf-abc123def456 wf-xyz789qwe012

# Get specific value
cascade config get namespace
 
# Get all config
cascade config get
 
# Output
namespace: default
api_server: http://localhost:8000
temporal_server: localhost:7233
postgres_host: localhost
postgres_port: 5432
debug: false
output_format: table
 
# Get nested value
cascade config get postgres.host

# Set namespace
cascade config set namespace production
 
# Set multiple values
cascade config set \
  api_server https://api.cascade.io \
  output_format json
 
# Save to config file
cascade config set debug true --save

# List schemas
cascade schema list
 
# Output
URN                                              VERSION    TYPE
urn:cascade:schema:loan_application              v1.0.0     application
urn:cascade:schema:loan_approval_form            v1.0.0     form
urn:cascade:schema:financial_information         v2.0.0     object
urn:cascade:schema:customer_database             v1.5.0     database
 
# Filter by application
cascade schema list --app loan-application

# View schema
cascade schema inspect urn:cascade:schema:loan_application
 
# Output
Schema: urn:cascade:schema:loan_application
├─ Version: v1.0.0
├─ Type: object
├─ Properties: 15
│
├─ applicant_name (string, required)
├─ email (string, required, format: email)
├─ loan_amount (number, required, min: 1000, max: 1000000)
├─ loan_purpose (string, required, enum: [...])
└─ ...
 
# Get as JSON
cascade schema inspect urn:cascade:schema:loan_application --json

# List policies
cascade policy list
 
# Output
NAME                                ENGINE    STATUS    LAST_TESTED
loan_approval_rules                 opa       healthy   2h ago
claim_decision_table                dmn       healthy   1d ago
compliance_checks                   opa       healthy   now
 
# With stats
cascade policy list --stats
# Shows: eval count, avg latency, error rate

# Test policy
cascade policy test urn:cascade:policy:loan_approval \
  --input '{"credit_score": 720, "amount": 50000}'
 
# Output
Policy: loan_approval
├─ Engine: opa
├─ Status: ✅ Success
├─ Duration: 3.2ms
│
├─ Rules Evaluated
│ ├─ allow_approval: true
│ ├─ deny_approval: false
│ └─ require_manager_review: false
│
└─ Result
  ├─ approved: true
  ├─ reason: "Credit score acceptable"
  └─ confidence: 0.95

# Show trace
cascade policy trace urn:cascade:policy:loan_approval \
  --input '{"credit_score": 720}'
 
# Output
Tracing: loan_approval (OPA)
├─ allow_approval: ✅ true
│  └─ Matched rules:
│     ├─ credit_score >= 700: true
│     └─ amount <= 100000: true
├─ deny_approval: ✅ false
│  └─ No matching rules
└─ Duration: 3.2ms

# List activities
cascade activity list
 
# Output
URN                                         APP                 STATUS
urn:cascade:activity:validate_application   loan-application    registered
urn:cascade:activity:check_credit           loan-application    registered
urn:cascade:activity:send_email             loan-application    healthy
 
# Show with stats
cascade activity list --stats
# activity_count, total_executions, avg_duration, error_rate

# Show activity logs
cascade activity logs urn:cascade:activity:check_credit \
  --since 24h
 
# Output
[2025-10-29 14:23:45] Process wf-abc123: ✅ 120ms
[2025-10-29 13:15:20] Process wf-xyz789: ✅ 115ms
[2025-10-29 12:40:30] Process wf-qwe345: ❌ 5000ms (timeout)
 
# With filtering
cascade activity logs urn:cascade:activity:check_credit \
  --status failed \
  --since 7d

# Deploy to production
cascade deploy \
  --app loan-application \
  --target kubernetes \
  --namespace production
 
# Deploy with Docker
cascade deploy \
  --app loan-application \
  --target docker \
  --image my-org/loan-app:latest
 
# Check deployment status
cascade deploy status --app loan-application --target kubernetes

# Check all services
cascade health
 
# Output
Cascade Platform Health Check
├─ API Server: ✅ healthy
├─ Temporal: ✅ healthy
├─ PostgreSQL: ✅ healthy (99.9% uptime)
├─ Redis: ✅ healthy
├─ NATS: ✅ healthy
├─ OPA: ✅ healthy
├─ SpiceDB: ✅ healthy
└─ Overall: ✅ healthy
 
# Check specific service
cascade health temporal
cascade health postgres

# Create backup
cascade backup create --app loan-application
 
# Output
Backup created successfully
├─ Backup ID: backup-20251029-152345
├─ App: loan-application
├─ Size: 2.5GB
├─ Location: s3://backups/cascade/backup-20251029-152345
└─ Duration: 45 seconds
 
# Restore backup
cascade backup restore backup-20251029-152345
 
# List backups
cascade backup list --app loan-application

# Start dev environment
cascade dev up
 
# Output
Starting Cascade Platform development environment...
├─ PostgreSQL 16: ✅ healthy (port 5432)
├─ Redis 8: ✅ healthy (port 6379)
├─ Temporal: ✅ healthy (port 7233)
├─ NATS: ✅ healthy (port 4222)
├─ Ory Kratos: ✅ healthy (port 4433)
├─ SpiceDB: ✅ healthy (port 8443)
├─ Grafana: ✅ ready (http://localhost:3000)
│
✅ All services ready in 15 seconds
 
# Stop dev environment
cascade dev down
 
# View logs
cascade dev logs
cascade dev logs postgres
cascade dev logs --follow

# Watch current directory
cascade watch
 
# Watches: *.cdl.yaml, *.yaml, *.go files
# On change: validates, recompiles, reloads
 
# Watch specific directory
cascade watch ./workflows
 
# Output
Watching: /path/to/workflows
[14:23:45] Detected: loan-application.cdl.yaml (modified)
[14:23:46] Validating...
[14:23:47] ✅ Valid
[14:23:48] Reloading application...
[14:23:49] ✅ Application reloaded successfully

# Run all tests
cascade test
 
# Output
Testing loan-application
├─ Test: ApprovalFlow (✅ passed)
│  ├─ Input: {amount: 50000, score: 720}
│  ├─ Expected end state: Approved
│  ├─ Duration: 250ms
│  └─ ✅ Passed
├─ Test: RejectionFlow (✅ passed)
├─ Test: TimeoutHandling (✅ passed)
└─ Summary: 3/3 tests passed (95% coverage)
 
# Run specific test
cascade test --name ApprovalFlow
 
# Generate coverage report
cascade test --coverage

cascade app list
 
# Output
NAME                    VERSION    STATUS      WORKFLOWS
loan-application        v1.0.0     healthy     3
insurance-claims        v2.1.0     healthy     8

cascade app list --json
 
# Output
[
  {
    "name": "loan-application",
    "version": "v1.0.0",
    "status": "healthy",
    "workflows": 3,
    "deployed_at": "2025-10-29T10:00:00Z"
  }
]

cascade app list --output yaml
 
# Output
applications:
  - name: loan-application
    version: v1.0.0
    status: healthy
    workflows: 3
    deployed_at: 2025-10-29T10:00:00Z

# Get process ID for automation
PID=$(cascade process start \
  --app loan-application \
  --workflow ProcessLoan \
  --input '{}' \
  --quiet)
 
echo "Started process: $PID"
 
# Wait for completion
cascade process inspect $PID --wait
 
# Get result
cascade process inspect $PID --json | jq '.result'

# Find all failed processes in last day
cascade process list --since 24h --status failed --json | \
  jq '.[] | select(.error != null)' | \
  wc -l
 
# Export all workflow traces
cascade process list --app loan-application --json | \
  jq '.[].id' | \
  xargs -I {} cascade trace {} --json > traces.jsonl

# Watch process status
watch -n 2 'cascade process inspect wf-abc123def456 --json | jq "{status, current_state, duration}"'
 
# Monitor all running processes
watch 'cascade process list --status running'
 
# Check system health every 30s
watch -n 30 'cascade health'

# Use environment variables for configuration
export CASCADE_NAMESPACE=production
export CASCADE_API_SERVER=https://api.cascade.io
export CASCADE_OUTPUT_FORMAT=json
export CASCADE_DEBUG=true
 
# All commands will use these values
cascade app list

# Check if services are running
cascade health
 
# Start dev environment
cascade dev up

# List available applications
cascade app list
 
# Check namespace
cascade config get namespace
cascade config set namespace production

# List processes
cascade process list
 
# Use correct ID format
cascade process inspect wf-abc123def456