Skip to content
Hexel StudioDocs

Triggers

Create tasks on a cron schedule, once at a set time, or on demand, with each fire recorded on the task it creates.

On this page

A trigger creates a task of an agent on a schedule (cron, or once at a time) or when you fire it. Each fire creates exactly one task.

Bash
hexel harness trigger set nightly --agent auditor@prod --goal "Audit the repositories" \
  --cron "0 2 * * *" --timezone Europe/London
hexel harness trigger set release-check --agent auditor@prod --goal "Check the release" \
  --at 2026-12-01T09:00:00Z
hexel harness trigger set on-demand --agent auditor@prod --goal "Audit {{fire_id}}"
hexel harness trigger fire on-demand --text "Look at the payments service" --idempotency-key deploy-4512
hexel harness trigger list
hexel harness trigger delete nightly

Define a trigger

PUT /harness/triggers/{name} creates (201) or replaces (200) a trigger:

FieldDescription
agentThe agent its tasks run: name, name@channel or name@v<n>.
goalIts tasks' goal. {{routine}}, {{fire_id}} and {{scheduled_for}} are filled in when it fires.
inputsOptional. Its tasks' inputs.
descriptionOptional. What it is for.
scheduleOptional. {"cron": "0 2 * * *", "timezone": "Europe/London"} or {"run_once_at": "<RFC 3339 time>"}. Without it, the trigger fires only on demand.

The person who sets a trigger owns the tasks it creates. Managing triggers needs harness:trigger:manage and harness:task:create, which Admins and Owners have by default.

Fire a trigger

POST /harness/triggers/{name}:fire takes {"text": "...", "data": {...}}, both optional, and answers 202 with {trigger, routine_id, fire_id}. With an Idempotency-Key, a repeated fire answers 200 with replayed: true and creates no second task.

Fire-time text and data reach the task as data under inputs.routine_fire, never in its goal.

Each fire's task gets a trigger.fired event {trigger, routine_id, fire_id}. Deleting a trigger stops its schedule first.

Triggers can also be managed as files with hexel harness apply.