Dagu workflow orchestration: workflow authoring, web UI, and REST API

version
0.1.10
GitHub stars
27

Install

/plugin install dagu@vinnie357

Run it inside Claude Code after adding the marketplace with /plugin marketplace add vinnie357/claude-skills.

Contents

Discovered from source

Skills 3

Dagu REST API

Use this skill when integrating Dagu with external systems, automating workflow operations, or programmatically managing workflows through the API.

Core API Capabilities

The Dagu REST API provides endpoints for:

  1. Workflow Operations - Start, stop, retry workflows
  2. Status Queries - Get workflow and execution status
  3. DAG Management - List and inspect workflow definitions
  4. Execution History - Query past executions
  5. Log Retrieval - Fetch execution logs

Base URL

Default API base URL: http://localhost:8080/api/v1

Configure in Dagu settings if using a different host/port.

Quick Start Operations

Start a Workflow

POST /dags/{dagName}/start

Basic example:

curl -X POST http://localhost:8080/api/v1/dags/my_workflow/start

For parameter passing and advanced options, see references/api-endpoints.md.

Get Workflow Status

GET /dags/{dagName}/status

Returns current status, running steps, and execution details.

Stop a Workflow

POST /dags/{dagName}/stop

Stops currently running execution.

When to Consult References

Read references/api-endpoints.md for the complete endpoint reference: workflow operations (start/stop/retry/restart), status and history queries, log retrieval, DAG management, response schemas, HTTP status codes, and the error response format.

Common Use Cases

CI/CD Integration

Trigger Dagu workflows from your CI/CD pipeline:

# In GitHub Actions, GitLab CI, etc.
curl -X POST http://dagu-server:8080/api/v1/dags/deploy_production/start \
  -H "Content-Type: application/json" \
  -d '{"params": "VERSION=1.2.3 ENVIRONMENT=production"}'

Monitoring and Alerting

Query workflow status for external monitoring:

# Check if workflow is running
curl http://localhost:8080/api/v1/dags/critical_job/status

Build custom alerts based on status responses. See references/api-endpoints.md for response format details.

Dynamic Scheduling

Trigger workflows based on external events:

import requests

def trigger_workflow(dag_name, params=None):
    url = f"http://localhost:8080/api/v1/dags/{dag_name}/start"
    data = {"params": params} if params else {}
    response = requests.post(url, json=data)
    return response.json()

Response Formats

All API responses are JSON. Common response structure:

{
  "status": "success",
  "data": { ... }
}

Error responses:

{
  "status": "error",
  "message": "Error description"
}

For complete response schemas, consult references/api-endpoints.md.

Key Principles

  • RESTful design: Standard HTTP methods (GET, POST, DELETE)
  • JSON responses: All responses in JSON format
  • Idempotent operations: Safe to retry most operations
  • Error codes: Standard HTTP status codes
  • Stateless: Each request is independent

Pro Tips

  • Use the API for automation, use Web UI for manual operations
  • Implement retry logic for network failures
  • Cache DAG lists if querying frequently
  • Use webhooks for event-driven workflows when possible
  • Monitor API response times for performance issues
  • Validate workflow names before calling API to avoid errors

Dagu Web UI

Use this skill when working with Dagu's web interface to manage workflows, view execution history, monitor running workflows, or configure the UI.

Core Capabilities

The Dagu Web UI provides:

  1. Workflow Management - View, start, stop, and manage workflows
  2. Execution Monitoring - Real-time status and logs
  3. History Viewing - Past execution records and results
  4. DAG Visualization - Visual representation of workflow structure
  5. Log Access - View detailed execution logs
  6. Schedule Management - Configure when workflows run

Quick Start

Access Dagu Web UI at http://localhost:8080 (default) after starting Dagu:

dagu server

Primary Operations

Start a Workflow

To manually execute a workflow:

  1. Navigate to workflow list
  2. Click the workflow name
  3. Click "Start" button
  4. View real-time execution progress

Monitor Execution

For detailed information on a running workflow, consult references/monitoring.md which covers:

  • Reading execution logs
  • Understanding status indicators
  • Tracking step progress
  • Identifying failures

View History

