Routines

What this is

A routine is an alarm. When it is due, Frontpage starts the agent with the prompt you saved. You see the same work you would from asking in chat: send email, edit the site, read People, and anything else the agent already does.

It is not a module. There is no data-fp-routine widget and no frontpage modules key. Owners open Routines from the site menu on Growth and above.

Requires frontpage-host 0.1.22 or later. Older global installs report Unknown command: routines. Upgrade with npm i -g frontpage-host@latest. Then run frontpage help routines.

Which site

--site is the subdomain slug, the same value as frontpage use. It is not the public host, not a custom domain, and not a site id.

frontpage routines list --site newest
frontpage routines list --site acme

# Rejected. These are hosts, not slugs.
frontpage routines list --site newest.frontpage.host
frontpage routines list --site https://newest.frontpage.host

The staging host newest.frontpage.host belongs to the slug newest. Pass --site newest. A missing --site, and no frontpage use in this folder, exits 2 with No site selected. Run: frontpage use <subdomain> or pass --site <subdomain>.

A Starter site, including one you can open in the editor, still returns HTTP 403 The CLI is included on Scale. Exit 4. Nothing is written. Growth can use the site menu and the agent tools. The frontpage routines command itself is Scale, Enterprise, and internal, with the rest of the Public CLI.

Verbs

Command	What it does
list	Every routine on the site, paused and active. No routines. when the list is empty.
get <id>	One routine, including the prompt and the sentence.
add	Creates the routine and starts the clock. New routines are active.
set <id>	Changes only the flags you pass. Recomputes the next run. Does not change paused or active.
pause <id>	Stops the clock. The stored next run stays where it is.
resume <id>	Turns the clock back on and recomputes the next run from now.
run <id>	Enqueues the saved prompt once. Works while paused. Does not move the next run and does not unpause.
runs <id>	The fire log. Not the agent’s later result.
rm <id>	Deletes the routine and its fire log. An agent run that is already queued still finishes.

The id is the UUID from list or add. Put it after the verb, or pass --id <uuid>. A non-UUID exits 2 with Routine not found. before a request. --json works on every verb.

Add

add requires --name, --prompt, --cadence, and --timezone. The prompt is stored as you wrote it. Nothing is prefixed. Name is at most 80 characters. Prompt is at most 20,000.

frontpage routines add --site acme \
  --name "Weekday check" \
  --prompt "Review new form submissions and reply to each customer." \
  --cadence weekly \
  --weekdays tue,thu,fri \
  --hours 8am,12pm,4pm \
  --timezone America/Chicago

That is one routine. It counts as 1 of 10 and fires nine times a week. The stored hours are [8, 12, 16]. The stored weekdays are [2, 4, 5]. Sunday is 0. The sentence comes back as “Runs at 8:00 AM, 12:00 PM, and 4:00 PM every Tuesday, Thursday, and Friday, America/Chicago.” The next run is the soonest later pair: Tuesday at 8:00, then Tuesday at 12:00, then Tuesday at 4:00, then Thursday at 8:00.

Cadence	Required flags	Leave empty
hourly	--timezone	Do not pass --hours, --weekdays, or --month-days. It fires at minute 0 of every hour.
daily	--hours and --timezone	No weekdays. No month days.
weekly	--hours, --weekdays, and --timezone	No month days. At least one weekday.
monthly	--hours, --month-days, and --timezone	No weekdays. Days are 1 through 28. There is no 29, 30, or 31.

frontpage routines add --site acme --name "Hourly" --prompt "…" --cadence hourly --timezone UTC
frontpage routines add --site acme --name "Morning" --prompt "…" --cadence daily --hours 8am --timezone America/Chicago
frontpage routines add --site acme --name "The 1st and the 15th" --prompt "…" --cadence monthly --month-days 1,15 --hours 8am,6pm --timezone America/Chicago

Explicit UTC is valid when that is the zone you mean. Do not send UTC because the owner never named a zone. If they did not name one, ask. The command will not guess.

How to write hours and days

The minute is always 0. These are the forms the CLI accepts.

You pass	Stored
8, 8am, 8:00am	8
12pm, 12	12
12am	0
4pm	16
5pm, 6pm	17, 18
tue,thu,fri or 2,4,5	[2, 4, 5]. tues, thur, and thurs also work.
sun or 0	0

Several values are comma-separated with no spaces: 8am,12pm,4pm. 4:30pm is rejected locally, exit 2: Routines fire at minute 0. Got "4:30pm". --month-days 31 is rejected locally: Month day must be 1 through 28. Got "31". Weekdays on a daily routine are rejected by the API: Weekdays are only used for a weekly routine.

Set

set patches. Omitted flags stay as they are. The next run is recomputed from now, even if the routine is paused. Status does not change.

frontpage routines set --site acme <id> --hours 9am,5pm
frontpage routines set --site acme <id> --prompt "Look at yesterday’s orders and write down what sold."
frontpage routines set --site acme <id> --timezone America/New_York

