<!--
Sitemap:
- [Installation](/installation): Install the Bento daemon on macOS or Linux, then write your first pipeline to run a coding agent on a GitHub, Linear, or schedule event.
- [Upgrading](/upgrading): Version-specific steps for upgrading an existing Bento install.
- [Concepts](/concepts)
- [Build your first pipeline](/tutorials/pipeline-args)
- [Target a specific issue or PR from a URL](/tutorials/url-targeting)
- [Keep state across runs](/tutorials/pipeline-state)
- [Fire a pipeline on a schedule or on demand](/tutorials/schedule-and-fire)
- [Deploy a box to Railway](/tutorials/deploy-to-railway)
- [Operate a hosted daemon](/tutorials/operate-a-hosted-daemon)
- [Configuration](/configuration): Configure the Bento daemon with daemon.yaml: service name, port, webhooks, sandboxes, knowledge base, and environment variables.
- [Members](/members)
- [Knowledge base](/knowledge-base/)
- [Method and delivery](/knowledge-base/modes): Choose how Bento retrieves knowledge (BM25, vector, or hybrid) and how it delivers that knowledge to a coding agent.
- [Config](/knowledge-base/config)
- [MCP](/knowledge-base/mcp): Give coding agents your team knowledge over MCP. The Bento daemon serves an ask_knowledge search tool and per-file resources.
- [Pipeline configuration reference](/pipelines/config): Reference for Bento pipeline YAML: triggers, agents, skills, instructions, filters, sandboxes, structured results, and outputs.
- [Filters](/pipelines/filters): Filter GitHub, Linear, and webhook events by repository, label, and other fields so only the right Bento pipelines run.
- [Triggers](/triggers/): Start a Bento pipeline from a GitHub, Linear, webhook, schedule, or manual trigger. Compare the trigger types and when each one fires.
- [GitHub trigger](/triggers/github): Run a coding agent on GitHub pull request, issue, and other webhook events. Configure HMAC verification and event patterns.
- [Linear trigger](/triggers/linear): Run a coding agent on Linear issue and comment events. Configure the Linear webhook, signature verification, and Hookdeck relay.
- [Webhook trigger](/triggers/webhook): Fire a Bento pipeline from any HTTP POST to /webhooks/{name}, with bearer-token authentication declared in daemon.yaml.
- [Schedule trigger](/triggers/schedule)
- [Manual trigger](/triggers/manual): Fire any Bento pipeline on demand with bento trigger fire, and pass typed inputs to a pipeline that runs only on request.
- [Traces](/pipelines/traces)
- [Slack](/integrations/slack)
- [Public access](/public-access): Expose the Bento daemon to GitHub webhooks through a Cloudflare Quick Tunnel or Tailscale Funnel, and compare the two options.
- [Context engineering](/context-engineering): Assemble each coding agent prompt from personas, policies, skills, and pipeline instructions. Learn which file each instruction belongs in.
- [Best practices](/best-practices)
- [Troubleshooting](/troubleshooting)
- [Architecture](/architecture/vision)
- [Workspaces](/workspaces)
- [Authentication](/authentication)
- [Identity](/identity)
- [Security](/security)
- [References](/references)
- [Changelog](/changelog): Bento release history.
- [CLI reference](/cli/)
- [Setup](/cli/setup)
- [Secrets](/cli/secrets)
- [Lifecycle](/cli/lifecycle)
- [Sandbox image](/cli/image)
- [Sandboxes](/cli/sandbox)
- [Observability](/cli/observability)
- [Diagnostics](/cli/diagnostics)
- [Triggers](/cli/triggers)
- [Workbench](/cli/workbench)
- [Auth](/cli/auth)
- [Knowledge](/cli/knowledge)
- [Evals](/cli/evals)
- [Bento docs: run coding agents from version-controlled pipelines](/index): Bento runs coding agents from pipelines you keep in your repository. Declare the trigger, sandbox, skill, and guardrails in YAML.
- [Runtime wrapper](/architecture/runtime-wrapper)
- [Skill evolve](/architecture/skill-evolve)
-->

# Triggers

## `bento trigger list`

List stored triggers, newest first. Filters combine. The footer reports the unpaged match count.

```bash
bento trigger list --repo acme/web --pr 42        # everything for one PR
bento trigger list --status error --since 6h      # recent failures
bento trigger list --pipeline pr-review --json    # machine-readable
```

