Skip to main content

Annotations

This page defines each annotation, its purpose, constraints, and common mistakes.

@in input contracts​

@in src/**/* Cargo.toml Cargo.lock
  • Type: list of glob patterns.
  • Purpose: defines inputs that influence graph fingerprints.
  • Effect: changing matched files can trigger cache miss.
  • Scope: graph tasks.

Use narrow patterns. Prefer src/**/* Cargo.toml over **/*.

@out output contracts​

@out dist/app
@out reports/test.xml
  • Type: list of paths.
  • Purpose: declares expected materialized outputs.
  • Effect: implies graph mode when @mode is omitted.
  • Validation: graph mode requires at least one output.

If a task should be cached, declare explicit outputs.

@env runtime environment​

@env RUST_LOG=info
@env HOME

Forms:

  1. KEY=value: sets fixed value for task.
  2. KEY: inherit from runtime environment.

@env participates in fingerprints for graph tasks.

@secret_env secret environment keys​

@secret_env GITHUB_TOKEN
@secret_env AWS_SECRET_ACCESS_KEY
  • Purpose: mark env keys as sensitive.
  • Effect: values are redacted in terminal/log/explain paths.
  • Explain reason stays generic: cache miss: secret env changed.

Do not put literal secrets in broskifile.

@dir working directory override​

@dir services/api
  • Type: single workspace-relative path.
  • Purpose: run command from specific directory.
  • Constraint: exactly one value.

Use this instead of prefixing every command with cd ... &&.

@mode execution mode​

@mode graph
@mode interactive

Modes:

  • graph: deterministic, staged, cache-aware.
  • interactive: live workspace execution, no cache, TTY inherited.

Inference when omitted:

  • @out present => graph mode.
  • no @out => interactive mode.

@isolation sandbox policy​

@isolation strict
@isolation best_effort
@isolation off
  • strict: enforce strict isolation where available.
  • best_effort: attempt strict, degrade when unsupported.
  • off: no sandbox isolation.

--force-isolation CLI flag overrides task setting for graph tasks.

@requires tool preflight checks​

@requires cargo docker python3
  • Purpose: fail fast when required binaries are missing.
  • Check timing: before execution work.
  • Error style: task-scoped, explicit missing binary.

Use this on setup/dev/deploy tasks to reduce trial-and-error failures.

@private hidden task​

@private
  • Purpose: hide helper tasks from broski list.
  • Use for internal wiring tasks not meant for direct invocation.

@confirm safety prompt​

@confirm "Drop local database? Type y to continue"
  • Purpose: prevent accidental destructive execution.
  • Behavior: prompts before running task.
  • Constraint: prompt text must be non-empty.

In non-interactive contexts, this should fail safe.

@load env file directive​

@load is a top-level directive (not task-scoped).

@load .env
  • Purpose: load key-value pairs into task environment resolution.
  • Path: workspace-relative.
  • Typical usage: local development defaults.

Full example​

version = "0.5"
@load .env

build [target] [mode="release"]:
    @in src/**/* Cargo.toml Cargo.lock
    @out dist/{{ target }}
    @env RUST_LOG=info
    @secret_env GITHUB_TOKEN
    @dir services/api
    @mode graph
    @isolation best_effort
    @requires cargo
    cargo build --bin {{ target }} --{{ mode }}

clean-db:
    @private
    @confirm "Reset local database?"
    @mode interactive
    @requires rm
    rm -rf backend/data/app.db

Mistakes to avoid​

  1. Using @mode graph without @out.
  2. Using broad @in **/* for every task.
  3. Expecting @secret_env values in explain output.
  4. Using @dir with multiple values.
  5. Forgetting @requires for tool-heavy tasks.