Execution history is not unconditionally preserved — the REST API supports deleting individual records (DELETE /dags/{dagName}/history/{requestId}, see /dagu:rest-api references/api-endpoints.md "Delete Execution History"). Open a workflow's history to review past runs, find failed executions, and retry them (see Common Tasks).

Workflow Visualization

The DAG view shows workflow structure. Click step names in the DAG view for step-specific details.

When to Consult References

Read references/monitoring.md for execution status indicators, real-time log viewing, progress tracking, error detection, and troubleshooting stuck workflows.

Common Tasks

Restart a Failed Workflow

  1. Find the failed execution in history
  2. Click the retry/restart button
  3. Monitor the new execution

Stop a Running Workflow

  1. Navigate to the running workflow
  2. Click "Stop" or "Cancel"
  3. Confirm the action
  4. View cleanup handlers execution

View Detailed Logs

When you need to debug a workflow:

  1. Click on the specific workflow execution
  2. Select the step with issues
  3. View stdout/stderr logs
  4. Check for error messages

For advanced log analysis, consult references/monitoring.md.

Key Principles

  • Real-time visibility: Web UI provides live updates of workflow execution
  • Click-based operations: No CLI needed for basic workflow management
  • History preservation: Executions are logged and accessible; individual records can be deleted via the REST API
  • Visual feedback: Status indicators show current state at a glance
  • Log accessibility: Detailed logs available for debugging

Pro Tips

  • Use the search feature to quickly find workflows by name
  • Filter execution history by date range or status
  • Click on step names in DAG view for step-specific details
  • Use the refresh button if live updates seem delayed
  • Check the scheduler status to verify cron jobs are active

Dagu Workflow Authoring

This skill activates when creating or modifying Dagu workflow definitions, configuring workflow steps, scheduling, or composing complex workflows.

Basic Workflow Structure

Minimal Workflow

# hello.yaml
steps:
  - name: hello
    command: echo "Hello from Dagu!"

Complete Workflow Structure

name: my_workflow
description: Description of what this workflow does

# Schedule (optional)
schedule: "0 2 * * *"  # Cron format: daily at 2 AM

# Environment variables
env:
  - KEY: value
  - DB_HOST: localhost

# Parameters
params: ENVIRONMENT=production

# Email notifications (optional)
mailOn:
  failure: true
  success: false

smtp:
  host: smtp.example.com
  port: 587

errorMail:
  from: dagu@example.com
  to: alerts@example.com

# Workflow steps
steps:
  - name: step1
    command: echo "First step"

  - name: step2
    command: echo "Second step"
    depends:
      - step1

Steps

Basic Step

steps:
  - name: greet
    command: echo "Hello, World!"

Step with Script

steps:
  - name: process
    command: |
      echo "Starting processing..."
      ./scripts/process.sh
      echo "Done!"

Step with Working Directory

steps:
  - name: build
    dir: /path/to/project
    command: make build

Step with Environment Variables

steps:
  - name: deploy
    env:
      - ENVIRONMENT: production
      - API_KEY: $API_KEY  # From global env
    command: ./deploy.sh

Executors

Command (default), Docker, SSH, HTTP, Mail, and JQ executor configuration: see references/executors.md.

Gotcha: the default executor (no executor: block) is the Command Executor — set executor.type only when a step needs Docker, SSH, HTTP, Mail, or JQ.

Step Dependencies

Simple, multiple, and parallel dependency patterns via depends:: see references/steps-and-flow.md.

Gotcha: steps with no depends: run in parallel by default — sequencing is opt-in.

Conditional Execution

Preconditions

steps:
  - name: deploy_production
    preconditions:
      - condition: "`echo $ENVIRONMENT`"
        expected: "production"
    command: ./deploy.sh

Continue On Failure

steps:
  - name: optional_step
    continueOn:
      failure: true
    command: ./might_fail.sh

  - name: cleanup
    depends:
      - optional_step
    command: ./cleanup.sh  # Runs even if optional_step fails

Error Handling and Retries

Retry Configuration

steps:
  - name: flaky_api_call
    command: curl https://api.example.com/data
    retryPolicy:
      limit: 3
      intervalSec: 10

Exponential Backoff

