Pipeline — YAML Format

Each action is a YAML file in ~/.vibe-action/actions/. The file name becomes the CLI subcommand. Custom files are loaded automatically alongside the built-in defaults.

Top-level fields

version: '0.0.2'
name: my-action
about: Short description for CLI help
notify: true

args:
  - name: arg_format
    short: 'f'
    input: string
    default: json
    help: 'Output format'

api:
  output: replace
  input: query_raw
  args:
    arg_format: query_raw

actions:
  - tag: tag_result
    run: small
    val:
      - name: content
        data: query_raw
    action: |
      [Task]
      Do something with {content}

Args

Each argument becomes a CLI flag and a val-candidate tag under its own name. Convention: prefix names with arg_ (e.g. arg_file → flag --arg_file, tag arg_file).

args:
  - name: arg_dry_run
    short: 'd'
    input: bool
    default: false
    help: 'Print message without executing'

API block

Metadata for the IDE plugin: input source, output target, extra args. Ignored by the CLI runtime. Field reference and semantics — see IDE Plugin.

Actions

Each item is one pipeline step. Execution order is determined automatically by data dependencies (topological sort), not by list position.

actions:
  - tag: tag_result
    run: medium
    reg: '.+'
    ask: true
    when: 'is:empty:not'
    val:
      - name: content
        data: query_raw
        mods: 'fetch|text'
        when: 'is:path'
    action: |
      [Task]
      Process {content}

Action-level when

An action-level when is evaluated before any candidates are resolved. If it fails, the entire action is skipped (dead tag). Accepts inspect operators only — the same set as candidate-level when and fail.

This is separate from candidate-level when, which controls individual candidate selection. Use the action-level guard to skip an entire step based on runtime conditions.

Run types

LLM sizes route to cluster nodes by role — see Configuration.

Output validation (reg)

If reg is set, the step’s output is tested against the regex. No match → hard error, pipeline aborts. Use it to enforce output format:

reg: '.+'           # must be non-empty
reg: '^[^\n]+$'     # must be a single line
reg: 'DIRTY|CLEAR'  # must be one of these words

Pipeline-level check

The top-level check field validates the final pipeline result (the output of the last action). Same behavior as reg — no match → hard error. Use it when you need to enforce the overall result format rather than individual step output.

Reserved prefixes

Action tags and argument names must not use query_* or system_* prefixes — those are reserved for providers. A bare query tag is also forbidden; use query_raw instead.

Self-referencing (data points to the action’s own tag) is a validation error.

Version management

The version field must match the engine’s PIPELINE_VERSION. For custom actions a mismatch is a validation error — bump version when the pipeline schema changes.

Built-in files are instead overwritten with the embedded default on version mismatch — see Built-in Actions.