dagu

name	dagu
description	Authors, validates, and troubleshoots Dagu DAG definitions and assists with Dagu CLI operations. Use when creating or debugging DAG YAML, choosing Dagu commands, or inspecting and managing DAGs and runs from the CLI.

DAG Authoring

Load only the reference file that matches the task.

Default Approach

• Prefer type: graph for new DAGs. It supports both sequential flow via depends: and parallel flow.
• Use type: controller only when the step order cannot be written down in advance and an LLM must choose it. It requires llm: and a tasks: list stating when the run is finished.
• Use type: build only for local regular-file pipelines whose unchanged transformations should be reused across runs.
• Prefer id on every step. Omit name unless the display label must differ from the step ID.
• Prefer dagu schema ... and dagu validate ... over guessing field names or shapes.
• Prefer action: template.render when generating text files, prompts, or artifacts instead of assembling them with shell echo or heredocs.
• Prefer file.* actions for local file operations such as stat, read, write, copy, move, delete, mkdir, and list instead of shelling out to cp, mv, rm, or mkdir.
• Prefer git.worktree.add and git.worktree.remove when steps need isolated branches inside an existing local Git repository. Add an explicit remove step when the workflow should delete the worktree.
• Prefer stdout.artifact / stderr.artifact when a command stream should become a DAG-run artifact, especially for large reports, JSON, Markdown, logs, or generated files.
• Prefer artifact.* actions for explicit artifact reads/writes/lists. Use DAG_RUN_ARTIFACTS_DIR only when a tool truly needs a filesystem path inside the step.
• Prefer string-form output: VAR_NAME for capturing small stdout values into flat variables.
• Prefer object-form output: when downstream steps need structured values via ${step_id.output.*}.
• Prefer declared step outputs: with $DAGU_OUTPUT_FILE when a step must publish explicit values for ${steps.<step_id>.outputs.<name>}.
• Use action: human.task when an operator must provide typed input before downstream steps continue. Human task form outputs use ${steps.<step_id>.outputs.<name>} without an authored outputs: field.
• Prefer stdout.outputs or action: outputs.write when a DAG or remote action needs to return caller-visible values via ${step_id.outputs.*}.
• Prefer state.* actions for small persistent JSON state across DAG runs, such as cursors, checkpoints, and previous-value comparisons.
• Prefer temporary files in the artifacts dir only when downstream steps need file paths; otherwise let commands write large artifact content to stdout and attach it with stdout.artifact.
• Prefer scoped Dagu references for named values: ${consts.NAME}, ${params.NAME}, and ${env.NAME}. Avoid unscoped braced names in examples unless the example is intentionally showing shell syntax.
• Declare portable external CLI dependencies in top-level tools using aqua shorthand when the binary version affects reproducibility, for example tools: ["jqlang/jq@jq-1.7.1"]. Append #sha256:<64 hex> to also pin the downloaded artifact content for the run platform, for example jqlang/jq@jq-1.7.1#sha256:<hex>.
• For remote actions, put tools in the referenced action DAG file, not in dagu-action.yaml; caller DAG tools are not inherited across the action boundary.
• Use remote action packages (dagu-action.yaml) when reusable logic needs helper files, its own DAG, versioning, or an input/output schema contract.

High-Signal Rules

• output: has two modes:
  • string form captures trimmed stdout into an env-scope variable such as ${env.VERSION}
  • object form publishes structured step-scoped output for ${step_id.output.*} access
