Reference

dibbla-task.yaml schema

The setup-pipeline format run by dibbla run — its three step types, the tools map, the env and ports declarations, and why a URL-fetched task file deserves the same suspicion as curl piped to a shell.

A dibbla-task.yaml is a pipeline of setup steps run on your machine by dibbla run. It is what templates use to scaffold a project: check the tools are present, install dependencies, allocate ports, write an env file, start dev servers.

It is not related to dibbla.yaml, which describes deployed services, or to pipelines in the Workflows app, which run on the platform.

A complete file

version: "1"                    # required; only "1" is accepted, and it is a string

env:                            # pipeline-level variables, exported to every step
  API_URL:
    description: Where the backend lives
    default: http://localhost:8090
  OPENAI_KEY:
    description: Needed for the summariser
    required: true

ports:                          # dynamically allocated; the name becomes an env var
  BACKEND_PORT:
    preferred: 8090
    range: 20                   # try this many ports upward if taken
    description: Go API

tools:                          # named tool definitions, referenced by tool_check steps
  go:
    check: go version
    install:
      darwin: brew install go
      linux: sudo apt-get install -y golang
    bin_path: /usr/local/go/bin
    privileged: false

steps:
  - id: check-go                # required, unique
    name: Check Go              # required
    type: tool_check            # required
    tool: go

  - id: deps
    name: Install dependencies
    type: command
    run: go mod download
    depends_on: [check-go]

  - id: env
    name: Write .env
    type: write_env
    env_file: .env              # optional; defaults to .env

  - id: backend
    name: Start the API
    type: command
    run: go run ./cmd/api
    mode: background
    depends_on: [deps, env]

Unknown keys are silently ignored

Parsing is a plain YAML unmarshal with no strict-field checking. A misspelled key — depends-on, working-dir, a top-level name: — is discarded without a word, and the pipeline runs as though you never wrote it. Only an unknown step type value is rejected. Do not rely on the CLI to catch a typo in this file.

Top-level fields

Field	Required	What it is
`version`	✅	Must be the string `"1"`.
`steps`	✅	At least one step, or the file is rejected.
`env`		Named variables with `description`, `default`, `required`. Exported to every step.
`ports`		Named ports allocated at run time. The name becomes an environment variable holding the chosen port.
`tools`		Named tool definitions that `tool_check` steps reference.

There is no top-level name or description. Both are commonly written and both are thrown away.

`env`

Only the keys declared here are written by a write_env step. An env: section you forget to add means write_env produces an empty file — which is the most common way to get a pipeline that “runs fine” and leaves an app with no configuration.

Names must match ^[A-Za-z_][A-Za-z0-9_]*$.

`ports`

preferred must be between 1024 and 65535. If the preferred port is taken, the runner walks upward through range candidates. The allocated value is exported under the port’s own name, so a step can use $BACKEND_PORT directly.

A name declared in both ports and env is a hard error.

Step fields

id, name and type are required on every step. The rest are optional:

Field	Applies to	What it does
`id`	all	Unique identifier. Duplicates are rejected.
`name`	all	Human-readable label, shown while running. Required — a step without one fails before anything executes.
`type`	all	`command`, `tool_check`, or `write_env`.
`run`	`command`	The command. Required for `command` steps. A string, or a map keyed by platform.
`tool`	`tool_check`	Which entry in `tools:` to use. Must exist.
`mode`	`command` only	`background` (start and move on) or `terminal` (open a native terminal window). Default is foreground. Setting it on any other step type is an error.
`depends_on`	all	Step ids this one waits for.
`platforms`	all	Restrict to `darwin`, `linux`, `windows`.
`env`	all	Extra variables for this step only.
`working_dir`	all	Directory to run in.
`continue_on_error`	all	Keep going if this step fails.
`env_file`	`write_env`	Output path. Defaults to `.env`.
`retry`	all	`max_attempts`, `delay` (e.g. `3s`), and `on_output` to retry only when the output contains a given substring.

Steps are a graph, not a list

depends_on drives a topological sort, so the file’s order is not the execution order. Steps with no dependency between them may run in either order. If two steps must be sequential, say so with depends_on rather than relying on where they sit in the file. A dependency on an id that does not exist is rejected.

The three step types

`command`

Runs run. Either a string, or per-platform:

- id: install
  name: Install dependencies
  type: command
  run:
    darwin: brew bundle
    linux: sudo apt-get install -y build-essential

`tool_check`

Named for what it does first, not for all it does. It runs the tool’s check command, and if that fails it runs the matching install command — install_fallback if the first fails, and via sudo when the tool is marked privileged: true.

tools:
  go:
    check: go version
    install:
      linux: sudo apt-get install -y golang
    privileged: true

So a tool_check step is not a read-only assertion. It is the step most likely to change your machine.

`write_env`

Writes the variables declared in the top-level env: section to env_file (default .env).

It writes only what `env:` declares

It does not write your Dibbla credentials. DIBBLA_API_TOKEN is placed in the pipeline’s process environment by dibbla run so steps can use it; write_env never copies it to disk. If you find a live token in a .env after running a template, some step put it there explicitly — go and look at which.

Platform filtering

platforms: restricts a step to the listed operating systems, and steps for other platforms are skipped at run time.

`--preview` does not apply the filter

dibbla run --preview lists every step in the file, including ones that will be skipped on your machine. It shows you the pipeline, not the plan.

Why this file deserves suspicion

A dibbla-task.yaml fetched from a URL runs arbitrary commands on your machine, can install software, and can do it with sudo. That is the same trust decision as piping curl into a shell — the YAML makes it look tamer than it is.

Read a task file before running one you did not write. dibbla run --preview is the fast way to see the commands, remembering that it over-reports (see above) and that it will not warn you about a privileged tool install.

← Previous

dibbla run