dibbla run

Execute a `dibbla-task.yaml` pipeline locally — from a file, a URL, or as a preview without running anything. Supports per-step platform filters, dependencies, env injection, and GitHub Actions-style output.

dibbla run executes a dibbla-task.yaml pipeline on your machine. The pipeline is a list of steps — command, tool_check, or write_env — with dependencies, platform filters, and per-step env vars.

The argument is one of:

• omitted — runs ./dibbla-task.yaml from the current directory.
• a local path — runs the given file. The default working directory is the file’s parent.
• an HTTPS URL — fetches the YAML (5 MB max, 30 s timeout) and runs it. The default working directory is the invocation CWD, not a temp dir, so bootstrap pipelines can clone projects into your current directory.

Flags

Examples

# Run ./dibbla-task.yaml from CWD
$dibbla run

$dibbla run ./pipelines/build.yaml

# Fetch & run a hosted bootstrap
$dibbla run https://templates.dibbla.com/expense-reporter/bootstrap.yaml

# lists every step in the file — including ones your OS will skip
$dibbla run --preview
Execution plan:
   1. write-env              write_env    Write .env File
   2. verify-go              tool_check   Verify Go tool=go
   3. build                  command      Build Backend
   4. test                   command      Run Tests
 
Env vars:
  DATABASE_URL
  API_KEY (required)

$dibbla run \
  --env API_KEY=$STAGING_KEY \
  --env-file ./.env.staging

# Pipeable into log parsers
$dibbla run --format gh
::group::Build Backend
::debug::Running: go build -o ./bin/server ./cmd/server
::notice title=Step Succeeded::Step "Build Backend" completed in 2.1s
::endgroup::

Env precedence

--env-file is the base layer and --env KEY=value flags override individual keys. If a key appears in more than one --env flag, the last one wins.

The same rule applies to dibbla deploy --env-file, dibbla apps update --env-file, and dibbla secrets import, so the behaviour is identical wherever you can hand the CLI a file. The accepted file grammar is documented once, under .env file format.

Auto-injected environment

Every step receives these in addition to your shell env, --env, and --env-file:

Exit codes

dibbla-task.yaml at a glance

A dibbla-task.yaml file declares pipeline-level env vars, named tools, and a list of steps. The full schema is documented in the dibbla-tasks SPEC; the essentials below cover what you’ll write 90% of the time.

Top-level fields

Step types

Step fields

Example

version: "1"

env:
DATABASE_URL:
  description: "PostgreSQL connection string"
  default: "postgres://localhost:5432/app"
API_KEY:
  description: "Third-party API key"
  required: true

tools:
go:
  check: "go version"
  install:
    darwin: "brew install go"
    linux: "sudo apt-get install -y golang"

steps:
- id: write-env
  name: "Write .env File"
  type: write_env

- id: verify-go
  name: "Verify Go"
  type: tool_check
  tool: go

- id: build
  name: "Build Backend"
  type: command
  run: "go build -o ./bin/server ./cmd/server"
  env:
    CGO_ENABLED: "0"
  depends_on: ["verify-go", "write-env"]

- id: test
  name: "Run Tests"
  type: command
  run: "go test ./..."
  depends_on: ["build"]

- id: dev-server
  name: "Start Dev Server"
  type: command
  mode: terminal
  run: "npm run dev"
  working_dir: "./frontend"
  depends_on: ["build"]

Execution order

Steps run in dependency order (topological sort). Rules:

• A step waits for every entry in its depends_on list to succeed.
• If a dependency fails without continue_on_error: true, downstream steps are skipped.
• Circular dependencies fail before any step executes.
• Platform-filtered steps are removed before sorting; depends_on references to them are pruned.

See also

• dibbla template — bootstrap pipelines are the engine behind dibbla template install.
• dibbla-tasks SPEC — the canonical schema and output-format reference.