• Value declarations in step outputs: publish explicit values through ${steps.<step_id>.outputs.<name>}. Write those values to $DAGU_OUTPUT_FILE; Dagu captures them only after the command succeeds. Build path declarations publish the final materialization path after commit or reuse.
• human.task is a processless root-DAG step with an explicit id, a required with.prompt, and an optional flat scalar form. A root DAG containing one can run locally or on a distributed worker. Every declared form property is a step output, published when submitted or defaulted, and available as ${steps.<step_id>.outputs.<name>}.
• stdout.artifact / stderr.artifact store command stdout/stderr directly as relative artifact paths, for example stdout: {artifact: reports/report.md}. Artifact outputs auto-enable artifacts unless artifacts.enabled: false is explicitly set, which is invalid.
• ${step_id.stdout} is a log file path, not stdout content.
• Use ${context.*} for run metadata in DAG YAML, for example ${context.dag.name}, ${context.run.id}, or ${context.paths.artifacts_dir}. Unavailable context values remain unresolved text instead of becoming empty strings.
• In a build step, ${inputs.<name>} is the final input path and ${outputs.<name>} is a fresh attempt staging path. Write file results only to the staging path; dependencies read the committed path as ${steps.<step_id>.outputs.<name>}.
• Do not read attempt-only ${step_id.stdout}, ${step_id.stderr}, or ${step_id.exit_code} from potentially reusable producers. This also applies to ${step_id.output.<name>} and ${step_id.outputs.<name>}, including their whole-value ${step_id.output} and ${step_id.outputs} forms. Path-output steps cannot use continue_on.mark_success.
• Build workflows are local-only. Path declarations are supported only on host command or shell steps without containers, and stream redirects cannot target declared build inputs or outputs.

Example of Params, template step, and artifacts

params:
  type: object
  properties:
    name:
      type: string
      maxLength: 50
    age:
      type: integer
      minimum: 0
      maximum: 120
    favorite_color:
      type: string
  required: [name, age]

steps:
  - id: render
    action: template.render
    with:
      data:
        name: ${params.name}
        age: ${params.age}
        favorite_color: ${params.favorite_color}
      template: |
        Hello, {{ .name }}!
        You are {{ .age }} years old.
        {{- if .favorite_color }}
        Your favorite color is {{ .favorite_color }}.
        {{- end }}
    stdout:
      artifact: greeting.txt

Example of Large Command Output as Artifact

steps:
  - id: report
    run: ./generate-report --format markdown
    stdout:
      artifact: reports/report.md

Example of Reproducible External CLI

tools:
  - jqlang/jq@jq-1.7.1

steps:
  - id: inspect
    run: jq --version

Example of Object-Form Output

steps:
  - id: inspect_build
    run: echo '{"version":"v1.2.3","artifact":{"url":"https://example.test/app.tgz"}}'
    output:
      # decode + select act as a lightweight contract check:
      # malformed JSON or a missing selected field fails the step.
      version:
        from: stdout
        decode: json
        select: .version
      artifact:
        from: stdout
        decode: json
        select: .artifact

  - id: publish
    depends: [inspect_build]
    output:
      versionLabel: "ver - ${inspect_build.output.version}"
      artifactUrl: "${inspect_build.output.artifact.url}"

Example of Action Outputs

steps:
  - id: classify
    run: ./classify.sh "${params.INPUT}"
    stdout:
      outputs:
        fields:
          label:
            decode: json
            select: .label
          confidence:
            decode: json
            select: .confidence

  - id: publish
    depends: [classify]
    action: outputs.write
    with:
      values:
        label: ${classify.outputs.label}
        reviewed: false

Example of Human Input

steps:
  - id: review
    action: human.task
    with:
      prompt: Choose the deployment target
      form:
        type: object
        properties:
          environment:
            type: string
            enum: [staging, production]
          note:
            type: string
            default: ""
        required: [environment]

  - id: deploy
    depends: [review]
    run: ./deploy --environment '${steps.review.outputs.environment}' --note '${steps.review.outputs.note}'

Complete the task from a local CLI context with dagu human-task complete --run-id=<run-id> --step=review --input environment=production <dag-name>. A form is optional for acknowledgement-only tasks. Human tasks cannot be used in sub-DAGs; a distributed root run is re-queued through the scheduler after completion.

Reference Guide

Load only the file you need:

• references/steptypes.md when choosing an action or checking action-specific behavior such as human.task, dag.run, parallel, git.worktree.*, jq.filter, file.*, state.*, or template.render
• references/dagu-action.md when creating a reusable dagu-action.yaml package or checking action input/output schema behavior
• references/cli.md when choosing or using Dagu CLI commands, including workflow inspection, execution, and cleanup operations
• references/context.md when using ${context.*} metadata references or declared step outputs:
• references/build.md when creating or troubleshooting a type: build file workflow, path references, reuse decisions, or --no-reuse
• references/harnesses.md only when the DAG invokes external CLI harnesses through harness.run