<!-- zibby-template-version: 4 -->
# /zibby-trigger — run a deployed Zibby workflow

You are helping the user trigger a deployed workflow execution.

A trigger launches a sandboxed task that loads the workflow's bundle, runs the graph, and writes status + logs as it goes.

Canonical docs: **https://docs.zibby.app/cloud/triggering**

## Steps

1. **Get the workflow UUID.** The user should provide it; if not, run `zibby agent list` to discover it. UUIDs are stable across deploys (the same workflow always has the same UUID; only the bundle version changes).

2. **Construct the input.** Workflows take a JSON input that nodes can read via `ctx.input`. Ask the user what input the workflow expects (or read `agent.json`'s `inputSchema` if present).

3. **Run the trigger.** Three ways to pass input — they merge with this **precedence (highest → lowest)**:
   1. `-p key=value` (repeatable) — wins over everything; great for shell-friendly tweaks on top of a base payload
   2. `--input '<json>'` — full JSON payload as a string
   3. `--input-file path.json` — full JSON/YAML payload from a file (lowest precedence; `-p` and `--input` override individual keys)

   ```
   zibby agent trigger <uuid> --input '{"key":"value"}'
   zibby agent trigger <uuid> -p ticket=ENG-1234 -p priority=high
   zibby agent trigger <uuid> --input-file payload.json -p priority=urgent   # mix
   ```

   Same flag surface as `zibby agent run` (local) — flip the verb and the same call shape goes from local to remote.

4. **Tail the logs immediately:**
   ```
   zibby agent logs <uuid> -t
   ```
   This streams live output. The tail auto-attaches to all currently-running executions of the workflow (docker-compose-style), so back-to-back triggers interleave naturally.

5. **Watch for completion.** Workflow runs typically end with one of:
   - `✓ Workflow completed` — success, status `completed`
   - `Error: Node 'X' failed` — a node threw; status `failed`
   - silent timeout — task killed by the runtime; status stays `running` then becomes a zombie. Trigger again.

## Idempotency

Use `--idempotency-key <key>` to prevent duplicate runs from a retry-prone caller:
```
zibby agent trigger <uuid> --input '{}' --idempotency-key job-2026-05-04-001
```
Same key + same input within ~24h = same execution returned (no new run).

## Multiple inputs / batch

There's no built-in batch trigger — script it from your shell:
```
for ticket in ENG-1 ENG-2 ENG-3; do
  zibby agent trigger <uuid> -p ticket=$ticket
done
zibby agent logs <uuid> -t   # tail will show all 3 interleaved
```