Changing --cadence daily while weekdays are still stored fails with Weekdays are only used for a weekly routine. Clear them in the same command:

frontpage routines set --site acme <id> --cadence daily --hours 8am --weekdays ""

The same rule applies the other way. A weekly routine needs --weekdays. A monthly routine needs --month-days, and an hourly routine needs the three lists empty (--hours "" --weekdays "" --month-days "").

Pause, resume, run, and delete

frontpage routines pause --site acme <id>
frontpage routines resume --site acme <id>
frontpage routines run --site acme <id>
frontpage routines rm --site acme <id>

• pause sets status to paused and leaves nextRunAt unchanged. The tick will not enqueue it.
• resume sets status to active and sets nextRunAt to the next future slot. Slots that passed while it was paused are not replayed.
• run enqueues the saved prompt once, whether the routine is paused or active. Status stays what it was. nextRunAt stays what it was. A second run enqueues a second agent turn and writes a second fire-log row.
• The agent run uses origin routine, path /, and the prompt byte for byte.
• rm returns deleted set to that id. The fire log for that routine goes with it. An agent run already queued is not canceled.
• get after rm is HTTP 404 Routine not found.

A site can hold 10 routines, paused and active together. The 11th is HTTP 409, exit 3: This site can have 10 routines. Delete one to add another.

The fire log

frontpage routines runs --site acme <id>

Each row is one attempt to enqueue. trigger is manual for run and schedule for the clock. outcome is fired, failed, or skipped. fired means enqueue returned an agent run id. It does not mean the agent later succeeded, committed, or sent anything. skipped means the clock reached the slot and did not enqueue, with skipReason not_entitled or not_live. The next run still advances. failed means enqueue threw. The reason is on the row.

The clock runs every 15 minutes. A fire up to 15 minutes after the scheduled minute still counts. If several slots passed while the clock was down, it enqueues once for the latest due slot and jumps to the next future slot. It does not replay the missed ones.

A missing local hour, such as 2:00 AM on a spring-forward morning, uses the next valid time. On the fall-back hour, the earlier instant is the one that fires.

--json

Success is ok: true and command: "routines". add, get, set, pause, and resume return data.routine:

{
  "id": "…",
  "name": "Weekday check",
  "prompt": "…",
  "cadence": "weekly",
  "timezone": "America/Chicago",
  "hours": [8, 12, 16],
  "weekdays": [2, 4, 5],
  "monthDays": [],
  "status": "active",
  "nextRunAt": "2026-09-22T13:00:00.000Z",
  "lastRunAt": null,
  "sentence": "Runs at 8:00 AM, 12:00 PM, and 4:00 PM every Tuesday, Thursday, and Friday, America/Chicago.",
  "createdAt": "…"
}

list returns data.routines. run returns outcome, agentRunId, and routineId. runs returns data.runs. rm returns data.deleted. Times are UTC ISO strings. The sentence is the local-time description.

Errors

You did this	Result
Missing --name, --prompt, --cadence, or --timezone on add	Exit 2, local. add needs --name, --prompt, --cadence, and --timezone.
Unknown flag, such as --nope	Exit 2, local. Unknown flag: --nope. Run: frontpage help routines
--hours 4:30pm or hour 24	Exit 2, local. Minute must be 0. Hours are 0 through 23.
Bad weekday, or month day outside 1–28	Exit 2, local. Nothing is written.
Lists that do not match the cadence	HTTP 400, exit 2. The row is unchanged.
11th routine	HTTP 409, exit 3. This site can have 10 routines. Delete one to add another.
Site plan has no Public CLI	HTTP 403, exit 4. The CLI is included on Scale.
Plan drops below Growth	The site menu row hides and the clock writes skipped / not_entitled instead of enqueueing. Rows stay. The CLI already stopped at the Scale check above.
Unknown slug, or a slug you are not a member of	HTTP 404 Site not found.
Viewer role on add, set, pause, resume, run, or rm	HTTP 403. list, get, and runs still work.

Words the owner might use

When you are turning a sentence into flags, use this map. Do not split one sentence into several routines.

They say	Flags
Every hour	--cadence hourly. No hour list.
Every morning	--cadence daily --hours 8am
Every afternoon	--cadence daily --hours 2pm. The word “afternoon” with no clock time is hour 14. The editor preset labeled Afternoon is 4:00 PM, which is --hours 4pm.
Every evening	--cadence daily --hours 6pm
Every Monday morning	--cadence weekly --weekdays mon --hours 8am
8am, 12pm, and 4pm every Tuesday, Thursday, and Friday	--cadence weekly --weekdays tue,thu,fri --hours 8am,12pm,4pm
The 1st and the 15th at 8am and 6pm	--cadence monthly --month-days 1,15 --hours 8am,6pm

An unnamed weekly or monthly time defaults to 8:00 AM. Hourly has no default hour.