---
title: "Runs & Outputs"
canonical: https://trickest.com/docs/developer-tools/cli/runs
description: "Execute workflows, watch progress, manage run records, and read node outputs (stdout/stderr, files) from the CLI."
---

# Runs & Outputs

The `run` family executes workflows and manages run records; the `output` family
reads results. `run execute` and `run ls` use the active workflow unless you pass
`--workflow`. `run get` without an ID reads its latest run. Commands with an
explicit run ID target that run. Output inspection and download commands use the active workflow and default
to its latest run; pin `--run` when inspecting a specific execution. `output mount`
is different: by default it collects the workflow's current effective outputs,
which can combine reused node results from different runs. Pass `--run` to mount
only a specific run.

<Note>
Need a workflow active first: `trickest workflow use <name-or-id>`. Run-scoped
output commands default to the most recent run; pass `--run <id>` to target another.
</Note>

## `trickest run`

| Subcommand | Description |
|---|---|
| `run execute [target]` | Execute the workflow (or a single node) |
| `run ls` | List runs for the current workflow |
| `run get [run-id]` | Run details + per-node statuses |
| `run watch\|status <run-id>` | Watch a run live until completion |
| `run stop <run-id>` | Stop a running execution |
| `run retry <run-id>` | Retry a failed run |
| `run rm <run-id>` | Remove a run record |
| `run output\|outputs <run-id> <node>` | Output files for a node in a run |
| `run output-content\|cat <output-id>` | Print an output file's content |

### `run execute`

Without flags, execution waits for a terminal status and prints the final run
summary. `--watch` adds live progress. `--async` or `--no-wait` returns the new
run ID immediately; it does not indicate completion.

```bash
trickest run execute                       # run the whole active workflow
trickest run execute --watch               # run and stream progress
trickest run execute --async               # start and return immediately
trickest run execute httpx --downstream    # run one node and everything after it
trickest run execute --set domain=example.com --set threads=50
```

| Flag | Description |
|---|---|
| `--fleet <name-or-id>` | Fleet to execute on |
| `--workflow <name-or-id>` | Target a workflow for this call without changing saved context |
| `--max-machines <n>` | Cap run parallelism; the backend rejects values above the fleet limit |
| `--watch` | Stream execution progress live |
| `--no-wait` / `--async` | Start the run and return immediately |
| `--dry` | Preview the execution plan without running |
| `--timeout <duration>` | Client-side stop after e.g. `30m`, `1h`; use with `--watch` and keep the CLI attached. It is not a backend deadline and does not apply to detached `--async` runs |
| `--downstream` | When running a single target, also run nodes downstream of it |
| `--set <key=value>` | Override an input value (repeatable) |
| `--node <name>` | Execute a single node (alias for the positional target) |

### `run ls`

```bash
trickest run ls
```
```json
[{"id":"72e345d6-…","status":"COMPLETED","created":"2026-05-26T16:16:21Z","finished":"","fleet":""}]
```

| Flag | Description |
|---|---|
| `--limit <n>` | Max runs to show (default 20) |
| `--status <status>` | Filter: `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`, `STOPPED`, `ERROR`, `PARTIAL_SUCCESS`, `SCHEDULED`, `STOPPING` |

```bash
trickest run ls --status FAILED --limit 5
```

### `run get` & `run watch`

```bash
trickest run get <run-id>
```
```json
{
  "id": "72e345d6-…",
  "status": "COMPLETED",
  "fleet": "0ca38cb7-…",
  "created": "2026-05-26T16:16:21Z",
  "nodes": [{"name":"airixss","status":"SUCCEEDED"}]
}
```

```bash
trickest run watch <run-id>    # block and stream until the run finishes
```

To inspect failures inside modules, use `run get <id> --tree --failed-only`.
Add `--task-stats` for distributed task counts and `--depth <n>` to control how
far the tree expands.

`run watch` follows execution; it does not change the workflow. A watched run
that does not finish as `COMPLETED` causes a nonzero exit.

### Manage runs

```bash
trickest run stop <run-id>
trickest run retry <run-id> --watch
trickest run rm <run-id> --force
```

## `trickest output`

Read node results from a run. `--run` defaults to the latest run.

| Subcommand | Description |
|---|---|
| `output ls [node]` | List output files per node |
| `output get <node>` | Summary: status, stdout preview, stderr |
| `output stdout <node>` | Raw stdout (pipe-friendly) |
| `output stderr <node>` | Raw stderr (pipe-friendly) |
| `output tail <node>` | Live-tail stdout |
| `output pull <node> [file]` | Download output files |
| `output mount` | Materialize run outputs as real files |

### `output ls`

```bash
trickest output ls --run <run-id>
```
```json
[{"node":"airixss","status":"SUCCEEDED","files":1}]
```

### Reading logs

```bash
trickest output get httpx                  # status + stdout preview + stderr
trickest output stdout httpx --all         # entire stdout
trickest output stdout httpx --tail 50     # last 50 lines
trickest output stderr httpx
trickest output tail httpx --follow        # stream while the run is RUNNING
```

`stdout`/`stderr` print raw text so you can pipe them:

```bash
trickest output stdout subfinder --all | sort -u | wc -l
```

| Command | Notable flags |
|---|---|
| `output stdout` / `stderr` | `--run <id>`, `--tail <n>`, `--all` |
| `output tail` | `--run <id>`, `--follow`, `-n, --lines <n>` |

### Downloading files

```bash
trickest output pull httpx                       # download this node's output
trickest output pull httpx results.txt           # a specific file
trickest output pull httpx --all -o ./out/       # everything into a directory
```

| Flag | Description |
|---|---|
| `--run <run-id>` | Target run (default latest) |
| `-o, --output <path>` | Destination file or directory |
| `--all` | Download all output files |

### `output mount`

Materialize a run's outputs as real files in the sandbox filesystem, handy when an
agent wants to process results with normal shell tools:

```bash
trickest output mount --node httpx          # current effective outputs
trickest output mount --run <run-id> --node httpx --wait
trickest output mount --node httpx -o /tmp/results
```

Select one or more nodes with `--node`, or explicitly use `--all`. Mounting all
nodes can download a large amount of data. Current outputs go under
`/trickest/sandbox/outputs/`; a specific run goes under
`/trickest/sandbox/runs/<id>/`. `--wait` waits for that run and its indexed output.

When distributed tasks produce the same filename, `output pull --source <job-name>`
selects the source shown by `output ls`. Use `--recurse` to inspect module outputs.

## Recipe: run and collect

```bash
trickest workflow use "Discovery"
RUN=$(trickest --output json --quiet run execute --async | jq -r '.id')
trickest run watch "$RUN"
trickest output ls --run "$RUN"
trickest output pull httpx --run "$RUN" --all -o ./discovery-results/
```

## Related

<CardGroup cols={2}>
  <Card title="Schedules" icon="clock" href="/docs/developer-tools/cli/schedules">
    Run workflows automatically on a recurring schedule.
  </Card>
  <Card title="Graph Analysis" icon="sitemap" href="/docs/developer-tools/cli/graph">
    Validate the DAG before you execute.
  </Card>
</CardGroup>

---
_Markdown source of https://trickest.com/docs/developer-tools/cli/runs._