Triggers

A trigger starts a workflow.rattish without anyone pressing Run. It can fire on a cron schedule, when files change, or when a program on this computer calls a local webhook. Every run goes through the same path as Raticode rattish run, so it gets the same compile, preflight, and run record.

Triggers only fire while something is running them

Triggers run only while Raticode or its background scheduler is running. Nothing wakes a sleeping computer. Turn on Start at login if triggers should still fire after a reboot.

Triggers belong to the computer, not the workflow file. They aren't part of workflow.rattish, and exporting a workflow doesn't export its triggers or tokens.

Add a trigger

In the Studio, open the workflow, choose Workflow settings from the graph's More menu, and scroll to Triggers. From the CLI:

Raticode rattish triggers add cron PATH/workflow.rattish --cron "0 9 * * 1-5" --timezone America/New_York
Raticode rattish triggers add file PATH/workflow.rattish --path inbox --debounce 2 --glob "*.csv"
Raticode rattish triggers add webhook PATH/workflow.rattish

Raticode refuses a trigger the workflow couldn't run, such as one on a workflow that needs an input you didn't set. Pass inputs with --input NAME=JSON, or fill in Workflow inputs in the Studio.

Cron schedules

The expression has five fields: minute, hour, day of month, month, weekday. Weekdays follow crontab, so 0 and 7 are Sunday. Use a day of the month or a weekday, not both. The schedule follows the time zone you choose through daylight saving changes.

File changes

Point a trigger at a file or a folder. Relative paths start at the workflow's project. The workflow starts once the files stay quiet for the debounce time. A folder that never goes quiet still gets a run, after 60 seconds or ten debounce periods, whichever is longer. Raticode ignores changes inside .git, .raticode, .venv, __pycache__, and node_modules.

A workflow that writes into its own watched folder would start itself forever. After 10 runs in a row started by changes made during a run, Raticode turns the trigger off and records why.

A loop with a trigger-events source receives one item per changed file, up to 256 per run. Each item has type, kind (created, modified, deleted or moved), path, name, directory and trigger_id; the loop also provides index and event_json, and file_content when the loop sets include-content. Webhook runs deliver one item with type, trigger_id, received_at and the JSON payload (bodies up to 1 MiB). Cron runs deliver no events. Bind events with the trigger.events reference.

Webhooks

A webhook trigger gets a URL on 127.0.0.1 and a token. Raticode shows the token once and stores only a hash of it. Lost it? Replace it with New token or rotate-token.

curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"ref":"main"}' http://127.0.0.1:8767/rattish-hooks/TRIGGER_ID

The call returns 202 with started, queued, or skipped. Requests from a web page are refused. A loop with a trigger-events source receives the JSON body as payload. Treat it as untrusted input.

On a computer with other user accounts, keep the token out of command lines, which other accounts can read. curl -H @header-file reads the header from a private file.

The listener opens only while an enabled webhook trigger exists. If port 8767 is taken, the Triggers section says so and Raticode rattish triggers webhook-port PORT changes it.

If the workflow is already running

Each trigger has an explicit overlap policy, set with --overlap skip|queue|parallel on the CLI or in the Triggers section. It also counts runs you started by hand.

Policy	CLI value	What happens
Skip this run	skip	The start is dropped and recorded as skipped. This is the default.
Run once after it finishes	queue	One run waits. Later starts fold into it.
Run at the same time	parallel	Another run starts, up to 16 triggered runs at once.

Missed and failed runs

The Triggers section and Raticode rattish triggers history list every occurrence. --problems shows only failed, missed, skipped, and interrupted ones. A failed run shows the reason, and its full record is under Runs as usual.

A scheduled time more than a minute old when the scheduler reaches it counts as missed, whether the computer was asleep or nothing was running. Raticode records missed runs by default. Choose Show as missed and run once (--missed run_once) to also run once to catch up.

File changes and webhook calls can't be replayed. When the scheduler comes back after more than two minutes away, those triggers record a missed entry that gives the gap. A queued run that never started and a run cut off by a crash are recorded too.

Start at login

The Start at login switch, or Raticode rattish triggers login on, adds a per-user login entry that runs Raticode rattish triggers start. No Raticode window is needed. The computer still has to be on and logged in.

System	Login entry
Linux	~/.config/autostart/raticode-triggers-*.desktop
macOS	~/Library/LaunchAgents/com.raticode.triggers.*.plist
Windows	A script in your Startup folder

The entry keeps the PATH of the process that switched it on, so providers are found at login. Other environment variables aren't copied. A workflow that needs an API key from your shell profile should read it another way.

Only one process runs a data directory's triggers at a time. Open the desktop app while the background scheduler holds them and the app waits on standby, taking over if the scheduler exits. The app's Stop button can't reach a run the background scheduler started.

Commands

Command	Purpose
Raticode rattish triggers list [PATH]	Show triggers, next runs, and scheduler state
Raticode rattish triggers update ID ...	Change a trigger
Raticode rattish triggers enable ID / disable ID	Turn a trigger on or off
Raticode rattish triggers remove ID	Delete a trigger and its history
Raticode rattish triggers rotate-token ID	Replace a webhook token
Raticode rattish triggers history [ID]	Show recent runs
Raticode rattish triggers status	Show whether anything is running triggers
Raticode rattish triggers start	Run triggers in the foreground
Raticode rattish triggers login on|off|status	Manage Start at login
Raticode rattish triggers webhook-port [PORT]	Show or change the webhook port

Add and update commands also take --label, --disabled (create it turned off), --recursive/--no-recursive for folders, --overlap, and --format json. history --limit N shows up to 1,000 events; Raticode keeps the latest 200 per trigger. Debounce must be between 0.1 and 3,600 seconds.