steps:
  - name: with_backoff
    command: ./external_api.sh
    retryPolicy:
      limit: 5
      intervalSec: 5
      exponentialBackoff: true  # 5s, 10s, 20s, 40s, 80s

Signal on Stop

steps:
  - name: graceful_shutdown
    command: ./long_running_process.sh
    signalOnStop: SIGTERM  # Send SIGTERM instead of SIGKILL

Data Flow

Passing step output to later steps via output: and captured script: variables: see references/steps-and-flow.md.

Scheduling

Cron Schedule

# Daily at 2 AM
schedule: "0 2 * * *"

# Every Monday at 9 AM
schedule: "0 9 * * 1"

# Every 15 minutes
schedule: "*/15 * * * *"

# First day of month at midnight
schedule: "0 0 1 * *"

Start/Stop Times

# Only run during business hours
schedule:
  start: "2024-01-01"
  end: "2024-12-31"
  cron: "0 9-17 * * 1-5"  # Mon-Fri, 9 AM to 5 PM

Environment Variables

Global, step-level, and file-loaded (.env) environment variables: see references/steps-and-flow.md.

Parameters

Defining workflow params: and overriding them from the CLI: see references/steps-and-flow.md.

Sub-Workflows

Calling and nesting sub-workflows with run:: see references/steps-and-flow.md.

Handlers

Exit, failure, and success handlers via handlerOn:: see references/steps-and-flow.md.

Gotcha: handlerOn is declared once per workflow, alongside steps: — it is not nested inside an individual step.

Templates and Variables

Built-in ({{.Name}}, {{.Step.Name}}, {{.timestamp}}, {{.requestId}}) and custom params:-backed templates: see references/steps-and-flow.md.

Gotcha: custom parameters are referenced as {{.Params.NAME}}, not bare {{.NAME}} — the bare form is reserved for built-ins.

Common Patterns

Complete ETL pipeline, multi-environment deployment, database backup, and health-check monitoring workflow artifacts: see references/common-patterns.md.

Best Practices

Workflow Organization

# Good: Clear, descriptive names
name: user_data_sync
description: Synchronize user data from CRM to database

# Good: Logical step names
steps:
  - name: fetch_from_crm
  - name: validate_data
  - name: update_database

# Avoid: Generic names
name: workflow1
steps:
  - name: step1
  - name: step2

Error Handling

# Always define error handlers for critical workflows
handlerOn:
  failure:
    - name: cleanup
      command: ./cleanup.sh
    - name: notify
      executor:
        type: mail
        config:
          to: team@example.com

# Use retries for flaky operations
steps:
  - name: api_call
    command: curl https://api.example.com
    retryPolicy:
      limit: 3
      intervalSec: 5
      exponentialBackoff: true

Environment Management

# Use parameters for environment-specific values
params: ENVIRONMENT=development

# Load environment from files
env:
  - config/$ENVIRONMENT.env

# Override in production
# dagu start workflow.yaml ENVIRONMENT=production

Modular Workflows

# Break complex workflows into sub-workflows
steps:
  - name: data_ingestion
    run: workflows/ingestion.yaml

  - name: data_transformation
    run: workflows/transformation.yaml
    depends:
      - data_ingestion

Key Principles

  • Keep workflows focused: One workflow per logical task
  • Use dependencies wisely: Parallelize when possible
  • Handle errors explicitly: Define failure handlers
  • Use retries for flaky operations: Network calls, external APIs
  • Parameterize configurations: Make workflows reusable
  • Document workflows: Add clear names and descriptions
  • Test workflows: Start with small, focused workflows
  • Monitor and alert: Use handlers to track workflow health

References

  • references/executors.md — Command (default), Docker, SSH, HTTP, Mail, and JQ executor configuration
  • references/steps-and-flow.md — step dependencies, data flow, environment variables, parameters, sub-workflows, handlers, templating
  • references/common-patterns.md — complete ETL, multi-environment deployment, backup, and monitoring workflow artifacts

Sponsors

Details

Marketplace
vinnie357/claude-skills
Source
plugins/tools/dagu
Category
Tools
Keywords
dagu, workflow, orchestration, automation

More from vinnie357/claude-skills

All 33