Quick Start

Get up and running with Dagu in under 2 minutes.

Install Dagu

macOS/Linux

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

# Install specific version
curl -fsSL https://raw.githubusercontent.com/dagu-org/dagu/main/scripts/installer.sh | bash -s -- --version vX.Y.Z

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

Windows

# Open the guided installer with recommended defaults
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))) -Version vX.Y.Z

Docker

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

Homebrew

brew install dagu

npm

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

The script installers open a guided wizard. They can install Dagu, add it to your PATH, set it up as a background service, create the first admin account, and install the Dagu AI skill when a supported AI tool is detected. Homebrew, npm, and Docker remain available, but they do not include the guided setup flow.

See Installation Guide for more options.

AI-Assisted Workflow Authoring

If you use an AI coding tool (Claude Code, Codex, OpenCode, Gemini CLI, or Copilot CLI), install the Dagu skill so the AI knows how to write correct DAG YAML files.

If you installed Dagu with Homebrew, npm, or a manual binary download, run this after dagu is available on your PATH. The guided installer can offer the same step automatically.

Use Dagu's built-in installer:

dagu ai install --yes

Fallback via the shared skills CLI:

npx skills add https://github.com/dagu-org/dagu --skill dagu

For explicit skills directories, see the Installation Guide and CLI Commands.

After installation, your AI coding tool can generate, edit, and debug Dagu DAG definitions with knowledge of the full YAML schema, all 18+ executor types, CLI commands, environment variables, and common pitfalls.

Your First Workflow

Example DAGs

When you first start Dagu 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 DAGU_SKIP_EXAMPLES=true or add skip_examples: true to your config file.

1. Create a workflow

Binary

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

Docker

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

2. Run it

Binary

Binary

dagu start hello

Docker

docker run --rm \
  -v ~/.dagu:/var/lib/dagu \
  ghcr.io/dagu-org/dagu:latest \
  dagu 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:

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

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

3. Check the status

Binary

dagu status hello

Docker

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

4. View Execution History

Check past runs of your workflow:

Binary

# View recent runs
dagu history hello

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

# Export to JSON
dagu history hello --format json

# Export to CSV
dagu history hello --format csv

Docker

# View recent runs
docker run --rm \
  -v ~/.dagu:/var/lib/dagu \
  ghcr.io/dagu-org/dagu:latest \
  dagu 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

dagu start-all

Docker

docker run -d \
  -p 8080:8080 \
  -v ~/.dagu:/var/lib/dagu \
  ghcr.io/dagu-org/dagu:latest \
  dagu 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
env:
  - TS: "`date +%Y%m%d_%H%M%S`"

params:
  - name: SOURCE
    default: /data
    description: Source directory to archive
  - name: DEST
    default: /backup
    description: Destination directory for archives

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:

dagu 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" [email protected]
  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 Dagu!')"
  # 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 Dagu's architecture
• Writing Workflows - Learn advanced features
• Examples - Ready-to-use workflow patterns
• CLI Reference - All command options