api-reference.md

API Reference

Generated on: 2025-08-21 17:13:55 UTC

This document provides a comprehensive reference for all Runestone CLI commands and configuration options.

CLI Commands

runestone bootstrap

Initializes your Runestone environment by installing providers and validating configuration.

runestone bootstrap [flags]

Flags:

• -c, --config string - Path to configuration file (default: "infra.yaml")
• -h, --help - Help for bootstrap

Example:

runestone bootstrap --config my-infra.yaml

runestone preview

Shows what changes would be made without applying them.

runestone preview [flags]

Flags:

• -c, --config string - Path to configuration file (default: "infra.yaml")
• --json - Output results in JSON format
• -h, --help - Help for preview

Example:

runestone preview --json > changes.json

runestone commit

Applies infrastructure changes.

runestone commit [flags]

Flags:

• -c, --config string - Path to configuration file (default: "infra.yaml")
• --auto-approve - Skip interactive approval
• --graph - Show DAG visualization during execution
• -h, --help - Help for commit

Example:

runestone commit --auto-approve --graph

runestone align

Monitors and fixes infrastructure drift.

runestone align [flags]

Flags:

• -c, --config string - Path to configuration file (default: "infra.yaml")
• --once - Run alignment once instead of continuously
• --interval duration - Interval between checks (default: 5m0s)
• -h, --help - Help for align

Example:

# One-time check
runestone align --once

# Continuous monitoring every 10 minutes
runestone align --interval 10m

runestone dismantle

Destroys infrastructure resources.

runestone dismantle [flags]

Flags:

• -c, --config string - Path to configuration file (default: "infra.yaml")
• --auto-approve - Skip interactive approval
• --force - Force deletion even with dependencies
• -h, --help - Help for dismantle

Example:

runestone dismantle --auto-approve

Exit Codes

• 0 - Success
• 1 - General error
• 2 - Configuration error
• 3 - Provider error
• 4 - Resource error

Environment Variables

• AWS_PROFILE - AWS profile to use (overrides config)
• AWS_REGION - AWS region to use (overrides config)
• RUNESTONE_LOG_LEVEL - Log level (debug, info, warn, error)

JSON Output Format

When using --json flag with preview command:

{
  "summary": {
    "create": 2,
    "update": 0,
    "delete": 0,
    "total": 2
  },
  "changes": [
    {
      "type": "create",
      "resource_id": "aws:s3:bucket.my-app-logs",
      "resource_kind": "aws:s3:bucket",
      "resource_name": "my-app-logs",
      "properties": {
        "versioning": true,
        "tags": {
          "owner": "platform-team"
        }
      }
    }
  ],
  "drift": {}
}