# 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 <command>
```

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.1.8/reference/cli/schedules.md#kindgi-schedules-list)                     | List schedules.                                                                                                       |
| [`kindgi schedules get`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules-get)                       | Fetch a schedule, with its next occurrences when asked.                                                               |
| [`kindgi schedules create`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules-create)                 | Run an agent or a flow on a schedule, or start improvement passes on an agent (--improve).                            |
| [`kindgi schedules update`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules-update)                 | Change a schedule: when it runs, what it runs, or its policies.                                                       |
| [`kindgi schedules pause`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules-pause)                   | Pause a schedule: it stops running until resumed.                                                                     |
| [`kindgi schedules resume`](https://docs.kindgi.com/v0.1.8/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.1.8/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.1.8/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.1.8/reference/cli/schedules.md#kindgi-schedules-take-ownership) | Become a schedule's owner, so its runs act as you (for a schedule whose owner left).                                  |
| [`kindgi schedules unregister`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules-unregister)         | Remove a schedule: it stops running.                                                                                  |

**See also**

- [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md)

### `kindgi schedules list`

**Synopsis**

```sh signature
kindgi schedules list [--project=<project-id>] [--status=active|paused] [--limit=<n>] [--cursor=<c>]
```

List schedules.

**Options**

| Option              | Default              | Description                                                      |
| ------------------- | -------------------- | ---------------------------------------------------------------- |
| `--cursor <value>`  | none                 | Resume after this cursor, from the previous page's `nextCursor`. |
| `--limit <value>`   | `25` (at most `100`) | The most to return (default 25, at most 100).                    |
| `--project <value>` | none                 | Only this project's schedules.                                   |
| `--status <value>`  | none                 | Only `active` or only `paused` schedules.                        |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md):

```sh
pnpm exec kindgi schedules list --status=active
pnpm exec kindgi schedules list --project=<project-id>
```

**See also**

- [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md)
- [`kindgi schedules`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules)

### `kindgi schedules get`

**Synopsis**

```sh signature
kindgi schedules get <schedule-id> [--upcoming=<n>]
```

Fetch a schedule, with its next occurrences when asked.

**Options**

| Option               | Default | Description                                   |
| -------------------- | ------- | --------------------------------------------- |
| `--upcoming <value>` | none    | Also show the next N times it runs (1 to 20). |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

Fetch a schedule with its next five run times.

```sh
kindgi schedules get <schedule-id> --upcoming=5
```

From [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md):

```sh
pnpm exec kindgi schedules get <schedule-id> --upcoming=3
```

**See also**

- [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md)
- [`kindgi schedules`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules)

### `kindgi schedules create`

**Synopsis**

```sh signature
kindgi schedules create --cron=<expr> (--agent=<id> [--agent-version=<v>] | --flow=<id> --flow-version=<v> | --improve=<agent-id> --project=<id> [--segment=<key:value>]…) [--timezone=<tz>] [--input=<json-or-@file>] [--project=<project-id>] [--catch-up=latest|skip] [--overlap=skip|allow] [--starting-deadline=<s>] [--label=<text>]
```

Run an agent or a flow on a schedule, or start improvement passes on an agent (--improve). Its runs act as you, checked again at every run; they're in your project's runs, naming the schedule.

**Options**

| Option                        | Default                      | Description                                                                                                                                                                                                                                                                              |
| ----------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--agent <value>`             | none                         | Run this agent (at its live version, else the latest).                                                                                                                                                                                                                                   |
| `--agent-version <value>`     | none                         | With --agent: run this exact version.                                                                                                                                                                                                                                                    |
| `--catch-up <value>`          | `latest`                     | After a gap (the runtime was down): `latest` runs once for the latest missed time (default); `skip` drops them.                                                                                                                                                                          |
| `--cron <value>`              | required                     | A cron expression: `0 7 * * 1-5` (07:00 on weekdays), `@daily`, …                                                                                                                                                                                                                        |
| `--flow <value>`              | none                         | Run this flow (with --flow-version).                                                                                                                                                                                                                                                     |
| `--flow-version <value>`      | none                         | With --flow: the flow version to run.                                                                                                                                                                                                                                                    |
| `--improve <value>`           | none                         | Start improvement passes on this agent (instead of runs), when enough new trusted "no" judgments have come in: for the project (--project), or a segment of it (--segment). `--input` takes the pass options, `threshold` and `monthlyCapUsd`.                                           |
| `--input <value>`             | `{}`                         | The input each run gets, as JSON or `@<file>`. An agent needs `{"userMessage": "…"}`; a flow takes its own input (default `{}`); --improve takes its pass options (`{"tiers": ["settings"], "threshold": {"judgments": 5, "runs": 3, "judges": 2}, "monthlyCapUsd": 20}`, the defaults). |
| `--label <value>`             | none                         | A short label.                                                                                                                                                                                                                                                                           |
| `--overlap <value>`           | `skip`                       | While the previous run is still going: `skip` (default) or `allow` another run.                                                                                                                                                                                                          |
| `--project <value>`           | the tenant's Default project | The schedule's project, by id (default: the tenant's Default project).                                                                                                                                                                                                                   |
| `--segment <value>`           | none                         | With --improve and --project: a segment of the project, `key:value`; repeat it in order, coarse to fine. Repeatable.                                                                                                                                                                     |
| `--starting-deadline <value>` | `600` (seconds)              | Seconds a run may start late and still count as on time (default 600).                                                                                                                                                                                                                   |
| `--timezone <value>`          | `UTC`                        | An IANA timezone, such as America/Toronto (default UTC).                                                                                                                                                                                                                                 |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

From [Run on a schedule](https://docs.kindgi.com/v0.1.8/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=<project-id> --segment=company:acme \
```

**See also**

- [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md)
- [`kindgi schedules`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules)

### `kindgi schedules update`

**Synopsis**

```sh signature
kindgi schedules update <schedule-id> [--cron=<expr>] [--timezone=<tz>] [--input=<json-or-@file>] [--agent=<id> [--agent-version=<v>] | --flow=<id> --flow-version=<v> | --improve=<agent-id> --project=<id> [--segment=<key:value>]…] [--catch-up=…] [--overlap=…] [--starting-deadline=<s>] [--label=<text>]
```

Change a schedule: when it runs, what it runs, or its policies. A flag left out keeps the schedule's value.

**Options**

| Option                        | Default   | Description                                                                                                                                                                                                                                    |
| ----------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--agent <value>`             | unchanged | Run this agent (at its live version, else the latest).                                                                                                                                                                                         |
| `--agent-version <value>`     | unchanged | With --agent: run this exact version.                                                                                                                                                                                                          |
| `--catch-up <value>`          | unchanged | After a gap (the runtime was down): `latest` runs once for the latest missed time; `skip` drops them.                                                                                                                                          |
| `--cron <value>`              | unchanged | A new cron expression: `0 7 * * 1-5` (07:00 on weekdays), `@daily`, …                                                                                                                                                                          |
| `--flow <value>`              | unchanged | Run this flow (with --flow-version).                                                                                                                                                                                                           |
| `--flow-version <value>`      | unchanged | With --flow: the flow version to run.                                                                                                                                                                                                          |
| `--improve <value>`           | unchanged | Start improvement passes on this agent (instead of runs), when enough new trusted "no" judgments have come in: for the project (--project), or a segment of it (--segment). `--input` takes the pass options, `threshold` and `monthlyCapUsd`. |
| `--input <value>`             | unchanged | The input each run gets from now on, as JSON or `@<file>`. An agent needs `{"userMessage": "…"}`; a flow takes its own input; --improve takes its pass options.                                                                                |
| `--label <value>`             | unchanged | A new short label.                                                                                                                                                                                                                             |
| `--overlap <value>`           | unchanged | While the previous run is still going: `skip` or `allow` another run.                                                                                                                                                                          |
| `--project <value>`           | unchanged | With --improve: the scope's project (the schedule's own).                                                                                                                                                                                      |
| `--segment <value>`           | none      | With --improve and --project: a segment of the project, `key:value`; repeat it in order, coarse to fine. Repeatable.                                                                                                                           |
| `--starting-deadline <value>` | unchanged | Seconds a run may start late and still count as on time.                                                                                                                                                                                       |
| `--timezone <value>`          | unchanged | A new IANA timezone, such as America/Toronto.                                                                                                                                                                                                  |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

Move a schedule to 08:00 on weekdays.

```sh
kindgi schedules update <schedule-id> --cron="0 8 * * 1-5"
```

Run an agent version on a schedule, and skip overlapping runs.

```sh
kindgi schedules update <schedule-id> --agent=acme.order-desk --agent-version=0.2.0 --overlap=skip
```

From [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md):

```sh
pnpm exec kindgi schedules update <schedule-id> --input='{"tiers": ["settings"], "threshold": {"judgments": 5, "runs": 3, "judges": 1}, "monthlyCapUsd": 20}'
```

**See also**

- [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md)
- [`kindgi schedules`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules)

### `kindgi schedules pause`

**Synopsis**

```sh signature
kindgi schedules pause <schedule-id>
```

Pause a schedule: it stops running until resumed.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

Pause a schedule.

```sh
kindgi schedules pause <schedule-id>
```

**See also**

- [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md)
- [`kindgi schedules`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules)

### `kindgi schedules resume`

**Synopsis**

```sh signature
kindgi schedules resume <schedule-id>
```

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.1.8/reference/cli.md#global-flags).

**Examples**

Resume a paused schedule.

```sh
kindgi schedules resume <schedule-id>
```

**See also**

- [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md)
- [`kindgi schedules`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules)

### `kindgi schedules run-now`

**Synopsis**

```sh signature
kindgi schedules run-now <schedule-id>
```

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.1.8/reference/cli.md#global-flags).

**Examples**

Run a schedule now, outside its times.

```sh
kindgi schedules run-now <schedule-id>
```

**See also**

- [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md)
- [`kindgi schedules`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules)

### `kindgi schedules fires`

**Synopsis**

```sh signature
kindgi schedules fires <schedule-id> [--limit=<n>] [--cursor=<c>]
```

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 <value>` | none                 | Resume after this cursor, from the previous page's `nextCursor`. |
| `--limit <value>`  | `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.1.8/reference/cli.md#global-flags).

**Examples**

From [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md):

```sh
pnpm exec kindgi schedules fires <schedule-id> --table
```

**See also**

- [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md)
- [`kindgi schedules`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules)

### `kindgi schedules take-ownership`

**Synopsis**

```sh signature
kindgi schedules take-ownership <schedule-id>
```

Become a schedule's owner, so its runs act as you (for a schedule whose owner left).

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

Take over a schedule whose owner left.

```sh
kindgi schedules take-ownership <schedule-id>
```

**See also**

- [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md)
- [`kindgi schedules`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules)

### `kindgi schedules unregister`

**Synopsis**

```sh signature
kindgi schedules unregister <schedule-id>
```

Remove a schedule: it stops running.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.8/reference/cli.md#global-flags).

**Examples**

Remove a schedule.

```sh
kindgi schedules unregister <schedule-id>
```

**See also**

- [Run on a schedule](https://docs.kindgi.com/v0.1.8/guides/runs/run-on-a-schedule.md)
- [`kindgi schedules`](https://docs.kindgi.com/v0.1.8/reference/cli/schedules.md#kindgi-schedules)