`/analyze schedule` — scheduled runs reference¶

/analyze schedule is the subgroup that owns one-shot scheduled metadata runs: the user picks a DB profile + LLM profile + scope + fire time, AMX persists the schedule, and a small daemon (or a manual tick) fires it when due. The walkthrough for picking a cadence and recovering missed fires lives in Scheduled runs; this page is the subcommand reference.

Every subcommand is typed inside the AMX REPL, slash-form, exactly the way /analyze run and /analyze apply are. There is no top-level amx <cmd> invocation for this group — the namespace is REPL-only by design, so tab completion and history pick up every subcommand.

Prerequisites¶

An AMX session (amx).
At least one DB profile + one LLM profile (/db-profiles, /llm).
For automatic firing: the AMX scheduler daemon installed (/analyze schedule install-daemon). Manual tick works without the daemon.

Subcommand table¶

Subcommand	Purpose
`/analyze schedule add`	Guided wizard. Picks DB profile, LLM profile, scope (all / schemas / tables / columns), and a fire time. Stores the row in `~/.amx/history.db`. Pass `--kind cache_refresh` (with optional `--deep`) to schedule a catalog cache sync instead of an LLM analyze run — see Catalog cache → Scheduled refreshes for the cache-side semantics. The `--cron` flag promotes a one-shot schedule into a recurring one (`'0 /6 * *'`); the `--missing-only` flag (analyze only) limits the run to columns that lack a description.
`/analyze schedule list`	Table listing. Status filters: `--status pending\|fired\|paused\|failed`. Each row carries `id`, scope, next-fire timestamp, and last-fire result.
`/analyze schedule show <id>`	Full record: scope spec, profile pins, prompt detail, alternatives count, last `analyze.run` row id.
`/analyze schedule pause <id>`	Mark the schedule as paused. The next `tick` skips it without dropping the row.
`/analyze schedule resume <id>`	Inverse of `pause`. Re-arms the row at the originally scheduled time (no catch-up unless `--catch-up`).
`/analyze schedule rm <id>`	Delete the schedule. Past `analyze.run` rows it produced stay in `/history`.
`/analyze schedule run-now <id>`	Fire immediately, regardless of next-fire timestamp. Pass `--background` to detach from the REPL.
`/analyze schedule tick`	Engine command — one stateless pass over due rows. Honors `AMX_SKIP_BOOTSTRAP_TICK=1` when the REPL bootstraps so a fresh shell doesn't fire the queue twice.
`/analyze schedule status`	Engine command — daemon presence (systemd / launchd / Task Scheduler), missed-fire count, next-fire window.
`/analyze schedule install-daemon`	Install a per-user daemon. Detects the host OS: launchd plist on macOS, systemd `--user` unit on Linux, Scheduled Task on Windows. Idempotent — re-running upgrades the unit in place.
`/analyze schedule uninstall-daemon`	Remove the daemon unit. Existing schedules stay; the next `tick` is your responsibility.

Scope spec¶

/analyze schedule add writes a compact scope spec that the next tick replays verbatim through the orchestrator. The spec mirrors /analyze run exactly:

Spec	Meaning
`all`	Every schema reachable through the picked DB profile.
`schema:public,sales`	Only the listed schemas.
`table:public.users,sales.orders`	Only the listed tables (any schema-qualified pair).
`column:public.users.email,public.users.first_name`	Only the listed columns.

The wizard offers the cascading picker (Profile → DB → Schema → Table → Column) so you usually don't type the spec by hand — see Multi-profile scoping.

Daemon vs manual tick¶

> /analyze schedule install-daemon
✓ launchd plist installed at ~/Library/LaunchAgents/com.amxcli.scheduler.plist
✓ Daemon loaded (bootstrap + enable + kickstart). Next tick in <60s.

> /analyze schedule status
Daemon: loaded (launchd, last tick 14s ago)
  log: ~/Library/Logs/amx-scheduler.log
       size 12,432 bytes · mtime 2026-05-28 09:14:11
Schedules: 4 active, 0 paused, 1 failed (id 7 — see /analyze schedule show 7)
Missed fires (closed AMX): 0

install-daemon on macOS Big Sur and later uses the modern launchctl bootout (to wipe any stale registration) followed by bootstrap / enable / kickstart. The deprecated launchctl load path silently no-ops on these OS versions, so AMX no longer uses it — the daemon ends up actually loaded instead of installed-but-dormant.

status distinguishes two states that previously looked the same:

Installed — the plist / unit file exists on disk but the OS scheduler does not know about it. Schedules will not fire. Most often happens after a manual file edit or an interrupted install; re-run install-daemon to repair.
Loaded — the plist / unit is registered with launchctl (or the platform equivalent) and the next tick is scheduled.

The status output also surfaces log_size_bytes and log_mtime from the daemon log so you can tell at a glance whether the daemon has been writing — a stale log_mtime paired with a small size usually means installed-but-not-loaded.

Without the daemon, every tick is your responsibility — either invoke /analyze schedule tick manually inside the REPL or wire your own cron. The engine is stateless between ticks: persistence lives in ~/.amx/history.db, the tick re-reads the queue on every call, so you can mix daemon and manual ticks without double-firing (the row carries an advisory lock for the duration of its run).

When AMX was closed at the scheduled time, the next REPL bootstrap surfaces the missed fire — the bootstrap honors AMX_SKIP_BOOTSTRAP_TICK=1 if you want a shell that opens without firing the catch-up batch.

Studio parity¶

Every command on this page has a 1:1 counterpart in AMX Studio → Schedules. The Studio surface adds an edit dialog (/runs/schedules), one-click daemon install / uninstall buttons, and a live status ticker.

Verify¶

> /analyze schedule list
ID  STATUS   NEXT FIRE              DB        SCOPE
1   pending  2026-05-14 03:00 UTC   prod-pg   schema:sales
2   pending  2026-05-14 03:00 UTC   prod-pg   table:public.users,public.orders
3   paused   —                      analytics column:public.events.payload

> /analyze schedule status
Daemon: loaded · 4 active · next fire in 8h 12m

Troubleshooting¶

Symptom	Fix
`Daemon: not installed` even after install-daemon	Re-run from a TTY (launchd / systemd refuse to load when stdin isn't a terminal); check the OS-native log (`launchctl print user/<uid>/com.amxcli.scheduler`).
Schedule fires twice on the same minute	Two daemons installed (e.g. via cron and `install-daemon`). Run `/analyze schedule uninstall-daemon` and rely on one.
`next fire in -3h` (past timestamp)	The host clock drifted or the schedule sat through a long AMX-closed window — `/analyze schedule run-now <id>` to fire once, then resume.
Spec rejected with "unknown column"	The DB schema drifted since the schedule was added. `/analyze schedule show <id>` to inspect, `rm` + re-`add` to rebuild.

/analyze schedule — scheduled runs reference¶