basset request

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.

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.

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.

list

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

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.

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.

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.

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.

Getting Started

SDK

CLI

Instruments

Reference

basset request

create

list

get

tail

stop

​create

​list

​get

​tail

​stop

create

list

get

tail

stop