`flexkit runs`

Inspects automation runs: what started them, what the agent did, what it produced, and how it ended. See Runs and diagnostics for what each status means. To start a run, use flexkit automations run.

Synopsis

flexkit runs <subcommand> [arguments] [options]

Without a subcommand, flexkit runs runs ls. Run ids are the ID column of runs ls and the id printed by automations run.

Permissions

Owners, developers and viewers can list and read runs of the automations they can see. cancel needs the owner or developer role, and transcript is limited to owners and developers.

`runs ls`

List runs, newest first: every run you can see in the project, only runs of automations you created (--mine), or the runs of one automation. Without --automation the list ends with success and failure counts for the last 24 hours and 7 days.

flexkit runs ls [--automation <id>] [--mine] [--limit <n>] [--offset <n>] [--json]

Examples

# Latest runs in the project
flexkit runs ls
 
# The last 50 runs of one automation
flexkit runs ls --automation 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f --limit 50
 
# The second page of runs of your own automations
flexkit runs ls --mine --limit 20 --offset 20
 
# Ids of the failed runs on this page
flexkit runs ls --json | jq -r '.runs[] | select(.status == "failed") | .id'

`runs inspect`

Show a run: automation, status, trigger, start and end time, duration, summary and error.

flexkit runs inspect <runId> [--json]

Examples

# Show a run
flexkit runs inspect 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f
 
# Print only the summary
flexkit runs inspect 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f --json | jq -r '.run.summary'

`runs logs`

Print a run’s events as they happened: the agent’s text, one line per tool call (→ tool {input}) and result (✓ or ✗), approval requests (⏸), errors, and the final status with the summary.

A finished run is replayed. An active run streams live until it ends, or until it pauses for an approval. With --follow, the command keeps waiting through approval pauses and continues where it left off until the run finishes. --json prints the raw stream chunks as newline-delimited JSON instead.

flexkit runs logs <runId> [-f | --follow] [--json]

Examples

# Replay a finished run
flexkit runs logs 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f
 
# Follow an active run until it finishes
flexkit runs logs 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f --follow
 
# List the tools the run called
flexkit runs logs 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f --json \
  | jq -r 'select(.type == "tool-input-available") | .toolName'

Run events are kept for a limited time. For older runs, runs logs reports that the stream is no longer available; runs inspect still shows the summary and error.

`runs transcript`

Print the model transcript stored when the run finished: the system, user, assistant and tool messages with full tool inputs and results. Useful to debug why an agent made a decision. Owners and developers only.

flexkit runs transcript <runId> [--output <file>] [--json]

Examples

# Read the transcript
flexkit runs transcript 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f
 
# Save it as JSON
flexkit runs transcript 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f --output run-transcript.json
 
# Count the assistant messages
flexkit runs transcript 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f --json \
  | jq '[.transcript[] | select(.role == "assistant")] | length'

`runs artifacts`

List the files a run generated (HTML and PDF reports, CSV and JSON exports), or download them with --download. Downloads never overwrite a file: an existing report.pdf makes the next one report (1).pdf.

flexkit runs artifacts <runId> [artifactId] [--download] [--out-dir <dir>] [--json]

Examples

# List the files of a run
flexkit runs artifacts 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f
 
# Download all of them into ./reports
flexkit runs artifacts 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f --download --out-dir reports
 
# Download one file
flexkit runs artifacts 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f 5e7a9c1b-3d5f-4b7a-9c1e-3f5a7c9e1b3d --download

`runs cancel`

Cancel a run that is running or waiting for approval. The agent stops, its subtasks and bulk jobs are cancelled, and its pending approvals are closed. The CLI asks for confirmation; pass --yes in scripts.

flexkit runs cancel <runId> [--yes] [--json]

Examples

# Cancel after a prompt
flexkit runs cancel 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f
 
# Cancel without a prompt
flexkit runs cancel 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f --yes

Options

Option	Description
`--json`	Print the API response as JSON on stdout (`logs`: NDJSON stream chunks).
`-p, --project <id>`	Project to act on (default: the linked project).
`-a, --automation <id>`	`ls`: only runs of this automation.
`--mine`	`ls`: only runs of automations you created.
`-n, --limit <n>`	`ls`: number of runs (default 20, max 100).
`--offset <n>`	`ls`: number of runs to skip.
`-f, --follow`	`logs`: keep streaming through approval pauses until the run finishes.
`-o, --output <file>`	`transcript`: write the transcript as JSON to a file.
`--download`	`artifacts`: download the files instead of listing them.
`-o, --out-dir <dir>`	`artifacts`: folder for downloads (default: the current folder).
`-y, --yes`	`cancel`: skip the confirmation prompt.

You can also use all global options.

Common workflows

Investigate a failed run

flexkit runs ls --automation 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f
flexkit runs inspect 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f
flexkit runs logs 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f
flexkit runs transcript 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f --output failed-run.json

Collect a scheduled report

# Download the files of the latest run of an automation
run=$(flexkit runs ls --automation 3f1c9a2e-8d4b-4c1a-9f0e-2b7d5e6a1c3f --limit 1 --json | jq -r '.runs[0].id')
flexkit runs artifacts "$run" --download --out-dir reports