Orchestr8 CLI & API Reference

Complete reference documentation for Orchestr8 commands, configuration options, and APIs.

CLI Commands

Global Options

o8 [command] [options]

Global Flags:

• --config - Path to configuration file
• --verbose - Enable verbose output
• --dry-run - Show what would be done without executing
• --help - Show help for any command

Core Commands

Setup & Bootstrap

o8 setup --provider <provider> --domain <domain>    # Initialize platform
o8 bootstrap create <provider> [options]            # Create infrastructure  
o8 bootstrap destroy <provider>                     # Destroy infrastructure
o8 doctor                                           # Validate setup

Module Management

o8 module list                                      # List available modules
o8 module install <name> [options]                 # Install module
o8 module uninstall <name>                         # Remove module
o8 module status <name>                            # Check module status
o8 module logs <name>                              # View module logs

Secrets Management

o8 secrets init --provider <provider>              # Initialize secrets
o8 secrets create <name> --data <json>             # Create secret
o8 secrets get <name>                              # Retrieve secret
o8 secrets list                                    # List all secrets
o8 secrets delete <name>                           # Delete secret

Environment Management

o8 env list                                        # List environments
o8 env create <name>                               # Create environment
o8 env switch <name>                               # Switch environment
o8 env delete <name>                               # Delete environment

Configuration Reference

Platform Configuration

The main configuration file (orchestr8.yaml) structure:

apiVersion: orchestr8.io/v1
kind: PlatformConfig
metadata:
  name: my-platform
spec:
  provider: aws                    # aws, azure, gcp, local
  domain: example.com             # Base domain for services
  cluster:
    name: orchestr8-cluster       # Cluster name
    region: us-east-1            # Cloud region
    nodeGroups:                  # Node group configuration
      - name: system
        instanceType: t3.medium
        minSize: 2
        maxSize: 5
  components:                    # Platform components
    argocd:
      enabled: true
      version: "2.8.4"
    istio:
      enabled: true
      version: "1.19.3"
    keycloak:
      enabled: true
      version: "22.0.5"
  monitoring:                    # Monitoring configuration
    prometheus:
      enabled: true
      retention: "30d"
    grafana:
      enabled: true
  secrets:                       # Secrets configuration
    provider: external-secrets
    backend: aws-secrets-manager

Module Configuration

Module specification (module.yaml) structure:

apiVersion: orchestr8.io/v1
kind: ModuleSpec
metadata:
  name: my-application
  version: "1.0.0"
  description: "Example application module"
spec:
  dependencies:                  # Module dependencies
    - name: postgresql
      version: ">=13.0.0"
  environments:                  # Environment-specific configs
    - name: development
      replicas: 1
      resources:
        requests:
          memory: "256Mi"
          cpu: "250m"
    - name: production
      replicas: 3
      resources:
        requests:
          memory: "512Mi" 
          cpu: "500m"
  networking:                    # Network configuration
    expose: true
    ports:
      - name: http
        port: 8080
        protocol: TCP
  storage:                       # Storage requirements
    - name: data
      size: "10Gi"
      accessMode: ReadWriteOnce

API Reference

REST API Endpoints

The Orchestr8 control plane exposes REST APIs for integration:

Platform Management

GET    /api/v1/platform/status          # Get platform status
POST   /api/v1/platform/components      # Install component
DELETE /api/v1/platform/components/:id  # Remove component

Module Management

GET    /api/v1/modules                  # List modules
POST   /api/v1/modules                  # Deploy module
GET    /api/v1/modules/:name            # Get module details
PUT    /api/v1/modules/:name            # Update module
DELETE /api/v1/modules/:name            # Remove module

Environment Management

GET    /api/v1/environments             # List environments
POST   /api/v1/environments             # Create environment
GET    /api/v1/environments/:name       # Get environment
DELETE /api/v1/environments/:name       # Delete environment

GraphQL API

Query and mutation examples for the GraphQL endpoint:

# Query platform status
query {
  platform {
    status
    version
    components {
      name
      status
      version
    }
  }
}

# Deploy a module
mutation {
  deployModule(
    name: "my-app"
    environment: "production"
    config: { replicas: 3 }
  ) {
    id
    status
  }
}

SDK Reference

Python SDK

from orchestr8 import O8Client

# Initialize client
client = O8Client(config_file="~/.o8/config.yaml")

# Deploy module
module = client.modules.deploy(
    name="my-app",
    environment="production",
    config={"replicas": 3}
)

# Check status
status = client.modules.get_status("my-app")
print(f"Module status: {status.phase}")

Go SDK

package main

import (
    "context"
    "github.com/orchestr8/go-sdk/pkg/client"
)

func main() {
    // Initialize client
    c := client.NewClient("~/.o8/config.yaml")
    
    // Deploy module
    module, err := c.Modules().Deploy(context.Background(), &client.DeployRequest{
        Name:        "my-app",
        Environment: "production",
        Config:      map[string]interface{}{"replicas": 3},
    })
}

Environment Variables

Variable	Description	Default
O8_CONFIG	Path to config file	~/.o8/config.yaml
O8_PROVIDER	Default cloud provider	local
O8_ENVIRONMENT	Default environment	development
O8_LOG_LEVEL	Log level (debug, info, warn, error)	info
O8_KUBECONFIG	Path to kubeconfig file	~/.kube/config

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Authentication error
4	Resource not found
5	Permission denied

Examples

See the complete CLI examples in the repository for more detailed usage patterns.