| Flag | Description |
|------|-------------|
| `--repo <owner/repo>` | Repository — a full slug, or a repo label from `daemon.yaml` `repos:` (ambiguous bare names error rather than guess) |
| `--pr <number>` | Pull request number |
| `--status <status>` | Trigger status (`received`, `matched`, `queued`, `processing`, `done`, `error`, `superseded`, `discarded`) |
| `--code <code>` | Diagnostic code of a failed or discarded trigger. See [Diagnostic codes](#diagnostic-codes). |
| `--pipeline <name>` | Pipeline name |
| `--event <type>` | Event type, for example `pull_request.synchronize` |
| `--kind <kind>` | Trigger kind (`webhook`, `schedule`, `manual`, `url`, `mcp`, `http`) |
| `--since <when>` | ISO timestamp or shorthand (`30m`, `6h`, `2d`) |
| `--limit / --offset` | Page through results (limit ≤ 200, default 50) |
| `--json` / `--format <fmt>` | Structured output (global flags: `json`, `yaml`, `toon`, `md`, `jsonl`) |
| `--instance <name>` | Target daemon instance (default: cwd config, else the running instance) |

## `bento trigger stats`

Count stored triggers. The daemon groups the rows and returns the counts. One command replaces a paged scan of the list. The filters are the filters `bento trigger list` accepts.

```bash
bento trigger stats --since 24h --by pipeline,status      # what ran today
bento trigger stats --since 7d --status error --by code   # why it failed
bento trigger stats --repo acme/web --by event --json     # machine-readable
```

The largest group is first. The footer reports the matched triggers and the group count.

```
PIPELINE   STATUS      COUNT
pr-review  done           12
pr-review  error           3
-          discarded     180
195 triggers in 3 groups
```

A `-` is a column the row does not carry. A discarded trigger has no pipeline. A successful trigger has no diagnostic code.

| Flag | Description |
|------|-------------|
| `--by <dimensions>` | Comma-separated grouping columns, three at most: `status` (default), `code`, `pipeline`, `event`, `kind`, `repo` |
| `--repo <owner/repo>` | Repository — a full slug, or a repo label from `daemon.yaml` `repos:` |
| `--pr <number>` | Pull request number |
| `--status <status>` | Trigger status (`received`, `matched`, `queued`, `processing`, `done`, `error`, `superseded`, `discarded`) |
| `--code <code>` | Diagnostic code of a failed or discarded trigger. See [Diagnostic codes](#diagnostic-codes). |
| `--pipeline <name>` | Pipeline name |
| `--event <type>` | Event type, for example `pull_request.synchronize` |
| `--kind <kind>` | Trigger kind (`webhook`, `schedule`, `manual`, `url`, `mcp`, `http`) |
| `--since <when>` | ISO timestamp or shorthand (`30m`, `6h`, `2d`) |
| `--json` / `--format <fmt>` | Structured output (global flags: `json`, `yaml`, `toon`, `md`, `jsonl`) |
| `--instance <name>` | Target daemon instance (default: cwd config, else the running instance) |

## `bento trigger fire <pipeline>`

Fire a pipeline on demand against a branch, a commit, or a pull request. You fire any configured pipeline this way.

```bash
bento trigger fire pr-review --branch feat/foo
bento trigger fire pr-review --pr 42
bento trigger fire pr-review --sha 1a2b3c4
bento trigger fire manual-task --arg request="review the latest changes"
```

| Flag | Description |
|------|-------------|
| `--branch <name>` | Branch to check out |
| `--sha <sha>` | Commit SHA to check out |
| `--pr <number>` | Pull request number |
| `--arg <key=value>` | Pipeline input, repeatable. Validated against the pipeline's `args:` |
| `--instance <name>` | Target daemon instance (default: cwd config, else the running instance) |

Bento validates each `--arg` input against the `args:` declaration of the pipeline, and rejects an undeclared key, a missing required input, and a wrong type. A pipeline that declares no `args:` accepts no `--arg`. See [Manual triggers](/triggers/manual#typed-inputs).

## `bento trigger fire <url>`

Pass a URL instead of a pipeline name to route by `trigger.patterns`. The URL prefix-matches the `patterns` of every pipeline, and bento fires the single pipeline that matches. A GitHub pull request URL (`/pull/<n>`) or issue URL (`/issues/<n>`) fills in the repository and the number itself, so bento rejects `--branch`, `--sha`, and `--pr` next to a URL.

```bash
bento trigger fire https://github.com/owner/repo/pull/42
```

A URL that matches no pipeline's `patterns` errors with `no pipeline matches <url>`. A URL that matches more than one errors and lists them, rather than firing all of them. See [URL routing](/triggers/manual#url-routing).

## `bento trigger inspect [<id>]`

Show what the runtime receives, either for a stored trigger or for a pipeline previewed against a synthetic event. The `<id>` comes from `bento trace`. Supply an `<id>` **or** `--pipeline <name>`.

```bash
bento trigger inspect <id>                          # a stored trigger
bento trigger inspect <id> --prompt                 # its rendered prompt
bento trigger inspect --pipeline pr-review --prompt # preview, no trigger
```

With `--pipeline` and no `<id>`, bento composes the named pipeline against a synthetic event, so you inspect its prompt and argv without firing a trigger. `{{args.*}}` render from `--arg`, validated against the `args:` of the pipeline. Where the synthetic event supplies no `{{event.*}}` value, bento leaves the `{{event.x}}` literal in place instead of failing.

| Flag | Description |
|------|-------------|
| `--event` | Print the original webhook payload (JSON) |
| `--prompt` | Print the rendered user prompt |
| `--system-prompt` | Print the assembled system prompt (PERSONA.md + skill pointer + augment) |
| `--orchestrator-prompt` | Print the orchestrator's own prompt, including the blocks `options.state` and `options.graph` inject. Orchestrated pipelines only |
| `--args` | Print the full argv as JSON |
| `--size` | Print prompt size breakdown with token estimates |
| `--json` / `--format <fmt>` | Structured output (global flags: `json`, `yaml`, `toon`, `md`, `jsonl`) |
| `--pipeline <n>` | With an `<id>`, pick a single pipeline when multiple match. Without one, the pipeline to preview |
| `--arg <k=v>` | Preview-mode pipeline input, validated against `args:` (repeatable) |
| `--instance <name>` | Target daemon instance (default: cwd config, else the running instance) |

## `bento trigger replay <trigger-id>`

Re-dispatch a stored trigger through the daemon.

After a planned shutdown, the daemon automatically replays eligible webhook triggers with the `shutdown_aborted` diagnostic once per lineage. A lineage consists of the original trigger and its replays. Replay waits for startup readiness and creates a new trigger with a `replayed_from` link. Normal event matching and filters still apply. Automatic replay excludes operator cancellations, scheduled triggers, and work-graph triggers.

At each startup, the daemon scans at most 25 candidates, oldest first. `bento trace` displays the original trigger as `replay_of`. Replay does not resume an interrupted agent process or reverse its earlier provider actions.

To inspect remaining work, run `bento trigger list --code shutdown_aborted`. If a lineage has used its automatic replay, use the explicit replay command:

```bash
bento trigger replay <trigger-id>
bento trigger replay <trigger-id> --payload '{"key":"value"}'
```

| Flag | Description |
|------|-------------|
| `--payload <json>` | Override the trigger payload |
| `--ignore-filter` | Bypass pipeline filter conditions (still matches on event type, requires `--pipeline`) |
| `--pipeline <name>` | Scope the replay to a single named pipeline |
| `--instance <name>` | Target daemon instance (default: cwd config, else the running instance) |

## `bento trigger schedule <name>`

Fire a scheduled pipeline immediately, outside its cron schedule.

```bash
bento trigger schedule triage-sweep
```

| Flag | Description |
|------|-------------|
| `--instance <name>` | Target daemon instance (default: cwd config, else the running instance) |

## Diagnostic codes

A trigger that ends in `error` or `discarded` carries one of these codes. Filter on a code with `--code`, or group by it with `bento trigger stats --by code`.

| Code | Status | Meaning |
| --- | --- | --- |
| **Agent run** | | |
| `agent_timeout` | `error` | The agent ran past its time limit, and the daemon stopped it. |
| `agent_interrupted` | `error` | The agent process stopped before it gave a final result. |
| `agent_exit_error` | `error` | The agent exited with a non-zero code, or its runtime reported a failed result. |
| `hook_veto` | `error` | A pre-run hook stopped the run before the agent started. |
| `hook_error` | `error` | A pre-run hook failed, so the daemon stopped the run. |
| **Workspace and setup** | | |
| `workspace_setup_failed` | `error` | Workspace preparation failed for a reason other than authentication or the network. |
| `workspace_auth_failed` | `error` | The provider rejected the daemon's credential during workspace preparation. |
| `workspace_network_failed` | `error` | A network or provider outage stopped workspace setup or a running sandbox, and one retry did not clear it. |
| `snapshot_not_ready` | `error` | The declared sandbox snapshot has no ready version. |
| `snapshot_runtime_unverified` | `error` | The declared sandbox snapshot is not verified for the run's runtime. |
| `snapshot_full` | `error` | The snapshot alias exceeded its concurrency wait limit, or the Cloudflare bridge immediately refused sandbox creation at a version's instance limit. |
| `setup_precondition_failed` | `error` | The run did not meet a precondition that a setup step declares. |
| **Result** | | |
| `result_parse_error` | `error` | The agent's output does not match the pipeline's result schema. |
| `result_apply_error` | `error` | The daemon could not publish the result to its output. |
| **Work graph** | | |
| `graph_node_failed` | `error` | A work graph node failed, and no more specific code applies. |
| `graph_node_enqueue_failed` | `error` | The daemon could not queue the run of a work graph node. The node gets another attempt until it reaches its attempt limit. |
| **Trigger dispatch** | | |
| `pipeline_action_failed` | `error` | Every action pipeline that matched the event failed. |
| `workspace_unresolved` | `error` | The daemon could not resolve a workspace for the event. |
| `workload_manager_unavailable` | `error` | The daemon has no workload manager to dispatch the run. |
| `trigger_orphaned` | `error` | The trigger had no live run after its grace period. |
| `internal_error` | `error` | The daemon failed, and no other code explains the failure. |
| **Routing** | | |
| `no_pipeline_match` | `discarded` | No pipeline subscribes to the event's source and type. |
| `filter_loop_breaker` | `discarded` | The event is the bot's reaction to its own comment or review reply. |
| `filter_merged_pr` | `discarded` | The event is for a pull request that is merged or closed. |
| `filter_repo` | `discarded` | The event's repository is not in the pipeline's repository list. |
| `filter_labels` | `discarded` | The subject's labels do not satisfy the pipeline's `labels` or `not_labels` filter. |
| `filter_state` | `discarded` | The subject's state does not match the pipeline's `states` filter. |
| `filter_predicate` | `discarded` | The event does not satisfy the pipeline's `when` or `not` predicate. |
| `filter_mentioned` | `discarded` | The event's mention does not match the pipeline's `mentioned` filter. |
| `filter_assignee` | `discarded` | The event's assignee does not match the pipeline's `assignee` filter. |
| `filter_participants` | `discarded` | No participant that the pipeline names approved or commented on the pull request. |
| `filter_unavailable` | `discarded` | A lookup that a filter needs failed, so the daemon could not evaluate the filter. |
| `mention_escalation_denied` | `discarded` | The user who mentioned the bot cannot push to the repository. |
| `review_on_push_disabled` | `discarded` | The pipeline sets `review_on_push: false`, so a push does not start a review. |
| **Discarded after a match** | | |
| `head_already_reviewed` | `discarded` | The pipeline already reviewed the pull request's head commit. |
| `head_unchanged` | `discarded` | The branch head did not move after the pipeline's last completed run. |
| `head_ref_missing` | `discarded` | The trigger's head ref was deleted before workspace setup ran. |
| `workload_gone` | `discarded` | The daemon restarted and lost the workload before it dispatched the run. |
| `run_already_started` | `discarded` | A process before the restart already started this run, so the daemon did not start it again. |
| `schedule_not_configured` | `discarded` | The pipeline no longer has a schedule. |
| `schedule_tick_expired` | `discarded` | The schedule tick is older than the schedule's maximum age. |
| `schedule_tick_superseded` | `discarded` | Another job for the same schedule is already queued. |
| **Restart and configuration** | | |
| `shutdown_aborted` | `error` | A planned daemon restart stopped the run. The next boot replays it once. |
| `unknown_agent_reference` | `discarded` | The pipeline names an agent that the daemon did not find at boot. |
| `unknown_skill_reference` | `discarded` | The pipeline names a skill that the daemon did not find at boot. |
