Workflows - Buttons

Workflows are called drawers in Buttons. A drawer chains one or more buttons into a repeatable run with typed inputs, step outputs, validation, and history. Use a button for one action. Use a drawer when the action has more than one step, needs data from an earlier step, or should be triggered as a unit.

buttons drawer create standup-digest
buttons drawer standup-digest add github-activity granola-query slack-post
buttons drawer standup-digest connect github-activity to slack-post
buttons drawer standup-digest set slack-post.args.channel='#standup'
buttons drawer standup-digest press

Mental model

Concept	Meaning
Button	One reusable action.
Drawer	A workflow made of steps.
Step	A button, sub-drawer, loop, switch, aggregate, or wait position in the drawer.
Input	A value supplied when the drawer is pressed.
Output	A step’s parsed JSON stdout, available to later steps.
Ref	A `${...}` expression that reads from inputs, step outputs, env, or webhook URLs.

Each drawer lives on disk as drawer.json under the Buttons drawers directory and records its own run history under pressed/.

Create a drawer

buttons drawer create deploy-flow
buttons drawer deploy-flow add build publish
buttons drawer deploy-flow connect build to publish
buttons drawer deploy-flow press env=prod

add accepts button names. It also accepts drawer/<name> for sub-drawers, for_each:<button> for loops, and wait:<duration> for time pauses.

buttons drawer nightly add gitcrawl-sync brain-audit
buttons drawer parent-flow add drawer/child-flow
buttons drawer notify-all add list-users for_each:send-message
buttons drawer cooloff add wait:30s retry-fetch

Wire data between steps

When a button prints valid JSON to stdout, the drawer parses it and exposes it as the step output.

buttons create current-version \
  --code 'echo "{\"version\":\"1.2.3\"}"'

buttons create publish-version \
  --arg version:string:required \
  --code 'echo "{\"published\":\"$BUTTONS_ARG_VERSION\"}"'

buttons drawer create release-flow
buttons drawer release-flow add current-version publish-version
buttons drawer release-flow set publish-version.args.version='${current-version.output.version}'
buttons drawer release-flow press

If stdout is not JSON, the raw stdout string is still recorded in history, but structured refs like ${step.output.field} only work against JSON output.

Auto-connect by schema

If a button declares output_schema, buttons drawer <name> connect A to B can match compatible output fields to downstream args.

buttons drawer standup-digest connect github-activity to slack-post

Use explicit wiring when the field names do not line up:

buttons drawer standup-digest connect github-activity.output.summary to slack-post.args.text

Drawer inputs

Any unfilled required button arg can be supplied at drawer press time by name.

buttons drawer deploy-flow press env=prod

Explicit step args win. If a step arg is not set and a drawer input with the same name exists, Buttons fills it for that step.

Run modes

By default a drawer runs its steps sequentially. Pass --mode parallel to run steps concurrently while honoring data dependencies — a step waits only for the steps its ${...} refs actually name. --concurrency N caps how many run at once (0 means NumCPU), and --on-failure stop|continue controls whether the first failure cancels in-flight siblings.

buttons drawer release-flow press --mode parallel --concurrency 4 --on-failure stop

Step kinds

Kind	Status	Purpose
`button`	Live	Press a button.
`drawer`	Live	Call another drawer.
`for_each`	Live	Iterate nested steps over an array.
`switch`	Live	Run the first matching branch.
`aggregate`	Live	Collect values from an array.
`wait`	Live	Pause by duration or until a timestamp.
`split`, `merge`, `transform`, `batch`	Reserved	Present in schema for future executors.

Sub-drawers

A drawer can call another drawer with drawer/<name>.

buttons drawer create child-build
buttons drawer child-build add build-artifact

buttons drawer create parent-release
buttons drawer parent-release add drawer/child-build publish

Sub-drawers are useful when a workflow has a reusable middle section. The child drawer can define a return block in drawer.json so the parent can reference selected values as ${child-build.output.<field>}.

{
  "output_schema": {
    "type": "object",
    "properties": {
      "version": { "type": "string" }
    }
  },
  "return": {
    "version": "${build-artifact.output.version}"
  }
}

Loops

Use for_each:<button> for per-item work.

buttons drawer create notify-users
buttons drawer notify-users add list-users for_each:send-message
buttons drawer notify-users set for_each-send-message.over='${list-users.output.users}'
buttons drawer notify-users set for_each-send-message.as=user
buttons drawer notify-users set for_each-send-message.steps.0.args.email='${user.email}'
buttons drawer notify-users set for_each-send-message.parallelism=4
buttons drawer notify-users press

Useful loop fields:

