---
title: 'flexkit runs'
description: 'List automation runs, stream their events, read transcripts, download their files and cancel them.'
---

# `flexkit runs`

Inspects automation runs: what started them, what the agent did, what it produced, and how it ended. See [Runs and diagnostics](/docs/automations/runs) for what each status means. To start a run, use [`flexkit automations run`](/docs/cli/automations#automations-run).

## Synopsis

```bash
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.

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

### Examples

```bash
# 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.

```bash
flexkit runs inspect <runId> [--json]
```

### Examples

```bash
# 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.

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

### Examples

```bash
# 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.

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

### Examples

```bash
# 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`.

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

### Examples

```bash
# 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.

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

### Examples

```bash
# 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](/docs/cli/global-options).

## Common workflows

### Investigate a failed run

```bash
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

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


---

[View full sitemap](/docs/sitemap.md)