Skip to content

๐Ÿ—‚๏ธ Stack Management

Sloth Runner provides a complete stack management system similar to Pulumi, allowing you to persist workflow state and track executions over time.

๐Ÿš€ Introduction

Stack Management in Sloth Runner enables:

  • Persist state between executions
  • Track outputs exported from pipeline
  • Complete history of executions
  • Intuitive CLI management
  • Isolation by environment/project

๐Ÿ“ Basic Syntax

Running with Stack

# New syntax - stack name as positional argument
sloth-runner run {stack-name} --file workflow.sloth

# Practical examples
sloth-runner run production-app -f deploy.sloth --output enhanced
sloth-runner run dev-environment -f test.sloth -o rich
sloth-runner run my-cicd -f pipeline.sloth

Managing Stacks

# List all stacks
sloth-runner stack list

# Show stack details
sloth-runner stack show production-app

# Delete stack
sloth-runner stack delete old-environment

๐ŸŽฏ Core Concepts

Stack State

Each stack maintains:

  • Unique ID (UUID)
  • Stack name
  • Current status (created, running, completed, failed)
  • Exported outputs from pipeline
  • Execution history
  • Metadata and configurations

Lifecycle

  1. Creation: Stack is automatically created on first execution
  2. Execution: State is updated during execution
  3. Persistence: Outputs and results are saved
  4. Reuse: Subsequent executions reuse the stack

๐Ÿ’พ State Persistence

Database

Sloth Runner uses SQLite to persist state:

~/.sloth-runner/stacks.db

Tables

  • stacks: Main stack information
  • stack_executions: Detailed execution history

๐Ÿ“Š Exported Outputs

Automatic Capture

The system automatically captures:

  • TaskRunner exports (runner.Exports)
  • Global outputs variable from Lua
  • Execution metadata

Export Example

local deploy_task = task("deploy")
    :command(function(params, deps)
        -- Deploy logic...

        -- Export outputs to stack
        runner.Export({
            app_url = "https://myapp.example.com",
            version = "1.2.3",
            environment = "production",
            deployed_at = os.date()
        })

        return true, "Deploy successful", deploy_info
    end)
    :build()

๐Ÿ–ฅ๏ธ CLI Interface

Stack List

$ sloth-runner stack list

Workflow Stacks     

NAME                  STATUS     LAST RUN           DURATION     EXECUTIONS
----                  ------     --------           --------     ----------
production-app        completed  2025-09-29 19:27   6.8s         5
dev-environment       running    2025-09-29 19:25   2.1s         12
staging-api           failed     2025-09-29 19:20   4.2s         3

Stack Details

$ sloth-runner stack show production-app

Stack: production-app     

ID: abc123-def456-789
Status: completed
Created: 2025-09-29 15:30:21
Updated: 2025-09-29 19:27:15
Executions: 5
Last Duration: 6.8s

     Outputs     

app_url: "https://myapp.example.com"
version: "1.2.3"
environment: "production"
deployed_at: "2025-09-29 19:27:15"

     Recent Executions     

STARTED            STATUS     DURATION   TASKS   SUCCESS   FAILED
-------            ------     --------   -----   -------   ------
2025-09-29 19:27   completed  6.8s       3       3         0
2025-09-29 18:45   completed  7.2s       3       3         0
2025-09-29 17:30   failed     4.1s       3       2         1

๐ŸŽจ Output Styles

Configurable per Execution

# Basic output (default)
sloth-runner run my-stack -f workflow.sloth

# Enhanced output
sloth-runner run my-stack -f workflow.sloth --output enhanced
sloth-runner run my-stack -f workflow.sloth -o rich
sloth-runner run my-stack -f workflow.sloth --output modern

Pulumi Style

The enhanced output provides rich formatting similar to Pulumi:

๐Ÿฆฅ Sloth Runner

     Workflow: production-app     

Started at: 2025-09-29 19:27:15

โœ“ build (2.1s) completed
โœ“ test (3.2s) completed  
โœ“ deploy (1.5s) completed

     Workflow Completed Successfully     

โœ“ production-app
Duration: 6.8s
Tasks executed: 3

     Outputs     

โ”œโ”€ exports:
  โ”‚ app_url: "https://myapp.example.com"
  โ”‚ version: "1.2.3"
  โ”‚ environment: "production"

๐Ÿ”ง Use Cases

Separate Environments

# Development
sloth-runner run dev-app -f app.sloth

# Staging  
sloth-runner run staging-app -f app.sloth

# Production
sloth-runner run prod-app -f app.sloth --output enhanced

CI/CD Integration

# In CI/CD pipeline
sloth-runner run ${ENVIRONMENT}-${APP_NAME} -f pipeline.sloth

# Examples:
sloth-runner run prod-frontend -f frontend-deploy.sloth
sloth-runner run staging-api -f api-deploy.sloth

Monitoring

# View status of all environments
sloth-runner stack list

# Check last production deployment
sloth-runner stack show prod-app

# Clean up test environments
sloth-runner stack delete temp-test-env

๐Ÿ› ๏ธ Best Practices

Stack Naming

# Use pattern: {environment}-{application}
sloth-runner run prod-frontend -f deploy.sloth
sloth-runner run staging-api -f deploy.sloth
sloth-runner run dev-database -f setup.sloth

Output Exports

-- Export relevant information
runner.Export({
    -- Important URLs
    app_url = deploy_info.url,
    admin_url = deploy_info.admin_url,

    -- Version information
    version = build_info.version,
    commit_hash = build_info.commit,

    -- Environment settings
    environment = config.environment,
    region = config.region,

    -- Timestamps
    deployed_at = os.date(),
    build_time = build_info.timestamp
})

Lifecycle Management

# Active development
sloth-runner run dev-app -f app.sloth

# When ready for staging
sloth-runner run staging-app -f app.sloth

# Deploy to production
sloth-runner run prod-app -f app.sloth --output enhanced

# Clean up old environments
sloth-runner stack delete old-test-branch

๐Ÿ”„ Migration

Old vs New Commands

# Before
sloth-runner run -f workflow.sloth --stack my-stack

# Now
sloth-runner run my-stack -f workflow.sloth

Compatibility

  • Existing workflows continue to work
  • Stack is optional - can run without specifying
  • Outputs are captured automatically when stack is used

๐Ÿ“š Next Steps