`hiveloom schedule`

Creates and manages cron-style scheduled jobs for an agent. Each job has a prompt template and a schedule expression; at each fire, Hiveloom runs the prompt against the agent and persists the result.

Synopsis


hiveloom schedule [GLOBAL FLAGS] <COMMAND>

Global flags

Flag	Default	Description
`--tenant <TENANT>`	`default`	Tenant slug.
`--endpoint <URL>`	—	API endpoint.
`--token <TOKEN>`	—	Bearer token.
`--json`	—	JSON output.

Subcommands

Subcommand	Purpose
`create`	Create a scheduled job.
`list`	List jobs for an agent.
`show`	Show one job, including last run + next fire.
`pause`	Pause a job (kept on disk; stops firing).
`resume`	Resume a paused job.
`delete`	Delete a job.

Examples

Daily 09:00 summary fed to a summariser agent:


hiveloom schedule create summariser \
  --cron "0 9 * * *" \
  --context "Summarise yesterday's events."

The agent is the positional argument; you can pass either its name or its ID. The initial prompt is --context; if omitted, a default “you are running as a scheduled autonomous agent” message is used.

Inspect:


hiveloom schedule list summariser
hiveloom schedule show summariser <job-id>

Pause for the weekend, resume Monday:


hiveloom schedule pause  summariser <job-id>
hiveloom schedule resume summariser <job-id>

Delete:


hiveloom schedule delete summariser <job-id>

Cron format

Two formats are accepted:

5-field standard cron: minute hour dom month dow (e.g. 0 9 * * *).
6-field cron with seconds: second minute hour dom month dow (e.g. */30 * * * * * — every 30 seconds).

Schedules are evaluated in the timezone passed via --timezone at create time, defaulting to UTC. Use --one-time-at <RFC3339> instead of --cron for a single fire.

What happens at fire time

The in-process scheduler in hiveloom serve (see serve --no-scheduler) polls due jobs once per second. When a job fires, Hiveloom:

Loads the agent’s current version, capabilities, and the LLM credential matching its model family (anthropic for claude-*, otherwise openai).
Opens an internal conversation with surface_type=internal and surface_ref=scheduled-job:<job-id>.
Runs the agent loop with the supplied --context (or the default message) as the first user turn, decrypting the credential through the vault.
Marks the conversation concluded once the loop returns.

Per-agent concurrency is enforced: a second tick for the same agent is skipped while a previous run is still in flight. Jobs without a matching credential fail the run; the rest of the schedule keeps ticking.

hiveloom schedule