kindgi runs

`kindgi runs`

Synopsis

kindgi runs <command>

Signature

Manage kernel runs — the single execution primitive.

Commands

Command	Description
`kindgi runs list`	List runs (paginated).
`kindgi runs get`	Fetch a run snapshot by id.
`kindgi runs cancel`	Request cancellation of a run.
`kindgi runs journal`	Read the durable journal for a run.
`kindgi runs stream`	Subscribe to a run event stream (SSE).
`kindgi runs start`	Start a run for an agent or flow.
`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

`kindgi runs list`

Synopsis

kindgi runs list [--agent=<agent-id>] [--trigger=<schedule-id>] [--replays=exclude|include|only] [--eval-run=<id>] [--limit=<n>] [--cursor=<c>]

Signature

List runs (paginated).

Options

Option	Default	Description
`--agent <value>`	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 <value>`	none	Resume after this cursor, from the previous page's `nextCursor`.
`--eval-run <value>`	none	Only this eval run's replay runs.
`--limit <value>`	`25` (at most `100`)	The most runs to return (default 25, at most 100).
`--replays <value>`	`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 <value>`	none	Only the runs this trigger started: a schedule, by its id (`kindgi schedules list`).

Every command also takes the global flags.

Examples

From List runs:

pnpm exec kindgi runs list --limit=2
pnpm exec kindgi runs list --agent=acme.chat-desk --table

See also

`kindgi runs get`

Synopsis

kindgi runs get <run-id>

Signature

Fetch a run snapshot by id.

Options

Every command also takes the global flags.

Examples

From Back up and restore the runtime's database:

npx --yes @kindgi/cli@0.1 runs get <run id> --url http://localhost:4000

From Ask before a long conversation continues:

pnpm exec kindgi runs get 0c424165-fc78-4563-965f-5ca9ba0ec4a9

See also

`kindgi runs cancel`

Synopsis

kindgi runs cancel <run-id>

Signature

Request cancellation of a run.

Options

Every command also takes the global flags.

Examples

From Restart the runtime and check its health:

npx --yes @kindgi/cli@0.1 runs cancel <run id> --url http://localhost:4000

From Cancel a run:

pnpm exec kindgi runs cancel <run-id>

See also

`kindgi runs journal`

Synopsis

kindgi runs journal <run-id> [--since=<seq>] [--limit=<n>] [--cursor=<c>]

Signature

Read the durable journal for a run.

Options

Option	Default	Description
`--cursor <value>`	none	Resume after this cursor, from the previous page's `nextCursor`.
`--limit <value>`	none: the whole journal	The most entries to return (1 to 100). Without it, the whole journal.
`--since <value>`	none	Only the entries after this sequence number.

Every command also takes the global flags.

Examples

From Erase a person's data:

pnpm exec kindgi runs journal <run-id>

From Ask before a tool runs:

pnpm exec kindgi runs journal <flow-run-id>

See also

`kindgi runs stream`

Synopsis

kindgi runs stream <run-id>

Signature

Subscribe to a run event stream (SSE).

Options

Every command also takes the global flags.

Examples

From Follow a run's events:

pnpm exec kindgi runs stream <run-id>

See also

`kindgi runs start`

Synopsis

kindgi runs start (--agent=<agent-id> [--agent-version=<v>] | --flow=<flow-id> [--flow-version=<v>]) --input=<json-or-@file> [--project=<project-id>] [--segment=<key:value>]… [--no-wait] [--dry-run] [--idempotency-key=<key>]

Signature

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 [<code>]: …), 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 <value>`	required: one of `--agent`, `--flow`	The agent to run, by id (`<pack>.<agent>`). Give `--agent` or `--flow`.
`--agent-version <value>`	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 <value>`	required: one of `--agent`, `--flow`	The flow to run, by id. Give `--flow` or `--agent`, not both.
`--flow-version <value>`	the flow's latest version	The flow's version to run (default: its latest).
`--idempotency-key <value>`	none	A retry with the same key returns the run the first call started.
`--input <value>`	required	The run's input as JSON, or `@<file>` 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 <value>`	the tenant's Default project	The project to run in (`kindgi projects list`). Default: the tenant's Default project.
`--segment <value>`	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.

Examples

From Deploy on Azure Container Apps:

npx --yes @kindgi/cli@0.1 runs start --flow=acme.greet-flow --input='{"name":"Azure"}' --url "$URL"

From Deploy on Google Cloud Run:

npx --yes @kindgi/cli@0.1 runs start --flow=acme.greet-echo --input='{"name":"Ada"}' --url "$URL"

See also

`kindgi runs resume`

Synopsis

kindgi runs resume <run-id>

Signature

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.

Examples

From Decide an approval:

pnpm exec kindgi runs resume 45d986f1-8a8d-4341-a786-5ddcf239bb93

See also