Quick Start

Get up and running with Boltbase in under 2 minutes.

Install Boltbase

macOS/Linux

# Install to ~/.local/bin (default, no sudo required)
curl -L https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.sh | bash

# Install specific version
curl -L https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.sh | bash -s -- --version v1.17.0

# Install to custom directory
curl -L https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.sh | bash -s -- --install-dir /usr/local/bin

Windows

# Install latest version to default location (%LOCALAPPDATA%\Programs\boltbase)
irm https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.ps1 | iex

# Install specific version
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.ps1))) v1.24.0

Docker

docker pull ghcr.io/dagu-org/boltbase:latest

Homebrew

brew update && brew install boltbase

npm

npm install -g --ignore-scripts=false @dagu-org/boltbase

See Installation Guide for more options.

Your First Workflow

Example DAGs

When you first start Boltbase with an empty DAGs directory, it automatically creates several example workflows to help you get started:

• example-01-basic-sequential.yaml - Basic sequential execution
• example-02-parallel-execution.yaml - Parallel task execution
• example-03-complex-dependencies.yaml - Complex dependency graphs
• example-04-scheduling.yaml - Scheduled workflows
• example-05-nested-workflows.yaml - Nested sub-workflows
• example-06-container-workflow.yaml - Container-based workflows

To skip creating these examples, set BOLTBASE_SKIP_EXAMPLES=true or add skip_examples: true to your config file.

1. Create a workflow

Binary

mkdir -p ~/.config/boltbase/dags && cat > ~/.config/boltbase/dags/hello.yaml << 'EOF'
steps:
  - echo "Hello from Boltbase!"
  - echo "Running step 2"
EOF

Docker

mkdir -p ~/.boltbase/dags && cat > ~/.boltbase/dags/hello.yaml << 'EOF'
steps:
  - echo "Hello from Boltbase!"
  - echo "Running step 2"
EOF

2. Run it

Binary

Binary

boltbase start hello

Docker

docker run --rm \
  -v ~/.boltbase:/var/lib/boltbase \
  ghcr.io/dagu-org/boltbase:latest \
  boltbase start hello

Output:

┌─ DAG: hello ─────────────────────────────────────────────────────┐
│ Status: Success ✓           | Started: 23:34:57 | Elapsed: 471ms │
└──────────────────────────────────────────────────────────────────┘

Progress: ████████████████████████████████████████ 100% (2/2 steps)

Note: The output may vary if you are using Docker.

2.5. Validate (optional)

Before running, you can validate the DAG structure without executing it:

boltbase validate ~/.config/boltbase/dags/hello.yaml

If there are issues, the command prints human‑readable errors and exits with code 1.

3. Check the status

Binary

boltbase status hello

Docker

docker run --rm \
  -v ~/.boltbase:/var/lib/boltbase \
  ghcr.io/dagu-org/boltbase:latest \
  boltbase status hello

4. View Execution History

Check past runs of your workflow:

Binary

# View recent runs
boltbase history hello

# View last 50 runs
boltbase history hello --limit 50

# Export to JSON
boltbase history hello --format json

# Export to CSV
boltbase history hello --format csv

Docker

# View recent runs
docker run --rm \
  -v ~/.boltbase:/var/lib/boltbase \
  ghcr.io/dagu-org/boltbase:latest \
  boltbase history hello

The history command shows:

• Run ID (never truncated - safe to copy-paste)
• Status (succeeded, failed, running, etc.)
• Start time (UTC)
• Duration
• Parameters

For more filtering options, see the CLI reference.

5. View in the UI

Binary

boltbase start-all

Docker

docker run -d \
  -p 8080:8080 \
  -v ~/.boltbase:/var/lib/boltbase \
  ghcr.io/dagu-org/boltbase:latest \
  boltbase start-all

Open http://localhost:8080

Understanding Workflows

A workflow is a YAML file that defines steps and their dependencies:

steps:
  - command: echo "First step"
  - command: echo "Second step"  # Runs after first step automatically

Key concepts:

• Steps: Individual tasks that run commands
• Dependencies: Control execution order
• Commands: Any shell command you can run

Working Directory

By default, DAGs execute in the directory where the YAML file is located. You can override this with working_dir:

# All relative paths are resolved from working_dir
working_dir: /app/project
dotenv: .env          # Loads /app/project/.env
steps:
  - command: ls -la            # Lists files in /app/project
  - command: cat ./config.yml  # Reads /app/project/config.yml

Parameters

You can define parameters for workflows to make them reusable:

# backup.yaml
params:
  - SOURCE: /data
  - DEST: /backup
  - TS: "`date +%Y%m%d_%H%M%S`"  # Command substitution

steps:
  # Backup files
  - command: tar -czf ${DEST}/backup_${TS}.tar.gz ${SOURCE}
  # Clean old backups
  - command: find ${DEST} -name "backup_*.tar.gz" -mtime +7 -delete

Run with parameters:

boltbase start backup.yaml -- SOURCE=/important/data DEST=/backups

Error Handling

Add retries and error handlers:

steps:
  - command: curl -f https://example.com/data.zip -o data.zip
    retry_policy:
      limit: 3
      interval_sec: 30
      
  - command: echo "Unzipping data and processing"
    continue_on: failed  # Continue even if this fails (DAG ends as partially_succeeded)
      
handler_on:
  failure:
    command: echo "Workflow failed!" | mail -s "Alert" admin@example.com
  success:
    command: echo "Success at $(date)"

Using Containers

Run all steps in Docker containers:

# Using a container for all steps
container:
  image: python:3.11
  volumes:
    - ./data:/data
steps:
  # write data to a file
  - command: python -c "with open('/data/output.txt', 'w') as f: f.write('Hello from Boltbase!')"
  # read data from the file
  - command: python -c "with open('/data/output.txt') as f: print(f.read())"

Scheduling

Run workflows automatically:

schedule: "0 2 * * *"  # 2 AM daily
steps:
  - command: echo "Running nightly process"

The workflow will execute every day at 2 AM.

What's Next?

• Core Concepts - Understand Boltbase's architecture
• Writing Workflows - Learn advanced features
• Examples - Ready-to-use workflow patterns
• CLI Reference - All command options