# kindgi runs > Manage kernel runs — the single execution primitive ## `kindgi runs` **Synopsis** ```sh signature kindgi runs ``` Manage kernel runs — the single execution primitive. **Commands** | Command | Description | | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`kindgi runs list`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs-list) | List runs (paginated). | | [`kindgi runs get`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs-get) | Fetch a run snapshot by id. | | [`kindgi runs cancel`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs-cancel) | Request cancellation of a run. | | [`kindgi runs journal`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs-journal) | Read the durable journal for a run. | | [`kindgi runs stream`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs-stream) | Subscribe to a run event stream (SSE). | | [`kindgi runs start`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs-start) | Start a run for an agent or flow. | | [`kindgi runs resume`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs-resume) | Say what a run waits for before it resumes: an approval (named, with the command that decides it), the runtime (a queued start, a child run, a retry, a lease, a timeout), or nothing. | **See also** - [Deploy on Azure Container Apps](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/azure-container-apps.md) - [Deploy on Google Cloud Run](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/cloud-run.md) - [Self-host Kindgi](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/self-host.md) - [Set an agent's budget](https://docs.kindgi.com/v0.1.10/guides/agents/budgets.md) ### `kindgi runs list` **Synopsis** ```sh signature kindgi runs list [--agent=] [--trigger=] [--replays=exclude|include|only] [--eval-run=] [--limit=] [--cursor=] ``` List runs (paginated). **Options** | Option | Default | Description | | -------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--agent ` | none | Only this agent's turns, at any version: its own runs and the turns its steps start inside flows. Turns from before Kindgi 0.1.3 don't name their agent and aren't listed. | | `--cursor ` | none | Resume after this cursor, from the previous page's `nextCursor`. | | `--eval-run ` | none | Only this eval run's replay runs. | | `--limit ` | `25` (at most `100`) | The most runs to return (default 25, at most 100). | | `--replays ` | `exclude`; with `--eval-run`, `include` | Replay runs (an eval run re-running a past run): `exclude` (the default) leaves them out, `include` lists them too, `only` lists just them. | | `--trigger ` | none | Only the runs this trigger started: a schedule, by its id (`kindgi schedules list`). | Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** From [List runs](https://docs.kindgi.com/v0.1.10/guides/runs/list-runs.md): ```sh pnpm exec kindgi runs list --limit=2 pnpm exec kindgi runs list --agent=acme.chat-desk --table ``` **See also** - [List runs](https://docs.kindgi.com/v0.1.10/guides/runs/list-runs.md) - [`kindgi runs`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs) ### `kindgi runs get` **Synopsis** ```sh signature kindgi runs get ``` Fetch a run snapshot by id. **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** From [Back up and restore the runtime's database](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/back-up-and-restore.md): ```sh npx --yes @kindgi/cli@0.1 runs get --url http://localhost:4000 ``` From [Ask before a long conversation continues](https://docs.kindgi.com/v0.1.10/guides/approvals/ask-after-n-turns.md): ```sh pnpm exec kindgi runs get 0c424165-fc78-4563-965f-5ca9ba0ec4a9 ``` **See also** - [Back up and restore the runtime's database](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/back-up-and-restore.md) - [Ask before a long conversation continues](https://docs.kindgi.com/v0.1.10/guides/approvals/ask-after-n-turns.md) - [Ask before a tool runs](https://docs.kindgi.com/v0.1.10/guides/approvals/ask-before-a-tool-runs.md) - [Wait for an approval](https://docs.kindgi.com/v0.1.10/guides/flows/wait-for-an-approval.md) - [`kindgi runs`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs) ### `kindgi runs cancel` **Synopsis** ```sh signature kindgi runs cancel ``` Request cancellation of a run. **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** From [Restart the runtime and check its health](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/restart-and-check-health.md): ```sh npx --yes @kindgi/cli@0.1 runs cancel --url http://localhost:4000 ``` From [Cancel a run](https://docs.kindgi.com/v0.1.10/guides/runs/cancel-a-run.md): ```sh pnpm exec kindgi runs cancel ``` **See also** - [Restart the runtime and check its health](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/restart-and-check-health.md) - [Cancel a run](https://docs.kindgi.com/v0.1.10/guides/runs/cancel-a-run.md) - [`kindgi runs`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs) ### `kindgi runs journal` **Synopsis** ```sh signature kindgi runs journal [--since=] [--limit=] [--cursor=] ``` Read the durable journal for a run. **Options** | Option | Default | Description | | ------------------ | ----------------------- | --------------------------------------------------------------------- | | `--cursor ` | none | Resume after this cursor, from the previous page's `nextCursor`. | | `--limit ` | none: the whole journal | The most entries to return (1 to 100). Without it, the whole journal. | | `--since ` | none | Only the entries after this sequence number. | Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** From [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md): ```sh pnpm exec kindgi runs journal ``` From [Ask before a tool runs](https://docs.kindgi.com/v0.1.10/guides/approvals/ask-before-a-tool-runs.md): ```sh pnpm exec kindgi runs journal ``` **See also** - [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md) - [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md) - [Ask before a tool runs](https://docs.kindgi.com/v0.1.10/guides/approvals/ask-before-a-tool-runs.md) - [Branch a flow](https://docs.kindgi.com/v0.1.10/guides/flows/branch-a-flow.md) - [`kindgi runs`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs) ### `kindgi runs stream` **Synopsis** ```sh signature kindgi runs stream ``` Subscribe to a run event stream (SSE). **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** From [Follow a run's events](https://docs.kindgi.com/v0.1.10/guides/runs/follow-a-run.md): ```sh pnpm exec kindgi runs stream ``` **See also** - [Follow a run's events](https://docs.kindgi.com/v0.1.10/guides/runs/follow-a-run.md) - [`kindgi runs`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs) ### `kindgi runs start` **Synopsis** ```sh signature kindgi runs start (--agent= [--agent-version=] | --flow= [--flow-version=]) --input= [--project=] [--segment=]… [--no-wait] [--dry-run] [--idempotency-key=] ``` Start a run for an agent or flow. Waits until it finishes or waits on an approval; if the wait is stopped (Ctrl+C), the run goes on and its id is printed. A run that fails is still printed, its error goes to stderr (`Error []: …`), and the command exits 1. With --no-wait it prints as soon as the run exists (follow it with `runs get` / `runs stream`). --dry-run runs only read-only tools. **Options** | Option | Default | Description | | --------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--agent ` | required: one of `--agent`, `--flow` | The agent to run, by id (`.`). Give `--agent` or `--flow`. | | `--agent-version ` | the agent's latest version | The agent's version to run (default: its latest). A turn in a conversation needs the version the conversation was opened with. | | `--dry-run` | off | Run only the tools declared read-only (`mutating: false`); an agent turn skips its model call. | | `--flow ` | required: one of `--agent`, `--flow` | The flow to run, by id. Give `--flow` or `--agent`, not both. | | `--flow-version ` | the flow's latest version | The flow's version to run (default: its latest). | | `--idempotency-key ` | none | A retry with the same key returns the run the first call started. | | `--input ` | required | The run's input as JSON, or `@` to read it from a file. Required. | | `--no-wait` | off (the command waits for the run to finish or wait on an approval) | Return the run as soon as it exists, agent or flow; follow it with `kindgi runs stream` or `kindgi runs get`. | | `--project ` | the tenant's Default project | The project to run in (`kindgi projects list`). Default: the tenant's Default project. | | `--segment ` | none | One step of the run's segment path, `key:value` (e.g. `company:acme`); repeat it in order, coarse to fine. It picks the agent's live version. Repeatable. | Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** From [Deploy on Azure Container Apps](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/azure-container-apps.md): ```sh npx --yes @kindgi/cli@0.1 runs start --flow=acme.greet-flow --input='{"name":"Azure"}' --url "$URL" ``` From [Deploy on Google Cloud Run](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/cloud-run.md): ```sh npx --yes @kindgi/cli@0.1 runs start --flow=acme.greet-echo --input='{"name":"Ada"}' --url "$URL" ``` **See also** - [Deploy on Azure Container Apps](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/azure-container-apps.md) - [Deploy on Google Cloud Run](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/cloud-run.md) - [Self-host Kindgi](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/self-host.md) - [Set an agent's budget](https://docs.kindgi.com/v0.1.10/guides/agents/budgets.md) - [`kindgi runs`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs) ### `kindgi runs resume` **Synopsis** ```sh signature kindgi runs resume ``` Say what a run waits for before it resumes: an approval (named, with the command that decides it), the runtime (a queued start, a child run, a retry, a lease, a timeout), or nothing. Exit 0: not waiting; 3: waits for an approval; 4: waits on the runtime. (5 is reserved for a held run.) **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** From [Decide an approval](https://docs.kindgi.com/v0.1.10/guides/approvals/decide-an-approval.md): ```sh pnpm exec kindgi runs resume 45d986f1-8a8d-4341-a786-5ddcf239bb93 ``` **See also** - [Decide an approval](https://docs.kindgi.com/v0.1.10/guides/approvals/decide-an-approval.md) - [`kindgi runs`](https://docs.kindgi.com/v0.1.10/reference/cli/runs.md#kindgi-runs)