Two Ways to Schedule
3xcode has two independent scheduling mechanisms, aimed at two different needs. Both start from a sealed batch (see Batch Conversion & Sessions for creating and sealing one).
| In-app: `batch schedule` | Durable: `schedule add` | |
|---|---|---|
| Good for | A one-off "run this batch in 2 hours" wake-up | A recurring job, or anything that must survive a reboot |
| Survives closing the terminal | Yes, it runs as a detached background process | Yes |
| Survives a machine reboot or logout | No, it's an ordinary background process with nothing registered at the OS level | Yes, once `schedule install` has set up the OS-level tick |
| Repeats | No, one wake time per call | Yes, with `--repeat` |
| Holds quota while waiting | No, only at the actual wake time | No, only at the actual wake time |
In-App Scheduling: batch schedule
3xcode batch schedule takes a sealed batch and a wake time, and immediately spawns a detached background process that waits until that time, then runs the batch exactly like batch run would. It returns right away: you don't need to keep your terminal open, since the waiting process has already detached from it. What it does need is the machine itself to stay powered on and logged in, since there's nothing registered with the operating system: a reboot or logout ends the waiting process along with everything else running on the machine.
# Wake in 2 hours and run 3xcode batch schedule <session_id> <batch_id> --in +2h # Wake at an absolute time today (naive time = your local timezone) 3xcode batch schedule <session_id> <batch_id> --at 2026-07-16T21:00 # Cancel a scheduled batch before it wakes (idempotent) 3xcode batch schedule-cancel <session_id> <batch_id>
No quota held while waiting
The batch doesn't reserve any of your conversion quota until the moment it actually wakes and starts running, so a long wait doesn't tie up allowance you might need elsewhere in the meantime.
Cancel any time before it wakes
batch schedule-cancel moves a scheduled batch back to sealed, ready to run manually or schedule again. Calling it twice is safe.
Durable Scheduling: schedule
The 3xcode schedule command group is for schedules that need to survive a reboot, or that repeat on a cadence. schedule install registers a real operating-system mechanism, a launchd user agent on macOS, a crontab entry on Linux, or a scheduled task on Windows, that ticks once a minute and dispatches whatever is due. Because that tick is owned by the OS rather than by any one 3xcode process, it comes back on its own the next time your machine and user session are up, with nothing for you to manually restart.
| Command | What it does |
|---|---|
schedule install | Registers the recurring, once-a-minute OS tick that dispatches due schedules |
schedule uninstall | Removes the OS tick this CLI installed (only its own entry) |
schedule add <session_id> <batch_id> | Adds a durable schedule for a sealed batch, with `--at` or `--in`, and optionally `--repeat` |
schedule list | Lists durable schedules, optionally filtered to one session with `--session` |
schedule remove <schedule_id> | Cancels a durable schedule by its numeric ID (idempotent) |
schedule status | Whether the OS tick is installed, how many schedules are pending, and when the next one fires |
schedule run-due | Dispatches every currently-due schedule right now; this is what the installed tick calls every minute |
schedule daemon | A fallback that loops `run-due` on an interval while the command itself stays running, for environments where installing an OS-level tick isn't possible |
# One-time setup: register the OS-level tick (run once per machine) 3xcode schedule install # Add a durable, repeating schedule for a sealed batch 3xcode schedule add <session_id> <batch_id> --at 2026-07-17T02:00 --repeat daily # Check what's installed and what's pending 3xcode schedule status 3xcode schedule list # Remove a schedule, or the OS tick entirely 3xcode schedule remove 14 3xcode schedule uninstall
One tick, many schedules
You install the OS-level tick once per machine; every durable schedule you add afterward is dispatched by that same tick, no separate OS registration per schedule.
Repeating schedules
--repeat accepts hourly, daily, or every N unit (every 30m, every 2h, every 1d), for a batch you want to re-run on a cadence rather than once.
Time Formats
Both batch schedule and schedule add accept the same two ways of specifying a wake time.
| Flag | Format | Examples |
|---|---|---|
--at | ISO 8601. A value with no UTC offset is read as your local time; a value with an explicit offset (or `Z`) is honored exactly as given. | 2026-07-16T21:00 (local time) or 2026-07-16T21:00+05:30 (explicit offset) |
--in | A relative offset: an optional `+`, a number, then a unit of `s`, `m`, or `h` (no day unit) | +2m, 90m, +2h, +30s |
--repeat | (`schedule add` only) `hourly`, `daily`, or `every N unit` where unit is `s`, `m`, `h`, or `d` | hourly, daily, every 30m, every 2h |
A wake time has to resolve to the future: passing a time already in the past is rejected with a clear error rather than firing immediately.
Which One Should You Use
Use batch schedule when...
You want a quick, one-off delay (run this tonight, run this in 90 minutes) and you know your machine will stay on and logged in until then.
Use schedule add when...
The run needs to survive a reboot, needs to repeat on a cadence, or is important enough that you don't want it to depend on the machine staying up the whole time.