Field	Purpose
`over`	CEL expression that resolves to an array.
`as`	Loop variable name, default `item`.
`parallelism`	Max concurrent iterations. `0` or `1` means serial.
`on_item_failure`	`stop` or `continue`.

The loop output includes results in input order, so downstream refs stay deterministic even when iterations run concurrently.

Switches

Switch steps run the first case whose when expression is truthy. Author them in drawer.json.

{
  "id": "route",
  "kind": "switch",
  "cases": [
    {
      "id": "prod",
      "when": "inputs.env == 'prod'",
      "steps": [
        { "id": "notify-prod", "kind": "button", "button": "notify-prod" }
      ]
    }
  ],
  "steps": [
    { "id": "notify-dev", "kind": "button", "button": "notify-dev" }
  ]
}

The top-level steps on a switch act as the default branch.

Aggregates

Aggregate steps collect values from an array, often after a for_each.

{
  "id": "summaries",
  "kind": "aggregate",
  "from": "${for_each-send-message.output.results}",
  "pluck": "item.output.message_id"
}

The output is { "values": [...], "count": N }, with values in the same order as the input.

Waits

Use waits to pause between steps.

buttons drawer retry-flow add fetch-api wait:30s fetch-api-2

You can also set wait fields directly:

buttons drawer retry-flow set wait.duration=2m
buttons drawer deploy-window set wait.until=2026-07-01T21:00:00Z

Waits honor cancellation, so stopping the drawer does not leave a sleeping process behind.

Failure handling

By default, a failing step fails the drawer. Step-level on_failure can be authored in drawer.json for retry or continue behavior:

{
  "id": "fetch-api",
  "button": "fetch-api",
  "on_failure": {
    "action": "retry",
    "max_attempts": 3,
    "backoff": { "strategy": "exponential", "initial_ms": 500 }
  }
}

A drawer can also declare on_error to point at a separate error-handler drawer, but this is reserved: the v1 executor parses it and does not yet run it. The field exists so a drawer can declare the intent ahead of the executor. When it ships, the handler will receive drawer, run_id, failed_step, error, and redacted inputs, and the failure will still remain visible in the original drawer run history.

{
  "on_error": {
    "drawer": "notify-workflow-failure",
    "with": {
      "severity": "warning"
    }
  }
}

Webhook-triggered drawers

Webhook triggers currently attach to drawers:

buttons drawer create on-apify-done
buttons drawer on-apify-done add apify-fetch-dataset
buttons drawer on-apify-done trigger webhook /apify-done
buttons webhook listen

The request appears as ${inputs.webhook} inside the drawer:

${inputs.webhook.body}
${inputs.webhook.headers.Content-Type}
${inputs.webhook.query.token}
${inputs.webhook.method}
${inputs.webhook.path}
${inputs.webhook.received_at}

Webhook is the only trigger kind drawers support today; registering any other kind errors. The trigger can require auth — append --auth basic|header|jwt (plus the matching --auth-user/--auth-pass, --auth-header-name/--auth-header-value, or --jwt-secret flags) to trigger webhook; the default is --auth none. Secret values accept $ENV{VAR}, resolved at match time, so drawer.json stays commit-safe. buttons webhook listen runs the foreground dispatcher behind a Cloudflare tunnel, so it requires cloudflared on your PATH. Run buttons webhook setup once for a stable hostname, or let listen spin up an ephemeral *.trycloudflare.com URL per run. Test a webhook drawer without standing up the listener by synthesizing the request payload at press time:

buttons drawer on-apify-done press --webhook-body '{"datasetId":"abc"}'
buttons drawer on-apify-done press --webhook-body @fixture.json

Inspect and debug

buttons drawer list
buttons drawer standup-digest
buttons drawer standup-digest logs
buttons drawer standup-digest logs --failed
buttons drawer standup-digest press --summary --json
buttons drawer schema

--summary previews a drawer mutation or press without running it. Use --json when an agent or script needs structured output. buttons drawer schema prints the embedded JSON Schema for drawer.json. See drawer.json for the full field reference.

Storage shape

A drawer folder looks like this:

~/.buttons/drawers/standup-digest/
  drawer.json
  pressed/
    2026-06-28T09-00-00.json

The history file records drawer inputs, each step’s resolved args, stdout, stderr, parsed output, duration, exit code, and structured errors. That is what lets agents recover from workflow failures without re-running blind.

​Mental model

​Create a drawer

​Wire data between steps

​Auto-connect by schema

​Drawer inputs

​Run modes

​Step kinds

​Sub-drawers

​Loops

​Switches

​Aggregates

​Waits

​Failure handling

​Webhook-triggered drawers

​Inspect and debug

​Storage shape