# kindgi schedules > Run agents and flows on a schedule: create, list, get, update, pause, resume, run-now, fires, take-ownership, unregister ## `kindgi schedules` **Synopsis** ```sh signature kindgi schedules ``` Run agents and flows on a schedule: create, list, get, update, pause, resume, run-now, fires, take-ownership, unregister. **Commands** | Command | Description | | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`kindgi schedules list`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules-list) | List schedules. | | [`kindgi schedules get`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules-get) | Fetch a schedule, with its next occurrences when asked. | | [`kindgi schedules create`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules-create) | Run an agent or a flow on a schedule, or start Improve runs on an agent (--improve). | | [`kindgi schedules update`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules-update) | Change a schedule: when it runs, what it runs, its policies, or the tools its runs may call unattended. | | [`kindgi schedules pause`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules-pause) | Pause a schedule: it stops running until resumed. | | [`kindgi schedules resume`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules-resume) | Resume a paused schedule from its next occurrence (the paused ones are not run). | | [`kindgi schedules run-now`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules-run-now) | Run a schedule now, outside its schedule (its next occurrence is unchanged). | | [`kindgi schedules fires`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules-fires) | A schedule's history, newest first: each time it fired, the run it started, or why it was skipped, refused or failed. | | [`kindgi schedules take-ownership`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules-take-ownership) | Become a schedule's owner, so its runs act as you from the next fire: for a schedule whose owner left, or to make it shared (--run-as=project, the project's own account becomes the owner; --run-as=\, that service account) or yours. | | [`kindgi schedules unregister`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules-unregister) | Remove a schedule: it stops running. | **See also** - [Ask before a tool runs](https://docs.kindgi.com/v0.2.0/guides/approvals/ask-before-a-tool-runs.md) - [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md) ### `kindgi schedules list` **Synopsis** ```sh signature kindgi schedules list [--project=] [--status=active|paused] [--limit=] [--cursor=] ``` List schedules. **Options** | Option | Default | Description | | ------------------- | -------------------- | ---------------------------------------------------------------- | | `--cursor ` | none | Resume after this cursor, from the previous page's `nextCursor`. | | `--limit ` | `25` (at most `100`) | The most to return (default 25, at most 100). | | `--project ` | none | Only this project's schedules. | | `--status ` | none | Only `active` or only `paused` schedules. | Every command also takes the [global flags](https://docs.kindgi.com/v0.2.0/reference/cli.md#global-flags). **Examples** From [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md): ```sh pnpm exec kindgi schedules list --status=active pnpm exec kindgi schedules list --project= ``` **See also** - [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md) - [`kindgi schedules`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules) ### `kindgi schedules get` **Synopsis** ```sh signature kindgi schedules get [--upcoming=] ``` Fetch a schedule, with its next occurrences when asked. **Options** | Option | Default | Description | | -------------------- | ------- | --------------------------------------------- | | `--upcoming ` | none | Also show the next N times it runs (1 to 20). | Every command also takes the [global flags](https://docs.kindgi.com/v0.2.0/reference/cli.md#global-flags). **Examples** Fetch a schedule with its next five run times. ```sh kindgi schedules get --upcoming=5 ``` From [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md): ```sh pnpm exec kindgi schedules get --upcoming=3 ``` **See also** - [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md) - [`kindgi schedules`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules) ### `kindgi schedules create` **Synopsis** ```sh signature kindgi schedules create --cron= (--agent= [--agent-version=] | --flow= --flow-version= | --improve= --project= [--segment=]…) [--timezone=] [--input=] [--project=] [--catch-up=latest|skip] [--overlap=skip|allow] [--starting-deadline=] [--label=] [--run-as=|project] [--allow-unattended=]… ``` Run an agent or a flow on a schedule, or start Improve runs on an agent (--improve). It's personal: its runs act as you, and only you or a project admin can change it. With `--run-as=project`, it's shared and acts as the project's own account; with `--run-as=`, as that service account. Who it acts as is checked again at every run; its runs are in your project's runs, naming the schedule. **Options** | Option | Default | Description | | ----------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--agent ` | none | Run this agent (at its live version, else the latest). | | `--agent-version ` | none | With --agent: run this exact version. | | `--allow-unattended ` | none (a tool that waits for a person still waits) | A tool, by id, whose calls in this schedule's runs needn't wait for a person's yes, though the tool asks for one when no person started the run (repeatable; only tools its agent or flow calls, no wildcard). Needs `admin` on the schedule's project. The tenant's and the agent's approval rules still apply. Repeatable. | | `--catch-up ` | `latest` | After a gap (the runtime was down): `latest` runs once for the latest missed time (default); `skip` drops them. | | `--cron ` | required | A cron expression: `0 7 * * 1-5` (07:00 on weekdays), `@daily`, … | | `--flow ` | none | Run this flow (with --flow-version). | | `--flow-version ` | none | With --flow: the flow version to run. | | `--improve ` | none | Start Improve runs on this agent (instead of running it), when enough new corrections marking answers wrong have come in: for the project (--project), or a segment of it (--segment). `--input` takes the Improve options, `threshold` and `monthlyCapUsd`. | | `--input ` | `{}` | The input each run gets, as JSON or `@`. An agent needs `{"userMessage": "…"}`; a flow takes its own input (default `{}`); --improve takes its Improve options (`{"tiers": ["settings"], "threshold": {"judgments": 5, "runs": 3, "judges": 2}, "monthlyCapUsd": 20}`, the defaults). | | `--label ` | none | A short label. | | `--overlap ` | `skip` | While the previous run is still going: `skip` (default) or `allow` another run. | | `--project ` | the tenant's Default project | The schedule's project, by id (default: the tenant's Default project). | | `--run-as ` | none (you own the schedule) | A service account, by id, or `project`: the schedule's owner, so its runs act as that account from the next fire (not as you). `project` runs it as the project's own account, made the first time, and takes `admin` on the project. The project's own account runs only what the project's editors can. A named account takes `act_as`, and needs a role that runs what the schedule runs (editor on the target's project). Omit it to own the schedule yourself. | | `--segment ` | none | With --improve and --project: a segment of the project, `key:value`; repeat it in order, coarse to fine. Repeatable. | | `--starting-deadline ` | `600` (seconds) | Seconds a run may start late and still count as on time (default 600). | | `--timezone ` | `UTC` | An IANA timezone, such as America/Toronto (default UTC). | Every command also takes the [global flags](https://docs.kindgi.com/v0.2.0/reference/cli.md#global-flags). **Examples** From [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md): ```sh pnpm exec kindgi schedules create --agent=acme.order-desk --cron="0 7 * * 1-5" --timezone=America/Toronto \ pnpm exec kindgi schedules create --cron="0 3 * * *" --improve=acme.rank.scorer --project= --segment=company:acme \ ``` **See also** - [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md) - [`kindgi schedules`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules) ### `kindgi schedules update` **Synopsis** ```sh signature kindgi schedules update [--cron=] [--timezone=] [--input=] [--agent= [--agent-version=] | --flow= --flow-version= | --improve= --project= [--segment=]…] [--catch-up=…] [--overlap=…] [--starting-deadline=] [--label=] [--allow-unattended=|none]… ``` Change a schedule: when it runs, what it runs, its policies, or the tools its runs may call unattended. A flag left out keeps the schedule's value. **Options** | Option | Default | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--agent ` | unchanged | Run this agent (at its live version, else the latest). | | `--agent-version ` | unchanged | With --agent: run this exact version. | | `--allow-unattended ` | unchanged; a schedule that has a list and moves to another flow or agent must name it again, or `none` | A tool, by id, whose calls in this schedule's runs needn't wait for a person's yes, though the tool asks for one when no person started the run (repeatable; only tools its agent or flow calls, no wildcard). Needs `admin` on the schedule's project. The tenant's and the agent's approval rules still apply. Replaces the list; `none` clears it; left out, the list is kept, and a new --agent or --flow must name it again (or `none`). Repeatable. | | `--catch-up ` | unchanged | After a gap (the runtime was down): `latest` runs once for the latest missed time; `skip` drops them. | | `--cron ` | unchanged | A new cron expression: `0 7 * * 1-5` (07:00 on weekdays), `@daily`, … | | `--flow ` | unchanged | Run this flow (with --flow-version). | | `--flow-version ` | unchanged | With --flow: the flow version to run. | | `--improve ` | unchanged | Start Improve runs on this agent (instead of running it), when enough new corrections marking answers wrong have come in: for the project (--project), or a segment of it (--segment). `--input` takes the Improve options, `threshold` and `monthlyCapUsd`. | | `--input ` | unchanged | The input each run gets from now on, as JSON or `@`. An agent needs `{"userMessage": "…"}`; a flow takes its own input; --improve takes its Improve options. | | `--label ` | unchanged | A new short label. | | `--overlap ` | unchanged | While the previous run is still going: `skip` or `allow` another run. | | `--project ` | unchanged | With --improve: the scope's project (the schedule's own). | | `--segment ` | none | With --improve and --project: a segment of the project, `key:value`; repeat it in order, coarse to fine. Repeatable. | | `--starting-deadline ` | unchanged | Seconds a run may start late and still count as on time. | | `--timezone ` | unchanged | A new IANA timezone, such as America/Toronto. | Every command also takes the [global flags](https://docs.kindgi.com/v0.2.0/reference/cli.md#global-flags). **Examples** Move a schedule to 08:00 on weekdays. ```sh kindgi schedules update --cron="0 8 * * 1-5" ``` Run an agent version on a schedule, and skip overlapping runs. ```sh kindgi schedules update --agent=acme.order-desk --agent-version=0.2.0 --overlap=skip ``` From [Ask before a tool runs](https://docs.kindgi.com/v0.2.0/guides/approvals/ask-before-a-tool-runs.md): ```sh pnpm exec kindgi schedules update --allow-unattended=acme-ops.post-update ``` From [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md): ```sh pnpm exec kindgi schedules update --input='{"tiers": ["settings"], "threshold": {"judgments": 5, "runs": 3, "judges": 1}, "monthlyCapUsd": 20}' ``` **See also** - [Ask before a tool runs](https://docs.kindgi.com/v0.2.0/guides/approvals/ask-before-a-tool-runs.md) - [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md) - [`kindgi schedules`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules) ### `kindgi schedules pause` **Synopsis** ```sh signature kindgi schedules pause ``` Pause a schedule: it stops running until resumed. **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.2.0/reference/cli.md#global-flags). **Examples** Pause a schedule. ```sh kindgi schedules pause ``` **See also** - [Ask before a tool runs](https://docs.kindgi.com/v0.2.0/guides/approvals/ask-before-a-tool-runs.md) - [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md) - [`kindgi schedules`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules) ### `kindgi schedules resume` **Synopsis** ```sh signature kindgi schedules resume ``` Resume a paused schedule from its next occurrence (the paused ones are not run). **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.2.0/reference/cli.md#global-flags). **Examples** Resume a paused schedule. ```sh kindgi schedules resume ``` **See also** - [Ask before a tool runs](https://docs.kindgi.com/v0.2.0/guides/approvals/ask-before-a-tool-runs.md) - [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md) - [`kindgi schedules`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules) ### `kindgi schedules run-now` **Synopsis** ```sh signature kindgi schedules run-now ``` Run a schedule now, outside its schedule (its next occurrence is unchanged). **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.2.0/reference/cli.md#global-flags). **Examples** Run a schedule now, outside its times. ```sh kindgi schedules run-now ``` **See also** - [Ask before a tool runs](https://docs.kindgi.com/v0.2.0/guides/approvals/ask-before-a-tool-runs.md) - [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md) - [`kindgi schedules`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules) ### `kindgi schedules fires` **Synopsis** ```sh signature kindgi schedules fires [--limit=] [--cursor=] ``` A schedule's history, newest first: each time it fired, the run it started, or why it was skipped, refused or failed. **Options** | Option | Default | Description | | ------------------ | -------------------- | ---------------------------------------------------------------- | | `--cursor ` | none | Resume after this cursor, from the previous page's `nextCursor`. | | `--limit ` | `25` (at most `100`) | The most to return (default 25, at most 100). | Every command also takes the [global flags](https://docs.kindgi.com/v0.2.0/reference/cli.md#global-flags). **Examples** From [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md): ```sh pnpm exec kindgi schedules fires --table ``` **See also** - [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md) - [`kindgi schedules`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules) ### `kindgi schedules take-ownership` **Synopsis** ```sh signature kindgi schedules take-ownership [--run-as=|project] ``` Become a schedule's owner, so its runs act as you from the next fire: for a schedule whose owner left, or to make it shared (--run-as=project, the project's own account becomes the owner; --run-as=\, that service account) or yours. Takes a project admin. **Options** | Option | Default | Description | | ------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--run-as ` | none (you own the schedule) | A service account, by id, or `project`: the schedule's owner, so its runs act as that account from the next fire (not as you). `project` runs it as the project's own account, made the first time, and takes `admin` on the project. The project's own account runs only what the project's editors can. A named account takes `act_as`, and needs a role that runs what the schedule runs (editor on the target's project). Omit it to own the schedule yourself. | Every command also takes the [global flags](https://docs.kindgi.com/v0.2.0/reference/cli.md#global-flags). **Examples** Take over a schedule whose owner left. ```sh kindgi schedules take-ownership ``` **See also** - [Ask before a tool runs](https://docs.kindgi.com/v0.2.0/guides/approvals/ask-before-a-tool-runs.md) - [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md) - [`kindgi schedules`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules) ### `kindgi schedules unregister` **Synopsis** ```sh signature kindgi schedules unregister ``` Remove a schedule: it stops running. **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.2.0/reference/cli.md#global-flags). **Examples** Remove a schedule. ```sh kindgi schedules unregister ``` **See also** - [Ask before a tool runs](https://docs.kindgi.com/v0.2.0/guides/approvals/ask-before-a-tool-runs.md) - [Run on a schedule](https://docs.kindgi.com/v0.2.0/guides/runs/run-on-a-schedule.md) - [`kindgi schedules`](https://docs.kindgi.com/v0.2.0/reference/cli/schedules.md#kindgi-schedules)