---
title: Triggers
description: Create tasks on a cron schedule, once at a set time, or on demand,
  with each fire recorded on the task it creates.
url: https://hexelstudio.com/docs/harness/triggers
---

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:

| Field | Description |
| --- | --- |
| `agent` | The agent its tasks run: `name`, `name@channel` or `name@v<n>`. |
| `goal` | Its tasks' goal. `{{routine}}`, `{{fire_id}}` and `{{scheduled_for}}` are filled in when it fires. |
| `inputs` | Optional. Its tasks' inputs. |
| `description` | Optional. What it is for. |
| `schedule` | Optional. `{"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`](https://hexelstudio.com/docs/harness/agents#manage-agents-from-files).
