> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Automation rules

> Create, inspect, test, and manage automation rules from the CLI.

Use `atoll automation` with your selected organization profile. Creating,
updating, testing, enabling, disabling, deleting, and viewing run history require
owner or admin access. The server validates permissions and the complete rule definition.

```bash theme={null}
atoll automation list --json
atoll automation list --project project-slug --json
atoll automation get rule-uuid --json
atoll automation create --file rule.json --json
atoll automation update rule-uuid --file patch.json --json
atoll automation test rule-uuid --json
atoll automation runs rule-uuid --limit 20 --json
atoll automation enable rule-uuid
atoll automation disable rule-uuid
atoll automation delete rule-uuid --dry-run
atoll automation delete rule-uuid --force
```

`--file -` reads a JSON object from standard input. Create defaults to disabled
when `enabled` is omitted, and requires an explicit `project_id`: a project UUID
or `null` for Organization-wide scope. Update sends only the fields in the patch.
An omitted `--project` on list does not apply the profile's default project;
organization-wide CI rules remain visible. List and run-history JSON uses the
standard `resource`, `items`, `total`, `limit`, `offset`, `nextOffset`,
`truncated`, and `hint` fields. Inspect truncation metadata before assuming
that the response contains all history. Permanent deletion requires `--force`;
`--dry-run` previews it without changing the rule.

## Create an issue when CI fails

Save this definition as `rule.json`. Replace the target project UUID with your
project ID and choose one of that project's status keys.

```json theme={null}
{
  "name": "Create an issue for unlinked CI failures",
  "project_id": null,
  "trigger_event": "ci.run.completed",
  "conditions": [
    { "kind": "event", "field": "conclusion", "operator": "eq", "value": "failure" },
    { "kind": "event", "field": "has_linked_issue", "operator": "eq", "value": false }
  ],
  "actions": [
    {
      "type": "create_issue",
      "project_id": "00000000-0000-4000-8000-000000000001",
      "status": "todo",
      "title": "{{workflow}} failed in {{repository}}",
      "description": "{{conclusion}}: {{run_url}}",
      "priority": 1
    }
  ]
}
```

Create the disabled rule, inspect it, and run a preview before enabling it.
CI previews use fixed example values and never read or execute a live run.
Custom repository or branch conditions can fail to match the example.
`test` sends an empty object when `--file` is omitted; CI previews reject
caller-supplied issue or event data. For issue rules, pass a JSON preview body
with `--file` as described in [Automation fields](/api-reference/fields).

CI rules require organization scope and allow Create issue and Send webhook. The action's
project is the destination. Each repository, run, and attempt has one immutable
source receipt; duplicate deliveries reuse its original link state and cannot
create another issue for the same rule. A new attempt is a distinct event.

Issue-triggered rules also support additive assignment, unassign, label removal,
and the other [core actions](/user-guide/automations). JSON files use the same
canonical fields and validation as the API. Use `runs` to inspect results,
including `created_issue_id` and failed or interrupted actions.

## Schedule an issue-time rule

Use the same rule file and `atoll automation test` command for time-based rules.
Set `trigger_event` to `schedule.issue_time` and include `schedule_config`:

```json theme={null}
{
  "name": "Nudge stale review tasks",
  "project_id": "project-uuid",
  "trigger_event": "schedule.issue_time",
  "schedule_config": {
    "anchor": "status_changed_at",
    "offset_minutes": 120
  },
  "conditions": [
    { "kind": "field", "field": "status", "operator": "eq", "value": "review" }
  ],
  "actions": [
    { "type": "post_comment", "value": "This task has been in Review for two hours." }
  ]
}
```

`anchor` is `updated_at`, `status_changed_at`, or `due_date`. Offsets for the
first two anchors must be non-negative. A due-date offset may be negative for
before due, zero for due, or positive for after due; date-only due dates use
midnight UTC. Scheduled rules are checked by the existing 15-minute maintenance
sweep, catch up after a missed sweep, exclude archived issues, and deduplicate
each `(rule, issue, scheduled_for)` occurrence. They use the shared rule
conditions, actions, and Activity history. They do not support arbitrary cron,
recurrence, or calendar expressions.

For a scheduled rule, `atoll automation test rule-uuid --file preview.json`
returns `scheduled_for`, `due`, and `conditions_matched` in addition to
`matched` and `actions_that_would_run`. The preview is side-effect free. Pass
an `issue_id`, or an issue sample containing the selected time fields; do not
pass an event.

For an invalid rule, use separate operations: `disable`, `update` the complete
definition while it remains disabled, `test` the saved rule, then `enable` it.
An enabled rule cannot change its source `project_id` in the same request that
disables it. The human `get` output includes invalid state and validation paths;
JSON output preserves the API response.