Action Structure

Each action is a YAML file in ~/.vibe-action/actions/. The engine loads all .yaml files recursively and builds a CLI command for each one.

Minimal Action

name: hello
about: Say hello
actions:
  - tag: tag_hello
    run: value
    expect: string
    action: Hello, World!

$ vibe-action hello
info: completed in 0.01s
── success ──
Hello, World!
─────────────

Full Structure

name: my-action # CLI subcommand name
about: Description # Help text
check: '^[a-z]+$' # Optional: regex validation for final output
notify: true # Optional: show system notification on completion
args: # Optional: CLI arguments
  - name: input
    short: i
    input: string # string | bool | number | path | list<string> | list<bool> | list<number> | list<path>
    help: Input text
    default: 'default' # Optional: makes argument non-required
api: # Optional: IDE plugin integration
  output: replace # replace | clipboard | dialog
  args:
    input: selection # selection | clipboard
actions: # Pipeline steps (executed in order of dependencies)
  - tag: tag_step1
    run: cmd # cmd | value | small | medium | large | vision | tiny
    expect: string # string | list. Omit for no expected output.
    check: '^.+$' # Optional: regex validation for this step
    confirm: true # Optional: ask before executing
    action: echo "Hello {input}!"

Action Types

Type	Description
`cmd`	Shell command executed in terminal
`value`	Static string, no execution
`tiny`	Prompt sent to tiny models
`small`	Prompt sent to small models
`medium`	Prompt sent to medium models
`large`	Prompt sent to large models
`vision`	Prompt sent to vision models

Argument Types (`input`)

Type	Description
`string`	Text (default)
`bool`	true/false flag
`number`	Integer or float
`path`	File path (validated for existence)
`list<string>`	Comma-separated list of strings
`list<bool>`	Comma-separated list of bool values
`list<number>`	Comma-separated list of numbers
`list<path>`	Comma-separated list of file paths

Expect Types

Type	Description
`string`	Text (default)
`list`	List of strings, triggers loop

Omit expect for steps with no expected output.

IDE Plugin Integration (`api`)

The optional api block configures how IDE plugins (like VS Code or IntelliJ) interact with the action.

output: Defines how the final result is presented (replace selected text, send to clipboard, or show in a dialog).
args: Maps action arguments to IDE contexts (e.g., automatically pass the selection or clipboard to the argument).

Conditional Actions (When/Then)

action can be a list of when/then pairs for conditional execution:

- tag: tag_result
  run: cmd
  expect: string
  action:
    - when: '{tag_check|contains:DIRTY}'
      then: echo "{tag_content}"
    - when: '{tag_check|contains:CLEAR}'
      then: echo "No errors found."

Each when condition is evaluated. The first matching then is executed. If no condition matches — the step fails with an error.

Execution Order

Actions are sorted by their {tag} dependencies, not by their order in the file. The engine builds a dependency graph and executes in topological order.

actions:
  - tag: tag_files # 1st — no dependencies
    run: cmd
    action: find . -name '*.rs'

  - tag: tag_summary # 2nd — depends on tag_files
    run: small
    action: Summarize - {tag_files}

Check (Regex Validation)

check validates output against a regex pattern. If the output doesn’t match — the step fails with an error.

- tag: tag_files
  run: cmd
  check: '.+' # Must be non-empty
  action: git diff --name-only

Confirm

confirm: true asks the user for approval before executing. Useful for dangerous commands.

- tag: tag_commit
  run: cmd
  confirm: true
  action: git commit -m "feat: something"

Clipboard

Use the clipboard modifier to copy values during pipeline execution:

- tag: tag_result
  run: value
  expect: string
  action: '{tag_data|format:json|clipboard}'

Keyboard shortcuts

Vibe Action