# obss schedules - Obss

CLI
obss schedules
Preview, create, change, pause, resume, launch, and delete schedules that launch a finished experiment again on a cron cadence, from the CLI.
A schedule launches a finished experiment again on a cron cadence, so you can track agents over time. Each launch uses the project as it is then: the latest tasks, treatments, files, and machines. Who a schedule runs as and when Obss pauses it are on
Schedules
.
Rules for every change
These rules hold in the CLI and the plugin.
Launch check.
A create, a resume, or a change to the experiment,
--cron
, or
--time-zone
first checks the launch as you. If anything blocks it, the command refuses with
schedule_launch_blocked
and lists every blocker with its fix link, the same ones
obss schedules preview
shows. When the check passes, the schedule runs as you.
Paused schedules stay paused.
A passing check clears the reason Obss paused a schedule, but it stays paused until you resume it.
obss schedules update
prints the resume command.
One launch at a time.
obss schedules launch
refuses with
experiment_schedule_run_active
while the schedule’s last experiment still runs.
50 active schedules.
A create or resume past that returns
schedule_limit_reached
.
Lock versions.
Every change after create takes the
--lock-version
from
obss schedules get
, so two people can’t overwrite each other’s edits; a stale value fails with
schedule_changed
.
Attempt IDs.
Create and update take an
--attempt-id
, so a retry after a lost response is the same change. Reusing an ID for a different change fails with
schedule_attempt_reused
.
Time zones
The cron has five fields (minute, hour, day of month, month, day of week) and always reads in the schedule’s time zone. For example,
0 9 * * 1-5
is 9:00 AM on weekdays. The minute must be
0
,
15
,
30
, or
45
, so a schedule launches at most once an hour, on the quarter hour.
--time-zone
(with a hyphen) takes an IANA name, such as
America/New_York
, or
UTC
. It’s required on create because AI assistants and CI machines often run in UTC, and the error suggests your machine’s time zone.
You pass
Obss
An abbreviation, such as
EST
or
BST
Refuses it and asks for an IANA name, because an abbreviation can name a zone you didn’t mean
GMT
or
Etc/GMT
Stores
UTC
An older name, such as
US/Pacific
or
Asia/Calcutta
Stores its current name, such as
America/Los_Angeles
or
Asia/Kolkata
obss schedules preview
Preview when a new or changed schedule launches, the runs it uses, and what would stop it.
obss
schedules
preview
[experiment-id] [flags]
Plugin (MCP) tool:
preview_schedule
Arguments
Argument
Description
[experiment-id]
The finished
exp_
experiment to launch. Required for a new schedule. With
--schedule-id
, leave it out to keep the schedule’s experiment.
Flags
Flag
Type
Default
Description
--cron
string
Five cron fields; the minute is
0
,
15
,
30
, or
45
. Required for a new schedule.
--time-zone
string
The IANA time zone the cron reads in, or
UTC
. Required for a new schedule.
--schedule-id
string
Preview a change to this
sch_
schedule. What you leave out keeps the schedule’s own value.
Also takes the
global flags
.
Examples
Preview a new weekday schedule:
obss
schedules
preview
exp_8f2c41d0
--cron
"0 9 * * 1-5"
--time-zone
America/Los_Angeles
Preview moving a schedule one hour later:
obss
schedules
preview
--schedule-id
sch_c0a9f311
--cron
"0 10 * * 1-5"
Result fields
Field
Description
cadenceDescription
The cadence in plain words.
timeZone
,
timeZoneLabel
The time zone that Obss stores, and its name in plain words.
nextLaunches
The next 3 launches.
runsPerLaunch
,
runsPer30Days
,
shortfall
The runs the schedule uses, and when your runs fall short, as
Schedule fields
describes.
blockers
Everything that would stop a launch now, each with a
code
, a
message
, and an
action
link that fixes it. Empty when the schedule can launch.
blocker
The first of
blockers
, kept for older CLI releases. Use
blockers
.
Notes
The preview changes nothing and checks the launch as you. A paused schedule’s preview shows the launches it would have once you resume it.
obss schedules create
Schedule a finished experiment to launch again on a cadence.
obss
schedules
create
<
experiment-i
d
>
--cron
<
cro
n
>
--time-zone
<
zon
e
>
[flags]
Plugin (MCP) tool:
manage_schedule
Each scheduled launch spends runs from your organization’s balance. In Ask Obss, you approve each call.
Arguments
Argument
Description
<experiment-id>
Required. The finished
exp_
experiment to launch.
Flags
Flag
Type
Default
Description
--cron
string
Required. Five cron fields; the minute is
0
,
15
,
30
, or
45
.
--time-zone
string
Required. The IANA time zone the cron reads in, or
UTC
.
--name
string
The experiment’s name
The schedule’s name, up to 120 characters.
--attempt-id
string
An ID you choose, so that a retry doesn’t repeat the change. 16 to 200 letters, digits,
-
, or
_
. Without it, the CLI makes one and prints it on stderr.
Also takes the
global flags
.
Examples
Launch the experiment again at 9:00 AM Pacific every weekday:
obss
schedules
create
exp_8f2c41d0
--cron
"0 9 * * 1-5"
--time-zone
America/Los_Angeles
--name
"Weekday checkout"
Result fields
Field
Description
schedule
The schedule:
scheduleId
,
name
,
status
,
needsAttention
,
pauseReason
,
cron
,
timeZone
,
cadenceDescription
,
timeZoneLabel
,
nextRunAt
,
sourceExperiment
,
runsAs
,
runsPerLaunch
,
runsPer30Days
,
shortfall
,
lastResult
,
skippedInARow
,
lastExperiment
,
lockVersion
, and
dashboardUrl
.
Schedule fields
describes each one.
Notes
The schedule runs as you.
obss schedules list
List the project’s schedules.
obss
schedules
list
[flags]
Plugin (MCP) tool:
list_schedules
Flags
Flag
Type
Default
Description
--query
string
Search text, up to 200 characters, such as part of a schedule’s name.
--status
active
,
paused
Schedules with this status.
--experiment-id
string
Schedules that launch this
exp_
experiment again.
--launched-experiment-id
string
The schedule that launched this
exp_
experiment.
--limit
integer
50
Results per page, up to 200 (default 50).
--cursor
string
The
nextCursor
from the previous page.
Also takes the
global flags
.
Examples
Find the schedule that launched an experiment:
obss
schedules
list
--launched-experiment-id
exp_d41a7c09
Result fields
Field
Description
schedules
Each schedule:
scheduleId
,
name
,
status
,
needsAttention
,
pauseReason
,
cron
,
timeZone
,
cadenceDescription
,
timeZoneLabel
,
nextRunAt
,
sourceExperiment
,
runsAs
,
runsPerLaunch
,
runsPer30Days
,
shortfall
,
lastResult
,
skippedInARow
,
lastExperiment
,
lockVersion
, and
dashboardUrl
.
Schedule fields
describes each one.
hasMore
,
nextCursor
Whether another page exists, and the cursor for it.
Notes
Text output shows
needs attention
for a schedule that Obss paused. To list the experiments a schedule launched, run
obss experiments list --schedule-id
.
obss experiments get
also names the schedule that launched an experiment, in
lineage.schedule
.
obss schedules get
Read one schedule.
obss
schedules
get
<
schedule-i
d
>
[flags]
Plugin (MCP) tool:
get_schedule
Arguments
Argument
Description
<schedule-id>
Required. The
sch_
schedule ID.
Takes only the
global flags
.
Examples
Read the
lockVersion
before a change:
obss
schedules
get
sch_c0a9f311
--output
json
Result fields
Field
Description
schedule
The schedule:
scheduleId
,
name
,
status
,
needsAttention
,
pauseReason
,
cron
,
timeZone
,
cadenceDescription
,
timeZoneLabel
,
nextRunAt
,
sourceExperiment
,
runsAs
,
runsPerLaunch
,
runsPer30Days
,
shortfall
,
lastResult
,
skippedInARow
,
lastExperiment
,
lockVersion
, and
dashboardUrl
.
Schedule fields
describes each one.
Notes
Text output shows the status, the cadence, the next launch in the schedule’s time zone, the runs it uses, who it runs as, the last experiment, and the lock version.
obss schedules update
Change a schedule’s name, cadence, time zone, or experiment.
obss
schedules
update
<
schedule-i
d
>
--lock-version
<
n
>
[flags]
Plugin (MCP) tool:
manage_schedule
Each scheduled launch spends runs from your organization’s balance. In Ask Obss, you approve each call.
Arguments
Argument
Description
<schedule-id>
Required. The
sch_
schedule ID.
Flags
Flag
Type
Default
Description
--lock-version
integer
Required. The
lockVersion
from
obss schedules get
.
--name
string
A new name, up to 120 characters. Without it, a schedule still named after its experiment takes the new experiment’s name when you change the experiment.
--cron
string
Five cron fields; the minute is
0
,
15
,
30
, or
45
.
--time-zone
string
The IANA time zone the cron reads in, or
UTC
.
--experiment-id
string
A finished
exp_
experiment to launch instead.
--attempt-id
string
An ID you choose, so that a retry doesn’t repeat the change. 16 to 200 letters, digits,
-
, or
_
. Without it, the CLI makes one and prints it on stderr.
Pass at least one of
--name
,
--cron
,
--time-zone
, or
--experiment-id
. Also takes the
global flags
.
Examples
Move a schedule to 10:00 AM:
obss
schedules
update
sch_c0a9f311
--lock-version
3
--cron
"0 10 * * 1-5"
Result fields
Field
Description
schedule
The schedule:
scheduleId
,
name
,
status
,
needsAttention
,
pauseReason
,
cron
,
timeZone
,
cadenceDescription
,
timeZoneLabel
,
nextRunAt
,
sourceExperiment
,
runsAs
,
runsPerLaunch
,
runsPer30Days
,
shortfall
,
lastResult
,
skippedInARow
,
lastExperiment
,
lockVersion
, and
dashboardUrl
.
Schedule fields
describes each one.
Notes
The command changes only the flags you pass, and renaming alone doesn’t change who the schedule runs as. A change to the experiment,
--cron
, or
--time-zone
gets the
launch check
; preview it first with
obss schedules preview --schedule-id
.
obss schedules pause
Pause a schedule. It does not launch until you resume it.
obss
schedules
pause
<
schedule-i
d
>
--lock-version
<
n
>
[flags]
Plugin (MCP) tool:
manage_schedule
In Ask Obss, you approve each call.
Arguments
Argument
Description
<schedule-id>
Required. The
sch_
schedule ID.
Flags
Flag
Type
Default
Description
--lock-version
integer
Required. The
lockVersion
from
obss schedules get
.
Also takes the
global flags
.
Examples
obss
schedules
pause
sch_c0a9f311
--lock-version
3
Result fields
Field
Description
schedule
The schedule:
scheduleId
,
name
,
status
,
needsAttention
,
pauseReason
,
cron
,
timeZone
,
cadenceDescription
,
timeZoneLabel
,
nextRunAt
,
sourceExperiment
,
runsAs
,
runsPerLaunch
,
runsPer30Days
,
shortfall
,
lastResult
,
skippedInARow
,
lastExperiment
,
lockVersion
, and
dashboardUrl
.
Schedule fields
describes each one.
Notes
Pausing a paused schedule changes nothing.
obss schedules resume
Resume a paused schedule. It runs as you from its next launch time.
obss
schedules
resume
<
schedule-i
d
>
--lock-version
<
n
>
[flags]
Plugin (MCP) tool:
manage_schedule
Each scheduled launch spends runs from your organization’s balance. In Ask Obss, you approve each call.
Arguments
Argument
Description
<schedule-id>
Required. The
sch_
schedule ID.
Flags
Flag
Type
Default
Description
--lock-version
integer
Required. The
lockVersion
from
obss schedules get
.
Also takes the
global flags
.
Examples
obss
schedules
resume
sch_c0a9f311
--lock-version
4
Result fields
Field
Description
schedule
The schedule:
scheduleId
,
name
,
status
,
needsAttention
,
pauseReason
,
cron
,
timeZone
,
cadenceDescription
,
timeZoneLabel
,
nextRunAt
,
sourceExperiment
,
runsAs
,
runsPerLaunch
,
runsPer30Days
,
shortfall
,
lastResult
,
skippedInARow
,
lastExperiment
,
lockVersion
, and
dashboardUrl
.
Schedule fields
describes each one.
Notes
Resume runs the
launch check
. If something blocks it, the schedule stays paused and
details.blockers
lists every blocker, with the same fields as the preview’s
blockers
; fix them and run the same command again. Resuming never starts a launch right away, and resuming an active schedule changes nothing.
obss schedules launch
Launch the schedule’s experiment now, as you.
obss
schedules
launch
<
schedule-i
d
>
[flags]
Plugin (MCP) tool:
rerun_experiment
with
schedule_id
This command spends runs from your organization’s balance. In Ask Obss, you approve each call.
Arguments
Argument
Description
<schedule-id>
Required. The
sch_
schedule ID.
Flags
Flag
Type
Default
Description
--attempt-id
string
An ID you choose, so that a retry doesn’t repeat the change. Up to 100 characters. Without it, the CLI makes one and prints it on stderr.
Also takes the
global flags
.
Examples
obss
schedules
launch
sch_c0a9f311
--output
json
Result fields
The same fields as
obss experiments launch
:
launchId
,
experimentId
,
status
,
runCount
, and
dashboardUrl
. Follow the launch with
obss experiments watch
.
Notes
The launch uses the latest tasks, under the schedule’s name, and doesn’t move the next scheduled launch. It refuses with
experiment_schedule_run_active
while the schedule’s last experiment still runs (see
Rules for every change
).
obss schedules delete
Delete a schedule. The experiments it launched stay.
obss
schedules
delete
<
schedule-i
d
>
--lock-version
<
n
>
[flags]
Plugin (MCP) tool:
delete_schedule
The schedule stops launching and is deleted. You can’t undo it.
Arguments
Argument
Description
<schedule-id>
Required. The
sch_
schedule ID.
Flags
Flag
Type
Default
Description
--lock-version
integer
Required. The
lockVersion
from
obss schedules get
.
--yes
boolean
false
Confirm without a prompt. Required with
--output json
or without a terminal.
Also takes the
global flags
.
Examples
obss
schedules
delete
sch_c0a9f311
--lock-version
4
--yes
--output
json
Result fields
Field
Description
status
deleted
.
scheduleId
The deleted schedule’s
sch_
ID.
Notes
Deleting a schedule that is already deleted returns
schedule_not_found
.
Schedule fields
obss schedules get
,
list
,
create
,
update
,
pause
, and
resume
return these fields.
obss schedules preview
returns the cadence, run, and shortfall fields.
Field
Description
scheduleId
,
name
The
sch_
ID and the name.
status
active
or
paused
.
needsAttention
true
when Obss paused the schedule. The dashboard shows
Needs attention
.
pauseReason
Why Obss paused it: a
code
, a
message
, and an
action
link that fixes it.
cron
,
timeZone
The cadence, and the IANA time zone that Obss stores.
cadenceDescription
,
timeZoneLabel
The same in plain words, such as “Every weekday at 9:00 AM” and “Pacific Time (Los Angeles)”.
nextRunAt
The next launch.
null
while paused.
sourceExperiment
The experiment it launches:
experimentId
and
label
.
runsAs
The person it runs as:
name
and
email
.
runsPerLaunch
The runs each launch uses.
runsPer30Days
The runs the next 30 days use, not a monthly average.
0
while paused, or when no launch falls in the next 30 days.
shortfall
When your runs fall short (next table).
null
while your runs cover the launches, or while the schedule is paused.
lastResult
What happened at the last scheduled launch:
outcome
(
launched
,
skipped
, or
failed
), a
code
and
message
, and
scheduledFor
.
skippedInARow
Launches skipped in a row because the last experiment was still running. After 3, the schedule’s owners get a
Schedule skipping launches
notification.
lastExperiment
The last experiment it launched:
experimentId
,
label
, and
status
.
lockVersion
The version to pass as
--lock-version
on the next change.
dashboardUrl
The schedule’s page in the dashboard.
shortfall
field
Description
at
This schedule’s first launch that your runs do not cover.
runsShort
The runs to add before that launch.
availableRuns
The runs you have now.
launchesCovered
The launches your runs cover.
runsToAdd
The runs that cover every scheduled launch until
until
.
until
The end of the period that
runsToAdd
covers.
untilReset
true
when
until
is the next reset of your runs.
message
The shortfall in plain words.
action
A link to
Organization settings → Usage & billing
, where you
add runs
.
In
obss notifications list
, a schedule’s paused, skipping, and short-of-runs notifications, and the problem notifications of the experiments it launched, carry its
scheduleId
. To read the runs or frictions of everything a schedule launched, pass
--schedule-id
to
obss runs list
or
obss frictions list
.
Next steps
Schedules
How schedules launch, who they run as, and when they pause.
Track results over time
Use a schedule to see how agents change from week to week.
obss experiments
Watch the experiments a schedule launches.
experiments
runs and results
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform