> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basset.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# basset request

> Ask real devices for readings, and see what is already being asked

The core loop: `create` activates instruments on matching devices, `tail` or `get` reads what comes back, `stop` ends it early rather than waiting out `--for`.

## create

Activates instruments on the devices matching a target. The request is live until it expires — devices matching it converge on the instruments named here, the ones already running immediately, the rest the next time they check in.

```bash theme={"dark"}
basset request create \
  --app <app> \
  --purpose "Hunting a hitch on the settings screen" \
  -i concurrency.mainThreadHang \
  -i runtime.stackSamples
```

| Flag | Meaning |
| - | - |
| `-a, --app` | App name or id. |
| `-i, --instrument` | An instrument to activate, or `name:key=value` to set its config. Repeat for more; `basset menu` lists each instrument and what it accepts. |
| `--user` | Only devices reporting this end-user id. |
| `--model` | Only this device model, by identifier (`iPhone18,1`) or the name it is sold under (`"iPhone 17 Pro"`). A name that matches no device is refused rather than matched against nothing. |
| `--at-launch` | Activate during app launch, from the device's persisted state. |
| `--purpose` | Why this capture is being taken, in 140 characters or fewer. Required. |
| `--max-readings`, `--max-frames` | Refuse readings past this many, per device. Every matching device gets its own budget. Uncapped when unset. |
| `--for` | How long to stay live: `30s`, `15m`, `2h`. Defaults to 15m. |
| `--allow-unknown-instruments` | Send instrument names this CLI does not recognize. |

<Callout icon="lightbulb" color="#89e20e">
  Hunting a hitch: the default `concurrency.mainThreadHang:thresholdMs=2000` only catches full freezes — lower it (250–500) for smaller stutters, and pair it with `runtime.stackSamples` (what ran) and `uikit.view.layoutPass` or `swiftui.host.updates` (why). An idle capture finds nothing — drive the UI during the window.
</Callout>

## list

The default when `request` is run with no subcommand. Lists live requests.

```bash theme={"dark"}
basset request list
```

| Flag | Meaning |
| - | - |
| `-a, --app` | Only this app, by name or id. |
| `--all` | Include requests that have already expired. |

## get

Reads the readings a request captured. The stored container is fetched whole and rendered here — the same rendering the dashboard downloads.

```bash theme={"dark"}
basset request get <request-id>
```

| Flag | Meaning |
| - | - |
| `--device` | Which device's readings, when more than one answered. |
| `-f, --format` | Shape to render: `basset`, `markdown`, `json`, `ndjson`, or `csv`. Defaults to a table at a terminal, to the container with `-o`, and to JSON when piped. |
| `-o, --output` | Write to this file instead of stdout. |

At a human terminal, the table renders colored and grouped by launch — a real view-hierarchy tree for `viewHierarchy` readings, not a flat dump. Piped or scripted, it's plain JSON.

## tail

Prints readings as they arrive, then stops. One reading per line as JSON, so a stream cut short still parses up to where it stopped.

```bash theme={"dark"}
basset request tail <request-id>
```

This always ends by itself — a request carries an expiry, so there is no way to start a tail that never returns.

| Flag | Meaning |
| - | - |
| `--for` | Stop after this long: `30s`, `15m`, `2h`. Defaults to when the request expires. |
| `--until-devices` | Stop once this many devices have answered. Useful for one device, once. |
| `--stop-when-done` | Expire the request when this stops, so nothing keeps collecting. |
| `--device` | Only this device's readings. |

Why it ended is written to stderr; the readings are on stdout.

## stop

Stops a live request by expiring it now — the teardown mechanism brought forward. Matching devices stop collecting on their next check-in; readings already stored stay readable.

```bash theme={"dark"}
basset request stop <request-id>
```

Worth doing the moment a capture answers the question, rather than waiting out the TTL: a live request keeps every matching device instrumenting and holding a place in the presence budget.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.