event

name	event
description	Operate the `event` scheduler — create, list, fire, and inspect events run by the `eventd` daemon. Events trigger on cron schedules, fixed intervals, file changes (inotify), boot, or manual emit. Trigger when the user wants to schedule a recurring task, react to file changes, run a handler on demand, or inspect the logs of past runs.

event skill

1. The model

An event is a directory holding an event.toml manifest and a handler script. eventd (the daemon) arms each enabled event's triggers and runs the handler when one fires.

The handler is a shell program with a simple contract:

• stdin ← JSON trigger context ({event, trigger, attempt, time, payload, context}), plus EVENT_NAME / EVENT_TRIGGER / EVENT_PAYLOAD environment variables.
• stdout → logged to the per-run log file.
• stderr + non-zero exit → recorded as a failure and captured to a .err file; the error policy decides retries/backoff and any on-failure hook.

2. Triggers

• cron — --cron '0 2 * * *' (or @daily, etc.)
• interval — --interval 5m
• watch — --watch PATH [--recursive] [--on create,modify,remove] [--debounce 500ms]
• nostr — --nostr --nostr-author <npub> --nostr-kind <n> [--nostr-relay wss://...] [--nostr-replay]
• manual — --manual, then event emit NAME
• boot — --boot, fired once when eventd starts

Outbound: --dispatch-nostr [--dispatch-when always|success|failure] [--dispatch-content summary|stdout|record] publishes a signed Nostr event after a run.

3. Workflow recipes

1. Start the daemon.

   event init
   eventd --user &        # or: systemctl --user enable --now eventd
   

2. Create a cron event.

   event add nightly --cron '0 2 * * *' --command 'backup.sh'
   

3. React to file changes.

   event add rebuild --watch /srv/content --recursive \
     --on create,modify --debounce 500ms \
     --command 'make -C /srv'
   

4. A handler that reads its payload from stdin.

   event add deploy --manual --stdin <<'SH'
   #!/bin/sh
   ctx=$(cat)                 # JSON trigger context
   echo "deploying: $ctx"
   SH
   event emit deploy --payload v1.2
   

5. Decentralized dispatch over Nostr. Enable it in <config_dir>/eventd.toml:

   [nostr]
   enabled = true
   relays  = ["wss://relay.damus.io"]
   

   Then react to a trusted key (the signed event arrives on stdin) and optionally publish an alert on failure:

   event identity --generate
   event add remote --nostr --nostr-author npub1... \
     --nostr-kind 30078 --command 'jq -r .content | sh' \
     --dispatch-nostr --dispatch-when failure
   

6. Inspect.

   event list                 # events + last-run status
   event status deploy --json
   event logs deploy          # last run's stdout
   event logs deploy --errors # captured stderr
   

7. Error behaviour. Set on creation or in the manifest (event edit NAME):

   --retries 3 --retry-delay 10s --backoff 2.0 \
   --on-failure 'logger event failed' \
   --treat-stderr-as-error --timeout 10m
   

4. Guardrails

1. Edits need a reload. event add/edit/enable/... nudge the daemon automatically; if eventd was down, changes apply when it next starts (or run event reload).
2. event rm NAME deletes the handler and logs. No undo.
3. Validate cron yourself for intent — syntax is checked, but a wrong-but-valid schedule is accepted.
4. --system vs --user. As root the client and daemon default to the system store (/etc/event); pass --user to use the per-user store instead. Client and daemon must agree.
5. Logs accumulate. There is no automatic rotation yet; prune <logs>/<name>/ or add a cron event that cleans them.
6. Always set --nostr-author on Nostr triggers. An empty author list means anyone can fire the handler. The author allowlist is the authorization mechanism. Guard the secret key at <config_dir>/key.

5. Command reference

Every command also has its own man page (man event-<cmd>). Global flags --system / --user pick the layout (system is the default as root).

Command	Synopsis	What it does
add	add NAME <trigger/handler/error flags>	Create an event + handler stub (or --stdin/--command); auto-reloads. See man event-add.
rm / delete	rm NAME	Delete the event, handler, and logs. No undo.
list / ls	list [--json]	All events + last-run status (live from daemon, else store).
status	status [NAME] [--json]	Status for one or all events.
show	show NAME	Print the manifest TOML.
edit	edit NAME	$EDITOR the manifest, validate, reload.
enable / disable	enable NAME	Arm / disarm an event's triggers.
emit	emit NAME [--payload S | --stdin]	Fire now (trigger manual); works even if disabled.
logs	logs NAME [--errors] [--list]	Last run's stdout, captured stderr, or file list.
reload	reload	Re-read the store and re-arm all triggers.
ping	ping	Is the daemon reachable? (exit 0/1)
init	init	Create dirs; print how to start eventd.
identity	identity [--generate]	Print this node's Nostr npub.

add flag groups (most-used)

• Triggers: --cron EXPR, --interval DUR, --watch PATH [--recursive] [--on create,modify,remove] [--debounce 500ms], --nostr [--nostr-author NPUB] [--nostr-kind N] [--nostr-relay URL] [--nostr-replay], --manual, --boot (most are repeatable).
• Handler: --command STR (inline) or --stdin (script body), --timeout DUR.
• Error policy: --retries N, --retry-delay DUR, --backoff F, --on-failure STR, --treat-stderr-as-error.
• Dispatch: --dispatch-nostr [--dispatch-when always|success|failure] [--dispatch-content summary|stdout|record] [--dispatch-kind N].
• Other: --description STR, --disabled, --force.

6. Where to read more

• man event / man eventd / man event-<cmd>
• docs/event.md — CLI contract reference
• This package's CLAUDE.md