Trailblaze CLI¶

Trailblaze - AI-powered device automation

Usage¶

trailblaze [OPTIONS] [COMMAND]

Device Claims & Sessions¶

Trailblaze tracks device ownership per MCP session so two CLI workflows on the same machine cannot accidentally drive the same device at the same time. Understanding the model up front saves debugging time when a command unexpectedly returns Error: Device <id> is already in use by another MCP session.

Two execution models¶

One-shot commands — ask, verify, snapshot, tool. Each invocation opens a fresh MCP session, binds the requested device, runs once, and tears the session down. Different-device parallel one-shots are fully isolated.
Reusable workflows — step, step --save, session start/info/save/recording/stop/end/artifacts/delete, device connect. These persist an MCP session under /tmp/trailblaze-cli-session-{port}[-scope] so follow-up commands can reattach. step --save is the canonical reason — each step invocation records steps into a per-device scoped session that step --save later exports as a trail YAML.

Device-claim conflicts (yield-unless-busy)¶

Device-binding commands try to claim the requested device on the daemon. If another MCP session already holds the claim, the daemon decides:

Prior holder is idle → the new command silently displaces it and proceeds. Idle means “no MCP tool call currently executing on that session.”
Prior holder is mid-tool-call → the new command fails with a Device … is busy. block naming the holder, the running tool, and how long it has been running. Wait for it to finish, or stop the holder before retrying.

Same-session re-claims are always allowed, so a step workflow that keeps calling into its own scope never trips on this — only cross-session contention with a busy holder does.

When a `step` scope leaks across commands¶

step --device android "…" opens a cli-android scoped MCP session that stays alive on the daemon after the CLI exits, holding the device claim until step --save (or another step --device android) reattaches. The session is idle while it waits, so a subsequent one-shot like ask --device android just yields and proceeds — the leaked scope no longer blocks unrelated commands. If you want to clear it explicitly, trailblaze app --stop recycles the daemon and drops all in-memory sessions.

Note: session stop ends the global CLI session created by session start. It does not reap device-scoped per-device sessions; use app --stop for those.

Global Options¶

Option	Description	Default
`--stop`	Stop the running daemon and exit.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

Commands¶

Command	Description
`step`	Run one step — describe what you want, the built-in agent picks the tools.
`ask`	Ask a question about what’s on screen (uses AI vision, no actions taken)
`verify`	Check a condition on screen and pass/fail (exit code 0/1, ideal for CI)
`snapshot`	Capture the current screen’s UI tree (fast, no AI, no actions)
`tool`	Run a Trailblaze tool by name (e.g., tap, inputText)
`toolbox`	Browse available tools by target app and platform
`run`	Run a trail file (.trail.yaml) — execute a scripted test on a device.
`usages`	Find every trail that directly invokes a tool (IDE “Find Usages” for tools).
`session`	Manage the current device session — save it as a replayable trail, inspect steps, end it
`report`	Generate an HTML report (plus JSON summary, optional MP4/GIF/WebP) for session recordings.
`strings`	Extract the human-visible text a recorded session showed, for localization and copy diffs
`viewer`	Write out the standalone report viewer (one self-contained HTML page).
`profile`	Generate a performance-analysis report (tools, LLM calls, timeouts, idle gaps) for a logs directory.
`otel`	Convert recorded spans to OpenTelemetry (OTLP/JSON files, optionally posted to an endpoint).
`waypoint`	Match named app locations (waypoints) against captured screen state.
`results`	Query the persisted test-result index for a test case.
`config`	View and set configuration (target app, device defaults, AI provider)
`device`	List and connect devices (Android, iOS, Web)
`show`	Open the multi-device live grid (/devices/all) in your default browser
`app`	Launch the legacy Trailblaze desktop app (use –v2 for Trail Runner or –headless for a daemon-only background service).
`mcp`	Start a Model Context Protocol (MCP) server for AI agent integration
`check`	Validate a trailmap: materialize manifests, type-check its TypeScript, run its `*.test.ts` tests.
`inprocess`	Check an app APK for in-process driver compatibility, and build a test APK that drives it.
`skill`	Print or install the bundled agent skill that teaches a coding agent this CLI
`companion`	Attach a coding agent to Trail Runner while it authors a trail.

`trailblaze step`¶

Run one step — describe what you want, the built-in agent picks the tools. Requires an LLM provider configured (trailblaze config llm).

Synopsis:

trailblaze step [OPTIONS] [<<stepWords>>]

Arguments:

Argument	Description	Required
`<<stepWords>>`	Step description, or assertion when `--verify` is set (e.g., ‘Tap login’, ‘The email field is visible’)	No

Options:

Option	Description	Default
`--verify`	Verify an assertion instead of taking an action (exit code 1 if assertion fails)	-
`-d`, `--device`	Device: platform (android, ios, web) or platform/id. Defaults to `$TRAILBLAZE_DEVICE` if set (manual override; rare), otherwise this terminal’s pin (set by `trailblaze device connect`). In a fresh-shell harness (Claude Code, Cursor, Codex, CI), pass –device on every call.	-
`--context`	Context from previous steps for situational awareness	-
`-v`, `--verbose`	Enable verbose output (show daemon logs, MCP calls)	-
`--target`	Target app ID for this command’s bound device. Defaults to `$TRAILBLAZE_TARGET` if set, otherwise the target you passed to `trailblaze device connect --target X` for this terminal (persists in this terminal’s pin; cleared by `device disconnect`, replaced by `device rebind --target Y`). Pass `--target=clear` to remove a previously-set override for this device. To set a persistent default, use `trailblaze config target`. List available targets with `trailblaze toolbox` (no args).	-
`--no-screenshots`, `--text-only`	Skip screenshots — the LLM only sees the textual view hierarchy, no vision tokens, and disk logging of screenshots is skipped too. Faster and cheaper for short objectives where the visual layout doesn’t matter; some tasks need vision and will degrade without it.	-
`--snapshot-details`	Comma-separated snapshot detail levels passed through to the daemon’s step tool: BOUNDS, OFFSCREEN, OCCLUDED, ALL_ELEMENTS. Useful for waypoint capture: ALL_ELEMENTS bypasses the on-device accessibility-importance filter so RecyclerView children land in the captured trailblazeNodeTree. OCCLUDED is web-only and surfaces elements hidden under popups/modals so the captured tree includes what’s actually behind the overlay.	-
`--save`	Save current session as a trail file. Shows steps if –setup not specified.	-
`--setup`	Step range for setup/trailhead (e.g., ‘1-3’). Use with –save.	-
`--no-setup`	Save without setup steps. Use with –save.	-
`--headless`	For –device web/…: launch the Playwright browser headless. When omitted, auto-detects: headless on machines with no display (remote workstations, CI), headed otherwise. Falls back to the persisted `web-headless` config when a display is present (see `trailblaze config web-headless`). Pass –headless=false to force a visible browser, –headless=true to force headless. Ignored for non-web devices.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze ask`¶

Ask a question about what’s on screen (uses AI vision, no actions taken)

Synopsis:

trailblaze ask [OPTIONS] <<questionWords>>

Arguments:

Argument	Description	Required
`<<questionWords>>`	Question about the screen (e.g., ‘What’s the current balance?’)	Yes

Options:

Option	Description	Default
`-d`, `--device`	Device: platform (android, ios, web) or platform/id. Defaults to `$TRAILBLAZE_DEVICE` if set (manual override; rare), otherwise this terminal’s pin (set by `trailblaze device connect`). In a fresh-shell harness (Claude Code, Cursor, Codex, CI), pass –device on every call.	-
`-v`, `--verbose`	Enable verbose output (show daemon logs, MCP calls)	-
`--headless`	For –device web/…: launch the Playwright browser headless. When omitted, auto-detects: headless on machines with no display (remote workstations, CI), headed otherwise. Falls back to the persisted `web-headless` config when a display is present (see `trailblaze config web-headless`). Pass –headless=false to force a visible browser, –headless=true to force headless. Ignored for non-web devices.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze verify`¶

Check a condition on screen and pass/fail (exit code 0/1, ideal for CI)

Synopsis:

trailblaze verify [OPTIONS] <<assertionWords>>

Arguments:

Argument	Description	Required
`<<assertionWords>>`	Assertion to verify (e.g., ‘The Sign In button is visible’)	Yes

Options:

Option	Description	Default
`-d`, `--device`	Device: platform (android, ios, web) or platform/id. Defaults to `$TRAILBLAZE_DEVICE` if set (manual override; rare), otherwise this terminal’s pin (set by `trailblaze device connect`). In a fresh-shell harness (Claude Code, Cursor, Codex, CI), pass –device on every call.	-
`-v`, `--verbose`	Enable verbose output	-
`--no-screenshots`, `--text-only`	Skip screenshots — the LLM only sees the textual view hierarchy, no vision tokens, and disk logging of screenshots is skipped too. Faster and cheaper for short objectives where the visual layout doesn’t matter; some tasks need vision and will degrade without it.	-
`--headless`	For –device web/…: launch the Playwright browser headless. When omitted, auto-detects: headless on machines with no display (remote workstations, CI), headed otherwise. Falls back to the persisted `web-headless` config when a display is present (see `trailblaze config web-headless`). Pass –headless=false to force a visible browser, –headless=true to force headless. Ignored for non-web devices.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze snapshot`¶

Capture the current screen’s UI tree (fast, no AI, no actions)

Synopsis:

trailblaze snapshot [OPTIONS]

Options:

Option	Description	Default
`-d`, `--device`	Device: platform (android, ios, web) or platform/id. Defaults to `$TRAILBLAZE_DEVICE` if set (manual override; rare), otherwise this terminal’s pin (set by `trailblaze device connect`). In a fresh-shell harness (Claude Code, Cursor, Codex, CI), pass –device on every call.	-
`-v`, `--verbose`	Enable verbose output	-
`--bounds`	Include bounding box {x,y,w,h} for each element	-
`--offscreen`	Include offscreen elements marked (offscreen)	-
`--screenshot`	Save a screenshot to disk and print the file path	-
`--all`	Show all visible elements, including those normally filtered as non-interactive	-
`--headless`	For –device web/…: launch the Playwright browser headless. When omitted, auto-detects: headless on machines with no display (remote workstations, CI), headed otherwise. Falls back to the persisted `web-headless` config when a display is present (see `trailblaze config web-headless`). Pass –headless=false to force a visible browser, –headless=true to force headless. Ignored for non-web devices.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze tool`¶

Run a Trailblaze tool by name (e.g., tap, inputText)

Synopsis:

trailblaze tool [OPTIONS] [<<toolName>>] [<<argPairs>>]

Arguments:

Argument	Description	Required
`<<toolName>>`	Tool name (e.g., web_click, tap)	No
`<<argPairs>>`	Tool arguments as key=value pairs (e.g., ref=”Sign In”)	No

Options:

Option	Description	Default
`-s`, `--step`, `--objective`, `-o`	Natural language step — describe what, not how. If the UI changes, Trailblaze uses this to retry the step with AI. ‘Navigate to Settings’ survives a redesign; ‘tap button at 200,400’ does not. Optional by default; required when `trailblaze config require-steps true` is set. (`--objective` / `-o` are deprecated aliases of `--step` / `-s`.)	-
`--yaml`	Raw YAML tool sequence (multiple tools in one call)	-
`-d`, `--device`	Device: platform (android, ios, web) or platform/id. Defaults to `$TRAILBLAZE_DEVICE` if set (manual override; rare), otherwise this terminal’s pin (set by `trailblaze device connect`). In a fresh-shell harness (Claude Code, Cursor, Codex, CI), pass –device on every call.	-
`-v`, `--verbose`	Enable verbose output	-
`--no-screenshots`, `--text-only`	Skip screenshots — the LLM only sees the textual view hierarchy, no vision tokens, and disk logging of screenshots is skipped too. Faster and cheaper for short objectives where the visual layout doesn’t matter; some tasks need vision and will degrade without it.	-
`--target`	Target app ID for this command’s bound device. Defaults to `$TRAILBLAZE_TARGET` if set, otherwise the target you passed to `trailblaze device connect --target X` for this terminal (persists in this terminal’s pin; cleared by `device disconnect`, replaced by `device rebind --target Y`). Pass `--target=clear` to remove a previously-set override for this device. To set a persistent default, use `trailblaze config target`. List available targets with `trailblaze toolbox` (no args).	-
`--headless`	For –device web/…: launch the Playwright browser headless. When omitted, auto-detects: headless on machines with no display (remote workstations, CI), headed otherwise. Falls back to the persisted `web-headless` config when a display is present (see `trailblaze config web-headless`). Pass –headless=false to force a visible browser, –headless=true to force headless. Ignored for non-web devices.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze toolbox`¶

Browse available tools by target app and platform

Synopsis:

trailblaze toolbox [OPTIONS] [<ROLE>]

Arguments:

Argument	Description	Required
`<ROLE>`	Optional role filter — show only tools tagged with this role. Valid values: trailheads, shortcuts. trailheads — tools that bring the device to a known starting state (launch + sign-in, deep-link, etc.). Use one at the start of every trail. shortcuts — tools that jump between named waypoints during a trail. Omit to show everything; trailheads and shortcuts will be called out as headline sections above the toolset listing.	No

Options:

Option	Description	Default
`--name`, `-n`	Show details for a single tool by name	-
`--target`, `-t`	Target app to show tools for. Optional — defaults to $TRAILBLAZE_TARGET (per-shell pin), then the workspace `trailblaze config target`, falling back to the built-in ‘default’.	-
`--search`, `-s`	Substring search on tool name and description.	-
`-d`, `--device`	Device: platform (android, ios, web) or platform/id. Defaults to `$TRAILBLAZE_DEVICE` if set (manual override; rare), otherwise this terminal’s pin (set by `trailblaze device connect`). In a fresh-shell harness (Claude Code, Cursor, Codex, CI), pass –device on every call.	-
`--detail`	Show full parameter descriptions for all tools	-
`-v`, `--verbose`	Enable verbose output	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze run`¶

Run a trail file (.trail.yaml) — execute a scripted test on a device. Accepts files, shell globs, or directories. Directory arguments expand recursively to every named unified trail (<scenario>.trail.yaml), plus one pick per legacy trail (recording preferred over NL when both are present). Trail-level metadata honored by the runner: - tags: (list of strings) — filtered via –tags. - skip: (reason string) — reported as skipped (reason printed, contributes to the N skipped summary tally) and exits 0 for that file’s slot. Blank/whitespace skip: is ignored. To run a skipped trail, remove its skip: line. Note: trailblaze trail is a deprecated alias for trailblaze run and will be removed in a future release.

Synopsis:

trailblaze run [OPTIONS] [<<trailFile>>]

Arguments:

Argument	Description	Required
`<<trailFile>>`	Trail files (.trail.yaml or blaze.yaml), shell globs, or directories. Directories expand recursively to every named unified trail, plus one pick per legacy trail (recording preferred over NL when both are present). Bare `trailblaze run` with no arguments is rejected as a misuse — pass a `.trail.yaml` path or name a directory (e.g. `trails/`) to fan out under a workspace’s trails directory.	No

Options:

Option	Description	Default
`--tags`	Only run trails whose `config.tags:` list contains at least one of the given names. Repeatable (`--tags smoke --tags login`) or comma-separated (`--tags smoke,login`). Match is OR across tags. Untagged trails are excluded when –tags is specified.	-
`-d`, `--device`	Device(s) to run on: `<platform>` (e.g. android), `<platform>/<instanceId>`, or a bare instanceId. Comma-separated or repeatable to run each trail on SEVERAL devices (`--device android,ios` → one run per device). When omitted, resolves to a pinned (`trailblaze device connect` / `TRAILBLAZE_DEVICE`) or single connected device; when 2+ devices are connected and none is pinned, the run fails and asks you to pass this (or `--driver` / `--all-devices`). See also –all-devices.	-
`--device-classifier`	Select a locale/variant-qualified recording for this run (for example `ios-iphone-es`). The key must refine the connected device’s detected classifiers. Only valid for a single-device run.	-
`--all-devices`	Run each trail on EVERY connected device whose platform the trail supports (its `platform:`/`driver:` for v1, or its `devices:`/recording classifiers for the unified format). The opt-in way to exercise a multi-target trail across platforms in one command. Mutually exclusive with `--device` (passing both is rejected). Connected devices that don’t match any supported platform are skipped.	-
`--bind`	Bind a multi-device trail’s COMPANION devices for this run: `--bind buyer=emulator-5562`. Repeatable or comma-separated. The names come from the trail’s `config.devices:` configuration; the START device is the one `--device` names and must NOT be bound here. Per-run, so two multi-device trails can run concurrently against different device sets on one daemon — which `TRAILBLAZE_DEVICE_BINDINGS` cannot express (it is daemon-wide, and changing it needs a daemon restart). Takes precedence over that env var when passed.	-
`--configuration`	Select which of a trail’s `config.devices:` configurations to run when it declares more than one. Per-run, like –bind. Naming a configuration a single-device trail does not declare is an error rather than a silent single-device run.	-
`-a`, `--agent`	Agent implementation name for AI-driven steps: TRAILBLAZE_RUNNER, MULTI_AGENT_V3, or KOOG_STRATEGY_GRAPH. Set it persistently with ‘trailblaze config agent’. Default: KOOG_STRATEGY_GRAPH	-
`--use-recorded-steps`	Three-way switch for replay vs. AI-driven execution: –use-recorded-steps Force replay mode (use the trail’s `recording:` tools verbatim). –no-use-recorded-steps Force AI mode (ignore any recordings; LLM drives each step from `step:` NL). (unset, default) Auto-detect: AI mode if no `recording:` blocks present, replay if they are. Use –no-use-recorded-steps to re-run a trail with stale selectors and let the agent re-pick selectors from current page state.	-
`--self-heal`	When a recorded step fails, let AI take over and continue. Overrides the persisted ‘trailblaze config self-heal’ setting for this run. Omit to inherit the saved setting (opt-in, off by default).	-
`--snapshot-baseline`	Diff this run’s `takeSnapshot` captures against a PREVIOUS run instead of checked-in golden files. is an http(s) URL to a session logs zip (e.g. the CI artifact store’s latest_success.zip), a local zip, or an extracted session directory. Snapshots are matched by name; a snapshot missing from the baseline is skipped, a resolvable mismatch above the threshold fails the run, and an unresolvable fails it too. Alternatively set TRAILBLAZE_SNAPSHOT_BASELINE on the executing process (the daemon for delegated runs).	-
`--snapshot-baseline-threshold`	Pass threshold for –snapshot-baseline: a snapshot passes when its pixel diff percentage is <= this value. Default: 2.0 (or TRAILBLAZE_SNAPSHOT_BASELINE_THRESHOLD when set).	-
`-v`, `--verbose`	Enable verbose output	-
`--driver`	Driver type to use (e.g., PLAYWRIGHT_NATIVE, ANDROID_ONDEVICE_ACCESSIBILITY). Overrides driver from trail config.	-
`--headless`	Launch the Playwright browser headless (default true). Pass –no-headless or –headless=false to surface a visible window. Equivalent to –show-browser when negated.	-
`--llm`	LLM provider/model shorthand (e.g., openai/gpt-4-1). Mutually exclusive with –llm-provider and –llm-model.	-
`--llm-provider`	LLM provider override (e.g., openai, anthropic, google)	-
`--llm-model`	LLM model ID override (e.g., gemini-3-flash, gpt-4-1)	-
`--memory`	Pre-populate trail memory with KEY=VAL before any step runs. Repeatable (`--memory user=sam --memory accountTier=PRO`). Overrides any value with the same key in the trail YAML’s `config.memory:` block. Values are strings; keys must be non-empty. Visible to `{{name}}` interpolation and to scripted tools via `ctx.memory.get(name)`. Values are logged in cleartext and persisted into the session-start snapshot — use –secret for passwords, tokens, or other sensitive data.	-
`--secret`	Pre-populate trail memory with a SENSITIVE KEY=VAL before any step runs. Same shape as –memory; the value is redacted in logs (via `rememberSensitive`), excluded from the scripting envelope, and omitted from the session-start snapshot. Only the KEY appears in `Started.sensitiveMemoryKeys` so replay knows it must re-supply the value. Repeatable. Use for passwords, tokens, API keys, PII.	-
`--arg`	Supply a value for a parameter the trail DECLARES under `config.args:`. Repeatable (`--arg recipient=sam@example.com --arg retries=3`). Unlike –memory, args are declared and typed: the value is coerced to the arg’s declared type, a missing required arg fails before the run starts, and an undeclared arg is rejected. Referenced as `{{args.name}}` in prompts and tool params. Overrides an –args-file entry with the same key. The value is always a string here; declaration-driven coercion turns `retries=3` into a number for an `integer` arg. Use –args-file for structured (array/object) values. Arg values are logged in cleartext, persisted into logs/recordings, and surfaced to the LLM — args are non-sensitive by design. Route passwords, tokens, or other sensitive data through –secret memory instead.	-
`--args-file`	Read parameter values from a YAML or JSON file (a map of arg-name to value). Applied BEFORE –arg, so a –arg KEY=VAL overrides the file entry with the same key. A YAML-null value is rejected (args have no null) — use ‘’ for an empty string. Arg values are logged in cleartext, persisted into logs/recordings, and surfaced to the LLM — args are non-sensitive by design. Route passwords, tokens, or other sensitive data through –secret memory instead.	-
`--max-llm-calls`	Cap the number of LLM calls per objective for the TRAILBLAZE_RUNNER and KOOG_STRATEGY_GRAPH agents. Useful on metered or expensive providers to cut off a stuck self-heal loop. Must be a positive integer. Default: 25 (both agents’ built-in cap). Not compatible with –agent MULTI_AGENT_V3.	-
`--no-report`	Skip HTML report generation after execution	-
`--full-report-payloads`	Embed full event payloads in the after-run HTML report even for sessions that passed, instead of applying the report size budgets (which truncate large successful network bodies and elide repeated intermediate snapshots to keep the report small). Failed sessions always embed full payloads regardless. The on-disk events/ artifacts are never budgeted, so an existing session can also be regenerated in full later via `trailblaze report --full-report-payloads`. Applies to in-process runs; a run delegated to an already-running daemon doesn’t generate a report from this process.	-
`--save-recording`	Save the recording back to the trail source directory after a successful run. Default: on. Use –no-save-recording to skip. Even when on, the recording is only saved when –self-heal was enabled OR this device isn’t recorded yet — deterministic re-runs no-op the write so they can’t clobber a hand-edited source.	-
`--no-logging`	Disable session logging — no files written to logs/, session does not appear in Sessions tab	-
`--markdown`	Generate a markdown report after execution	-
`--no-daemon`	Run in-process without delegating to or starting a persistent daemon. The server shuts down when the run completes.	-
`--compose-port`	RPC port for Compose driver connections (default: 52600)	-
`--turbo`	Turbo mode: let the Android app under test report when it is idle so the driver waits less after each action, instead of watching for its screen to go quiet. Each wait ends at whichever answer comes first, so this can only make a run faster, never slower. Needs an app signed with a key this build carries a helper for (debug and internal builds; not release or beta) — a run that can’t use it says so and runs at normal speed. When neither flag is passed, inherits TRAILBLAZE_TURBO and the saved `trailblaze config turbo` setting.	-
`--capture-video`	Record device screen video for the session. Off by default — video writes large files and sprite extraction is expensive — pass –capture-video to enable it for a run. When neither flag is passed, inherits TRAILBLAZE_CAPTURE_VIDEO and the saved `trailblaze config capture-video` setting.	-
`--capture-logcat`	Capture Android logcat (filtered to the app under test) to /device.log (only takes effect on Android). Recognized fatal crashes are also indexed in /events/crash.ndjson. On by default; use –no-capture-logcat to disable.	-
`--capture-ios-logs`	Capture the iOS Simulator system log via `xcrun simctl spawn log stream` to /device.log (only takes effect on iOS). On by default; the stream is scoped to the app under test (the logcat-equivalent app log, not the system firehose). Recognized fatal crashes are also indexed in /events/crash.ndjson. Use –no-capture-ios-logs to disable.	-
`--capture-network`	Auto-capture network requests/responses to /network.ndjson on supported devices (web today; mobile devices added as engines land). Mirrors the desktop-app “Capture Network Traffic” toggle. On by default; use –no-capture-network to disable. When neither flag is passed, inherits the desktop app’s saved setting.	-
`--capture-all`	Enable all capture streams: video, logcat, iOS logs, network (local dev mode)	-
`--test-name`	Override the test name used as the session ID seed. When set, replaces the default name derived from the trail filename. Useful in CI environments where the caller can supply a richer identifier (e.g. including suite/section/case context).	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze usages`¶

Find every trail that directly invokes a tool (IDE “Find Usages” for tools). Scans the trails directory’s recordings via the parsed trail model, so each usage reports WHICH device classifiers invoke the tool — not just which trails. Typical uses: before editing a tool, list the trails (and platforms) that would exercise the change; before deleting one, confirm nothing invokes it.

Synopsis:

trailblaze usages [OPTIONS] [<<tool>>]

Arguments:

Argument	Description	Required
`<<tool>>`	Tool name(s) to find trail usages for (e.g. myapp_launchSignedIn).	No

Options:

Option	Description	Default
`--changed-since`	Instead of naming tools, derive them: compare the workspace’s scripted tools against git and report usages for every tool that was added, removed, or modified. Detection hashes each tool’s source together with its resolved import closure, so editing a shared helper flags every tool that imports it.	-
`--json`	Emit the machine-readable JSON report (schemaVersion 1) to stdout instead of the human-readable summary.	-
`--trails`	Trails directory to scan. Repeatable — a repo whose trails live under more than one root scans them all in one pass, and every reported usage names the root it was found under. Order matters: the FIRST one is the primary root, which is what the report names and what –changed-since walks up from to find the workspace’s trailmaps. Passing any –trails replaces the configured roots rather than adding to them. Default: the workspace’s effective trails directory (TRAILBLAZE_TRAILS_DIR, the workspace `trails:` declaration, or the configured default) plus any extra roots configured in Trail Runner.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze session`¶

Manage the current device session — save it as a replayable trail, inspect steps, end it

Synopsis:

trailblaze session [OPTIONS]
trailblaze session start
trailblaze session stop
trailblaze session save
trailblaze session recording
trailblaze session info
trailblaze session list
trailblaze session artifacts
trailblaze session delete
trailblaze session end

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze session start`¶

Start a new session with automatic video and log capture

Synopsis:

trailblaze session start [OPTIONS]

Options:

Option	Description	Default
`--target`	Target app ID for this session’s bound device. Defaults to `$TRAILBLAZE_TARGET` if set, otherwise the target you passed to `trailblaze device connect --target X` for this terminal (persists in this terminal’s pin; cleared by `device disconnect`, replaced by `device rebind --target Y`). Pass `--target=clear` to remove a previously-set override. To set a persistent default, use `trailblaze config target`.	-
`--mode`	Working mode: trail or blaze. Saved to config for future commands.	-
`-d`, `--device`	Device: platform (android, ios, web) or platform/id. Defaults to `$TRAILBLAZE_DEVICE` if set (manual override; rare), otherwise this terminal’s pin (set by `trailblaze device connect`). In a fresh-shell harness (Claude Code, Cursor, Codex, CI), pass –device on every call.	-
`--bind`	Start a MULTI-DEVICE session: bind each device under a NAME, e.g. `--bind seller=emulator-5554 --bind buyer=emulator-5556`. Repeatable or comma-separated; the session’s cast is exactly the bound devices. The FIRST bind is the start device (same ordered semantics as a trail’s `config.devices:`); pass –device naming one bind’s DEVICE_ID to start on that entry instead. Each name must bind a DIFFERENT device — two names on one device is refused. `switchDevice(name=…)` hands the session between the names. Follow-up commands (`step`, `verify`, `session info`, `session stop`) reach the roster with the –device value the start prints.	-
`--title`	Title for the session (used as trail name when saving)	-
`--no-video`	Disable video capture	-
`--no-logs`	Disable device log capture	-
`-v`, `--verbose`	Enable verbose output	-
`--headless`	For –device web/…: launch the Playwright browser headless. When omitted, auto-detects: headless on machines with no display (remote workstations, CI), headed otherwise. Falls back to the persisted `web-headless` config when a display is present (see `trailblaze config web-headless`). Pass –headless=false to force a visible browser, –headless=true to force headless. Ignored for non-web devices.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze session stop`¶

Stop the current session and finalize captures

Synopsis:

trailblaze session stop [OPTIONS]

Options:

Option	Description	Default
`-d`, `--device`	Device: platform (android, ios, web) or platform/id. Defaults to `$TRAILBLAZE_DEVICE` if set (manual override; rare), otherwise this terminal’s pin (set by `trailblaze device connect`). In a fresh-shell harness (Claude Code, Cursor, Codex, CI), pass –device on every call.	-
`--save`	Save session as a trail before stopping	-
`--title`, `-t`	Trail title when saving (overrides session title)	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze session save`¶

Write the recorded steps to a *.trail.yaml file you can replay later (does not end the session)

Synopsis:

trailblaze session save [OPTIONS]

Options:

Option	Description	Default
`--title`, `-t`	Title for the saved trail (uses session title if not specified)	-
`--id`	Session ID to save (defaults to current session, supports prefix matching)	-
`-d`, `--device`	Save the CLI session pinned to this device — pass the same value given to `session start -d`. Required to save a multi-device session started with `session start --bind`: its named-device roster lives on that per-device session, and the save synthesizes the trail’s `config.devices:` cast from it.	-
`--configuration`	Name for the multi-device configuration saved from the session’s named-device roster (from `session start --bind`). Defaults to the bound names joined with ‘-‘, e.g. a seller,buyer roster saves as `seller-buyer`. The name is a recommendation — rename it in the saved file freely. It becomes a YAML key, so it must start with a letter or digit and hold only letters, digits, ‘-‘, ‘_’ and ‘.’. Only meaningful for a roster session; on a session that bound a trail-declared configuration it may only restate that configuration’s name.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze session recording`¶

Output the recording YAML for a session

Synopsis:

trailblaze session recording [OPTIONS] [<<session-id>>]

Arguments:

Argument	Description	Required
`<<session-id>>`	Session ID (positional form of –id, defaults to current session, supports prefix matching). Mutually exclusive with –id.	No

Options:

Option	Description	Default
`--id`	Session ID (defaults to current session, supports prefix matching). Equivalent to the positional form.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze session info`¶

Show information about a session

Synopsis:

trailblaze session info [OPTIONS] [<<session-id>>]

Arguments:

Argument	Description	Required
`<<session-id>>`	Session ID (positional form of –id, defaults to current session). Mutually exclusive with –id.	No

Options:

Option	Description	Default
`--id`	Session ID (defaults to current session). Equivalent to the positional form.	-
`-d`, `--device`	Inspect the CLI session pinned to this device — pass the same value given to `session start -d` / `step -d`. Adds the session’s named-device roster (from `session start --bind`) and its ACTIVE device to the output. The roster describes the devices bound right now, so it is omitted when a session id is also given.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze session list`¶

List recent sessions

Synopsis:

trailblaze session list [OPTIONS]

Options:

Option	Description	Default
`--limit`, `-n`	Maximum number of sessions to show (default: 10)	-
`--all`, `-a`	Show all sessions in a flat chronological list	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze session artifacts`¶

List artifacts in a session

Synopsis:

trailblaze session artifacts [OPTIONS] [<<session-id>>]

Arguments:

Argument	Description	Required
`<<session-id>>`	Session ID (positional form of –id, defaults to current session). Mutually exclusive with –id.	No

Options:

Option	Description	Default
`--id`	Session ID (defaults to current session). Equivalent to the positional form.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze session delete`¶

Delete a session’s logs and artifacts

Synopsis:

trailblaze session delete [OPTIONS] [<<session-id>>]

Arguments:

Argument	Description	Required
`<<session-id>>`	Session ID to delete (positional form of –id, supports prefix matching). Mutually exclusive with –id; one of the two is required.	No

Options:

Option	Description	Default
`--id`	Session ID to delete (supports prefix matching). Equivalent to the positional form.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze session end`¶

End the CLI session and release the device (deprecated: use ‘stop’ instead)

Synopsis:

trailblaze session end [OPTIONS]

Options:

Option	Description	Default
`-d`, `--device`	Device: platform (android, ios, web) or platform/id. Defaults to `$TRAILBLAZE_DEVICE` if set (manual override; rare), otherwise this terminal’s pin (set by `trailblaze device connect`). In a fresh-shell harness (Claude Code, Cursor, Codex, CI), pass –device on every call.	-
`--name`, `-n`	Save the recording as a trail before ending	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze report`¶

Generate an HTML report (plus JSON summary, optional MP4/GIF/WebP) for session recordings. JSON-only failures log a warning and still exit 0 — HTML is the primary artifact and is what gates the exit code. Animated exports collapse long idle gaps between steps so their length tracks the number of steps, not the session’s real wall-clock. The capture window for all three (–gif/–webp/–video) is bounded by the MAX_PLAYBACK_WAIT_MS environment variable (milliseconds, default 600000); if playback overruns it, a best-effort truncated artifact is still written with a warning.

Synopsis:

trailblaze report [OPTIONS] [<<session-id>>]

Arguments:

Argument	Description	Required
`<<session-id>>`	Session ID to narrow the report to (positional form of –id). Prefix matching is supported. Mutually exclusive with –id and –current.	No

Options:

Option	Description	Default
`--id`	Narrow to a single session (defaults to all sessions). Use `trailblaze session list` to find IDs. Prefix matching is supported. Equivalent to passing the session ID positionally.	-
`--current`	Narrow to the currently active session (resolved via the running daemon). Mutually exclusive with –id.	-
`--open`	Open the HTML report in the default browser after generation.	-
`--output-dir`	Write all artifacts into this directory with canonical names (report-interactive.html, summary.json, timeline.mp4, timeline.gif, timeline.webp). Created if it doesn’t exist. If omitted, artifacts land in the default `logs/reports/` location with timestamped names.	-
`--video`	Export the HTML report’s timeline autoplay (the scrubbing view with step labels and annotations) as an MP4. NOT the raw device recording — that’s a separate artifact in the session’s logs dir. Path defaults to /.mp4 (or /timeline.mp4 when –output-dir is set). Single-session only — pass –id or –current.	-
`--gif`	Export the HTML report’s timeline autoplay (the scrubbing view with step labels and annotations) as an animated GIF. NOT the raw device recording. Path defaults to /.gif (or /timeline.gif when –output-dir is set). Smaller and easier to paste into a PR than –video, at the cost of a lower frame rate and 256-color palette. Single-session only — pass –id or –current. Frame capture is shared with –webp: passing this bare (no path) auto-emits a companion .webp at the default path for free — pass –no-webp to suppress. An explicit path here limits output to just that file.	-
`--webp`	Export the HTML report’s timeline autoplay (the scrubbing view with step labels and annotations) as an animated WebP. NOT the raw device recording. Path defaults to /.webp (or /timeline.webp when –output-dir is set). Typically 25–50% smaller than the equivalent –gif (24-bit color, inter-frame deltas) — useful when the GIF would push past GitHub’s 10MB inline attachment limit. GitHub renders animated WebP inline the same as GIF. Single-session only — pass –id or –current. Frame capture is shared with –gif: passing this bare (no path) auto-emits a companion .gif at the default path for free — pass –no-gif to suppress. An explicit path here limits output to just that file.	-
`--storyboard`	Export a single-frame WebP storyboard — every step’s screenshot tiled into a CSS grid (one cell per executed action / taken snapshot, labeled with the action verb), then full-page-screenshotted via headless Playwright and encoded to WebP. Complements –gif/–webp (which play through the timeline over time) — embed both in a PR comment to get glance-overview plus the animated walkthrough. A companion .html with the same content is written alongside the WebP for standalone viewing. Path defaults to /.storyboard.webp (or /storyboard.webp when –output-dir is set). Single-session only — pass –id or –current.	-
`--storyboard-columns`	Number of columns in the –storyboard grid. When omitted, the exporter auto-picks by cell aspect ratio: landscape-majority sessions (desktop / tablet) get 3 columns so each cell stays meaningfully large at GitHub’s ~760px embed width without burning vertical space, portrait-majority sessions (phone) get 4 columns for denser inline glance. The auto-pick decision (landscape-cell count, threshold) is logged so the chosen value is visible from the CLI tail. Pass an explicit value to override (e.g. 6 / 8 for very long sessions that would otherwise force the auto-fit cell-width shrink — spreading wider on the page is cleaner than thumbnailing the cells).	-
`--storyboard-yaml`	Annotate each –storyboard cell with the YAML form of the recordable tool that produced it (looked up by traceId against the session’s TrailblazeToolLog entries). The YAML strip replaces the synthesized verb/sublabel line — strictly more informative for “what was invoked here” triage. Cells without a sibling tool log fall back to the verb line. CSS Grid aligns rows to their tallest YAML so a short YAML doesn’t pay the cost of a long one elsewhere. Capped at 20 lines per cell as a sanity bound. Default: on. Pass –no-storyboard-yaml to suppress (reduces total rendered height by ~20% on a typical session, at the cost of less actionable per-cell labels). Has no effect without –storyboard.	-
`--no-gif`	Suppress the auto-emitted .gif companion when –webp is requested with a bare flag. Use this on scripts and CI flows that only embed the .webp and want to skip the wasted GIF encode. Mutually exclusive with –gif.	-
`--no-webp`	Suppress the auto-emitted .webp companion when –gif is requested with a bare flag. Mutually exclusive with –webp.	-
`--max-size`	Cap each exported artifact (–gif / –video / –webp / –storyboard) at the given byte size. Defaults to 10MB — GitHub’s inline-attachment limit — so an export you paste into a PR fits without having to think about it. Accepts plain bytes (1024000) or human-readable suffixes (10MB, 5M, 1.5G); pass `none` (or `0`) for a genuinely uncapped export. After the initial encode, the exporter iteratively re-encodes at smaller viewport widths (1280→1024→720→640→480) until the artifact fits, then stops. If even the readability floor (480px) is still over the cap: an explicitly-passed –max-size fails the export with an actionable error, while the 10MB default keeps the oversized artifact and warns instead — a default you didn’t ask for never turns a working export into a failure. Either way the remedies are the same: drop GIF for –webp or –video (both compress dramatically better), or shorten the recorded session (fewer trail steps, or split into multiple sessions). The cap is applied per artifact, so `--gif --webp --max-size=10MB` caps each one independently.	-
`--full-report-payloads`	Embed full event payloads in the interactive report even for sessions that passed, instead of applying the report size budgets (which truncate large successful network bodies and elide repeated intermediate snapshots to keep the report small). Failed sessions always embed full payloads regardless. The on-disk events/ artifacts are never budgeted, so any session can be regenerated in full with this flag at any time.	-
`--share-url`	Bake a canonical hosted URL (http/https) into the interactive report. Its Copy link button then produces deep links against that URL — with the current view, sort, run, and step grafted on as query parameters — no matter where the file is opened from (including file://). Use this when the report is published to a known location, e.g. a CI artifact URL or an internal report server. Without this flag, Copy link uses the browser’s own address and only appears on http(s) pages.	-
`-v`, `--verbose`	Show the generator’s own progress logs — workspace config loading, tool-class discovery, per-session clock normalisation, and step timings. Suppressed by default so the report paths are the output; turn this on when a report is slow or empty and you need to see which session the generator was working on.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze strings`¶

Extract the human-visible text a recorded session showed, for localization and copy diffs

Synopsis:

trailblaze strings [OPTIONS]
trailblaze strings extract
trailblaze strings diff

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze strings extract`¶

Write visible-strings.ndjson into each session’s directory. One line per screen capture, keyed by the screenshot filename so every string traces back to its image.

Synopsis:

trailblaze strings extract [OPTIONS] [<<session-id>>]

Arguments:

Argument	Description	Required
`<<session-id>>`	Session ID or unambiguous prefix. Defaults to every session in the logs directory.	No

Options:

Option	Description	Default
`--all`	Keep the strings on every capture. By default a capture that repeats the previous screen’s text is recorded as a repeat with its strings omitted.	-
`--logs-dir`	Directory to read sessions from. Defaults to the configured logs directory.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze strings diff`¶

Compare two visible-strings.ndjson files step by step. Meaningful only for a mechanical trail: an LLM-driven objective takes a different path each run, so its step numbers do not line up across runs.

Synopsis:

trailblaze strings diff [OPTIONS] <<baseline.ndjson>> <<candidate.ndjson>>

Arguments:

Argument	Description	Required
`<<baseline.ndjson>>`	The run to compare against.	Yes
`<<candidate.ndjson>>`	The run to check.	Yes

Options:

Option	Description	Default
`--untranslated`	Report the strings both runs show verbatim instead of the ones that changed. Run the same trail at two locales and this is the list of screens nobody translated.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze viewer`¶

Write out the standalone report viewer (one self-contained HTML page). Serve it anywhere, or just open it: drop a session archive on the page, or point it at one with ?zip=. Versioned with this CLI, so it always matches the reports this binary generates.

Synopsis:

trailblaze viewer [OPTIONS]

Options:

Option	Description	Default
`--output`, `-o`	Where to write the viewer. A path ending in .html is used as-is; anything else is treated as a directory and index.html is written inside it. Defaults to ./index.html.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze profile`¶

Generate a performance-analysis report (tools, LLM calls, timeouts, idle gaps) for a logs directory. An Instruments-style time profiler over each session. Defaults to the configured logs directory when is omitted. Writes /trailblaze_performance_analysis.html. Requires bun on PATH.

Synopsis:

trailblaze profile [OPTIONS] [<<logs-dir>>]

Arguments:

Argument	Description	Required
`<<logs-dir>>`	Logs directory to profile (the directory holding per-session subdirectories). Defaults to the configured logs directory.	No

Options:

Option	Description	Default
`--open`	Open the report in the default browser after generation.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze otel`¶

Convert recorded spans to OpenTelemetry (OTLP/JSON files, optionally posted to an endpoint). Writes /otel.json for every session that recorded a trace, and with –post also sends them to an OTLP endpoint. Defaults to the configured logs directory when

is omitted.

Synopsis:

trailblaze otel [OPTIONS] [<<dir>>]

Arguments:

Argument	Description	Required
`<<dir>>`	A logs directory (holding per-session subdirectories) or a single session directory. Defaults to the configured logs directory.	No

Options:

Option	Description	Default
`--post`	Also send the spans to an OTLP endpoint. Uses –endpoint if given, otherwise OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_ENDPOINT, falling back to http://localhost:4318.	-
`--endpoint`	OTLP endpoint to send to. Implies –post. Port 4317 is treated as gRPC, anything else as OTLP/HTTP.	-
`--service-name`	Service name recorded in the exported resource. Defaults to `trailblaze`.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint`¶

Match named app locations (waypoints) against captured screen state.

Synopsis:

trailblaze waypoint [OPTIONS]
trailblaze waypoint list
trailblaze waypoint locate
trailblaze waypoint validate
trailblaze waypoint capture-example
trailblaze waypoint suggest-selector
trailblaze waypoint migrate-trail
trailblaze waypoint segment
trailblaze waypoint graph
trailblaze waypoint tune
trailblaze waypoint propose
trailblaze waypoint shortcut

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint list`¶

List all waypoint definitions from active trailmaps (workspace + framework classpath) and any additional *.waypoint.yaml files discovered under –root.

Synopsis:

trailblaze waypoint list [OPTIONS]

Options:

Option	Description	Default
`--target`	Trailmap id to operate on. Resolves –root to /trailmaps//waypoints/. Mutually exclusive with –root (–root wins if both given).	-
`--root`	Additional directory to scan for *.waypoint.yaml files. Overrides –target. Trailmap waypoints are always included regardless. (Convention: ./trails)	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint locate`¶

Given a captured screen state, report which waypoint(s) match.

Synopsis:

trailblaze waypoint locate [OPTIONS]

Options:

Option	Description	Default
`--session`	Session log directory. With –step, locates a single step; without –step, batch-locates every screen-state log in the dir and emits one TSV row per step.	-
`--step`	1-based index of the step within the session (single-step mode; selects from *_TrailblazeLlmRequestLog.json files)	-
`--file`	Direct path to a *_TrailblazeLlmRequestLog.json file (alternative to –session/–step)	-
`--target`	Trailmap id to operate on. Resolves –root to /trailmaps//waypoints/. Mutually exclusive with –root (–root wins if both given).	-
`--root`	Additional directory to scan for *.waypoint.yaml files. Overrides –target. Trailmap waypoints are always included regardless. (Convention: ./trails)	-
`--rel-base`	Batch mode only: emit log paths relative to this directory. Must be an existing directory. Default: relative to the session dir’s parent (yielding /).	-
`--log-suffix`	Batch mode only: restrict the walk to logs whose filename ends with this suffix (e.g. `_AgentDriverLog.json`). Default: every screen-state log type (`_AgentDriverLog.json`, `_TrailblazeSnapshotLog.json`, `_TrailblazeLlmRequestLog.json`). Use to pin row accounting against a specific log type when the session dir may carry multiple.	-
`--live`	Pull screen state from the connected device (not yet implemented)	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint validate`¶

Validate that a specific waypoint definition matches a captured screen state.

Synopsis:

trailblaze waypoint validate [OPTIONS] [<<positionalLogFile>>]

Arguments:

Argument	Description	Required
`<<positionalLogFile>>`	Path to a screen-state log — accepts _TrailblazeLlmRequestLog.json, _AgentDriverLog.json, _TrailblazeSnapshotLog.json, or a sibling .example.json. Optional: omit and use –session, or rely on the auto-resolved sibling example pair next to the matching *.waypoint.yaml.	No

Options:

Option	Description	Default
`--id`	Waypoint id to validate (matches the YAML’s top-level `id:` field). Required.	-
`--session`	Session id (the directory name under –logs-dir, e.g. `2026_05_07_22_26_48_yaml_6258`). Combine with –step to pin a specific step; without –step the last step is used.	-
`--step`	1-based index of the step within –session (default: last step). Requires –session.	-
`--target`	Trailmap id to operate on. Resolves –root to /trailmaps//waypoints/ — the canonical workspace-trailmap location. Warns if no such trailmap exists. Mutually exclusive with –root (–root wins if both given).	-
`--root`	Additional directory to scan for *.waypoint.yaml files. Overrides –target. Trailmap waypoints are always included regardless. (Convention: ./trails)	-
`--logs-dir`	Override the directory containing per-session log dirs. Defaults to the running daemon’s resolved logsDir.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint capture-example`¶

Capture a sibling .example.json + screenshot next to the waypoint YAML. With no –session/–step/positional-log, walks every session under logs/ and picks the most recent step that the waypoint matches AND that has a real screenshot.

Synopsis:

trailblaze waypoint capture-example [OPTIONS] [<<positionalLogFile>>]

Arguments:

Argument	Description	Required
`<<positionalLogFile>>`	Direct path to a screen-state log (alternative to auto-search / –session)	No

Options:

Option	Description	Default
`--id`	Waypoint id to capture an example for (matches the YAML’s top-level `id:` field). Required.	-
`--session`	Session id (the directory name under –logs-dir, e.g. `2026_05_07_22_26_48_yaml_6258`). Restricts the auto-search to that session. Combine with –step to pin a specific step.	-
`--step`	1-based step within –session. Skips auto-search; uses this step verbatim. Requires –session.	-
`--target`	Trailmap id to operate on. Resolves –root to /trailmaps//waypoints/ — the canonical workspace-trailmap location. Warns if no such trailmap exists. Mutually exclusive with –root (–root wins if both given). Also supplies the trailmap’s declared `app_ids:` to expand `{{target.appId}}` placeholders during matching; exits with a usage error if the named trailmap can’t be resolved or declares no `app_ids:`.	-
`--root`	Explicit root directory to scan for *.waypoint.yaml files. Overrides –target. (Convention: ./trails)	-
`--logs-dir`	Override the directory containing per-session log dirs. Defaults to the running daemon’s resolved logsDir.	-
`--force`	Overwrite an existing example pair without prompting.	-
`--device-classifier`	Device classifier (e.g. android-phone, android-tablet, ios-iphone, ios-ipad) to label this example, so one waypoint can keep a per-form-factor example SET. Written into the filename (`<base>.example.<classifier>.json` + screenshot) and the example’s `deviceClassifier` field. Selectors stay per-platform (one waypoint file) — only the snapshot is classifier-keyed, since a phone and tablet share accessibility identity but render differently. If omitted, falls back to the source log’s classifier if it records one, else writes the unlabeled default example (`<base>.example.json`).	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint suggest-selector`¶

Suggest selector YAML for a specific element ref in a captured screen — the whole menu. Pair with ./trailblaze snapshot --all to see refs, then run this on the matching session log to translate ref → selector. Prints EVERY strategy that computes a selector resolving to the target (resource id, text, structural, childOf, containsChild, spatial, index-qualified variants, plus a run-variable-wildcarded text variant), each with its strategy name + live match count, ranked most-stable first. Nothing computable is hidden.

Synopsis:

trailblaze waypoint suggest-selector [OPTIONS] [<<positionalLogFile>>]

Arguments:

Argument	Description	Required
`<<positionalLogFile>>`	Path to a *_TrailblazeLlmRequestLog.json (required unless –session/–step given). Same shape as the input to `waypoint validate`.	No

Options:

Option	Description	Default
`--ref`	Element ref from the captured tree (e.g. ‘a812’). Mutually exclusive with –at; exactly one must be provided.	-
`--at`	Screen-coordinate pair `x,y` (in device pixels) identifying the target element. The frontmost interactive node whose bounds contain the point is selected via the same hit-test the runtime uses for taps. Useful for the deterministic Maestro-selector → accessibility-selector migration: resolve the Maestro selector to a center coordinate, then ask this command for an accessibility selector that covers the same node. Mutually exclusive with –ref / –maestro-selector.	-
`--maestro-selector`	Inline TrailblazeElementSelector YAML (the legacy flat selector with fields like `textRegex`, `idRegex`, `accessibilityTextRegex`, `index`, `enabled`, etc.) — the shape used by the older Maestro-driver tap recordings. The selector is resolved against the captured `viewHierarchy` (Maestro tree) using the same matcher the runtime taps use; the resulting node’s CENTER coordinate is then hit-tested against the captured `trailblazeNodeTree` (accessibility tree) to find the accessibility node that covers the same on-screen element. The output is the same selector cascade as `--ref` / `--at`, but starting from a Maestro selector. This is the deterministic Maestro→accessibility migration primitive. Mutually exclusive with –ref / –at.	-
`--session`	Session log directory (containing *_TrailblazeLlmRequestLog.json files)	-
`--step`	1-based step within –session (default: last step)	-
`--max`	Maximum candidate selectors to print (default: 25 — enough to show them all)	-
`--anchor`	Compose the leaf selector with an ancestor predicate. Currently supported: parent-selected — find the nearest ancestor with isSelected=true and emit a selector that matches that ancestor as a `View` with `isSelected: true`, using the leaf as `containsChild`. This is the canonical bottom-nav-tab waypoint pattern: any app with selectable bottom-nav tabs uses this to pin identity to the currently active tab rather than to any tab with the given label. Without the anchor, the leaf selector matches a tab regardless of selection state — fine for tap targets, wrong for waypoint identity, because we want to know WHICH tab is currently active.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint migrate-trail`¶

Mechanically migrate a trail’s Maestro-shape selectors to accessibility shape. Every tapOnElementBySelector / assertVisibleBySelector whose nodeSelector still carries androidMaestro matchers is rewritten to androidAccessibility shape, using the captured session logs to deterministically resolve each selector through the same matcher the runtime uses for taps. Defaults to dry-run (unified diff on stdout). Use --write to apply the migration in place. Pair with a recorded session log directory (--session) for the same trail.

Synopsis:

trailblaze waypoint migrate-trail [OPTIONS] <<trailFile>>

Arguments:

Argument	Description	Required
`<<trailFile>>`	Path to the trail YAML file to migrate.	Yes

Options:

Option	Description	Default
`--session`	Session log directory from a dual-tree recorded run of this trail (trailblaze.captureSecondaryTree=true). Accepts _TrailblazeLlmRequestLog.json, _TrailblazeSnapshotLog.json, and *_AgentDriverLog.json files; only logs carrying viewHierarchy + trailblazeNodeTree + driverMigrationTreeNode are usable.	-
`--write`	Overwrite the trail file in place with the migrated YAML. Default is dry-run: print a unified diff for review without changing the file.	-
`--classifier`	For a unified-format trail file only: which classifier’s recordings to migrate (e.g. `android-phone`, `ios-tablet`). A session is captured against one device at a time, so migrate-trail always operates on one classifier per invocation — unified format just changes where that classifier’s tool list lives (nested under this trail’s `recording:` map instead of its own file). If omitted, inferred from the session logs’ device classifier when exactly one available classifier matches; otherwise this is required. Ignored for legacy-format trail files.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint segment`¶

Inspect transitions between waypoints observed in a session log.

Synopsis:

trailblaze waypoint segment [OPTIONS]
trailblaze waypoint segment list

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint segment list`¶

List trail segments observed in a session log directory. A segment is a transition from one matched waypoint to another, with the tool calls that drove it.

Synopsis:

trailblaze waypoint segment list [OPTIONS]

Options:

Option	Description	Default
`--session`	Session log directory (containing *.json log files)	-
`--root`	Additional directory to scan for *.waypoint.yaml files (default: ./trails, resolved against the current working directory). Trailmap waypoints are always included regardless of –root.	-
`--target`	Trailmap id whose declared `app_ids:` expand `{{target.appId}}` placeholders in waypoint selectors during matching. Match `--target` on `waypoint locate/validate` if the session was captured against that target’s app.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint graph`¶

Render the waypoint navigation graph (waypoints, authored shortcuts, authored trailheads) as a single self-contained HTML file. The output bakes in screenshots as data URIs and loads React Flow + dagre at runtime via esm.sh CDN — open it in any browser, share it via email/Slack/zip, no Trailblaze install required on the viewer’s side. For a live, refresh-on-edit view from the running daemon, point your browser at http://localhost:<daemon-port>/waypoints/graph instead.

Synopsis:

trailblaze waypoint graph [OPTIONS]

Options:

Option	Description	Default
`--target`	Trailmap id to scope the graph to (e.g. `myapp`, `clock`). Filters the rendered graph to waypoints whose id starts with `<id>/` and drops shortcuts/trailheads that cross out of that scope. Also resolves –root to /trailmaps//waypoints/ when no explicit –root is given.	-
`--platform`	Platform to scope the graph to (`android`, `ios`, or `web`). Filters waypoints whose source path is under `waypoints/<platform>/...` and drops shortcuts/trailheads that cross out of that scope. Combine with –target to produce a single (target, platform) map.	-
`--root`	Filesystem directory to scan for *.waypoint.yaml files (default: ./trails, resolved against the current working directory). Overrides –target’s root resolution. Trailmap-bundled waypoints from the classpath are always included regardless of this flag.	-
`--out`, `-o`	Output HTML file path (default: ./.trailblaze/reports/waypoint-graph.html, relative to the current directory). The default scopes the artifact to .trailblaze/reports/ — a stack-agnostic, generated-output-only subpath that consumers can gitignore without having to blanket-ignore the rest of .trailblaze/ (which may hold things they want to commit). Parent directories are created if missing; the file is overwritten if present.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint tune`¶

Analyze a session set for near-miss patterns and propose YAML edits. Each surviving proposal lands as a JSON+YAML pair under –out-dir, ready for the pipeline’s auto-PR step to materialize as one PR per proposal.

Synopsis:

trailblaze waypoint tune [OPTIONS]

Options:

Option	Description	Default
`--sessions`	Directory containing one or more session subdirectories. Each subdirectory is treated as a session; *_AgentDriverLog.json (or any screen-state log) inside is treated as a step. Required.	-
`--target`	Trailmap id. Resolves –root to /trailmaps//waypoints/. Also supplies the trailmap’s app_ids for templated selector expansion.	-
`--root`	Directory containing *.waypoint.yaml files to consider for tuning. Overrides –target. (Convention: ./trails)	-
`--min-support`	Minimum number of supporting sessions for a proposal to fire. Default: 5.	-
`--out-dir`	Output directory for proposal sidecars. Default: ./.waypoints_tune/proposals/. Wiped at the start of each run.	-
`--idempotence-check`	After the first pass, re-run the analyzer on the same session set with the proposals applied in-memory and fail if the second pass emits any proposal.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint propose`¶

Synthesize draft waypoint YAMLs from unmatched-cluster fingerprints. Emits one proposal sidecar per surviving cluster to –out-dir; the trailblaze-waypoints-propose pipeline picks them up and opens one PR per proposal.

Synopsis:

trailblaze waypoint propose [OPTIONS]

Options:

Option	Description	Default
`--cluster`	Single JSONL cluster line. Mutually exclusive with –aggregate.	-
`--aggregate`	Path to unmatched-clusters.jsonl. Pipeline mode. Mutually exclusive with –cluster.	-
`--sessions`	Directory containing the session logs used by the source build. Each cluster’s `example_log` path is resolved relative to this dir, and the cross-waypoint bleed guard walks the full session set.	-
`--target`	Trailmap id. Resolves –root + provides the proposal namespace (`<target>/auto-<slug>`).	-
`--root`	Override the waypoint-root dir for sibling-overlap checks. (Convention: ./trails)	-
`--top-n`	Maximum number of clusters to process in –aggregate mode (default: 10).	-
`--out-dir`	Output directory for proposal sidecars. Default: ./.waypoints_propose/proposals/. Wiped at the start of each run.	-
`--idempotence-check`	Re-run after applying the proposals in-memory; fail (exit 1) if the second pass emits any new proposal.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint shortcut`¶

Analyze a session set for (A->B) waypoint transitions and synthesize draft shortcut YAMLs, then empirically replay each candidate on a fresh emulator before opening a PR. Subcommands: propose (offline), verify (on-device).

Synopsis:

trailblaze waypoint shortcut [OPTIONS]
trailblaze waypoint shortcut propose
trailblaze waypoint shortcut verify

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint shortcut propose`¶

Analyze a session set for (A->B) transitions and emit draft shortcut YAMLs. Each surviving proposal lands as a JSON+YAML pair under –out-dir, ready for the pipeline’s verify + auto-PR steps.

Synopsis:

trailblaze waypoint shortcut propose [OPTIONS]

Options:

Option	Description	Default
`--sessions`	Directory containing one or more session subdirectories with *_AgentDriverLog.json files. Each subdirectory is one session.	-
`--target`	Trailmap id. Resolves –root to /trailmaps//waypoints/ and supplies the trailmap’s app_ids for templated selector expansion.	-
`--root`	Override the waypoint-root dir for waypoint + existing-shortcut discovery. (Convention: ./trails)	-
`--min-support`	Minimum distinct sessions for a transition to be proposed. Default: 3.	-
`--fingerprint-agreement`	Fraction of supporting sessions that must share the dominant action fingerprint (default: 0.67). Sessions disagreeing on the procedure short-circuit the proposal.	-
`--top-k`	Process at most the top-K surviving proposals by hit count. The replay step is expensive enough that v1 caps weekly throughput here. Default: 5.	-
`--out-dir`	Output directory for proposal sidecars. Default: ./.waypoints_shortcut/proposals/. Wiped at the start of each run.	-
`--idempotence-check`	Re-run after applying the surviving proposals in-memory; fail (exit 1) if any new proposal surfaces.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint shortcut verify`¶

Empirical replay of a proposed shortcut against a connected emulator. Generates a throwaway trail YAML and runs it via trailblaze run. Returns 0 if the post-condition waypoint matches, non-zero otherwise.

Synopsis:

trailblaze waypoint shortcut verify [OPTIONS]

Options:

Option	Description	Default
`--yaml`	Path to the shortcut YAML to verify (a `*.shortcut.yaml`).	-
`--device`	Device id to run against (forwarded to `trailblaze run --device`). Defaults to $TRAILBLAZE_DEVICE.	-
`--driver`	Driver to use in the generated trail config. Default: ANDROID_ONDEVICE_ACCESSIBILITY. Pick a different value when verifying an iOS shortcut (v1 ships Android-first).	-
`--max-attempts`	Total attempts before declaring failure. Default: 1 (no retries). Trail-runtime exit codes are not distinguishable today between infrastructure and test-side failures (picocli SOFTWARE=1 covers both driver-init failures and post-condition mismatches), so v1 defaults to no retries. Override to 2+ only when investigating known transient infra flake; a flaky shortcut is a bad shortcut and the default policy reflects that.	-
`--trail-out`	Write the generated trail YAML to for debugging. Default: ./.waypoints_shortcut/verify/.trail.yaml	-
`--trailblaze-bin`	Override the `trailblaze` binary used for the inner trail run. Default: ./trailblaze (so framework changes are picked up). CI sets this to the installed-distribution binary to mirror the end-user code path.	-
`--timeout-seconds`	Per-attempt timeout in seconds for the inner `trailblaze run` subprocess. Default: 600 (10 min). A wedged trail run (device disconnect, ADB hung, runtime stuck on settle) is destroyed and returns exit code 124 so the outer bootstrap can move on. Without a timeout, a single stuck replay would block the rest of v1’s sequential top-K loop indefinitely.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze results`¶

Query the persisted test-result index for a test case. Passing a positional <case-id> (e.g. trailblaze results C12345 --device android-phone) is equivalent to the explicit trailblaze results show <case-id> form — picocli routes the bare case-id straight to the show subcommand.

Synopsis:

trailblaze results [OPTIONS] [<<case-id>>]
trailblaze results show

Arguments:

Argument	Description	Required
`<<case-id>>`	Test-case ID. When supplied without a subcommand, this routes to `show <case-id>`. Case-insensitive; the leading `C` is required (e.g. C12345).	No

Options:

Option	Description	Default
`--device`	Forwarded to `show --device`. See `trailblaze results show --help` for the full flag set.	-
`--all-devices`	Forwarded to `show --all-devices`.	-
`--latest`	Forwarded to `show --latest`.	-
`--json`	Forwarded to `show --json`.	-
`--repo`	Forwarded to `show --repo`.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze results show`¶

Show the recorded result for a test case ID

Synopsis:

trailblaze results show [OPTIONS] <<case-id>>

Arguments:

Argument	Description	Required
`<<case-id>>`	Test-case ID, e.g. C12345. Case-insensitive; the leading `C` is required.	Yes

Options:

Option	Description	Default
`--device`	Device profile to look up (e.g. android-phone, android-tablet, ios-iphone, ios-ipad, web). Required unless –all-devices is passed. The same case runs on multiple devices and produces materially different results per device, so this command refuses to guess.	-
`--all-devices`	Print a one-line summary for every device profile that has a recorded result for this case. Enumerates the case directory in the index repo. Mutually exclusive with –device / –latest / –json (single-device flags). Exit code: 0 iff every listed device’s latest run is a pass AND a recorded success file is present; 1 if any device is currently failing OR its latest state could not be determined (e.g. ‘data unavailable’ shown when the cell’s latest.json couldn’t be read — check stderr for the underlying HTTP error). Usable as a CI gate, e.g. `results show C12345 --all-devices && deploy`.	-
`--latest`	Show the most recent terminal run instead of the most recent successful run. Reads latest.json instead of latest_success.json for the chosen device cell.	-
`--json`	Print the raw JSON document instead of a pretty summary.	-
`--repo`	owner/name of the results repo to query. Falls back to the TRAILBLAZE_RESULTS_REPO env var when not supplied. The OSS CLI ships with no default; distributions point at their own index repo via the launcher.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze config`¶

View and set configuration (target app, device defaults, AI provider)

Synopsis:

trailblaze config [OPTIONS] [<<key>>] [<<value>>]
trailblaze config show
trailblaze config target
trailblaze config models
trailblaze config reset

Arguments:

Argument	Description	Required
`<<key>>`	Config key to get or set	No
`<<value>>`	Value to set	No

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

Config Keys:

Key	Description	Valid Values
`llm`	LLM provider and model (shorthand: provider/model)	provider/model (e.g., openai/gpt-4-1, anthropic/claude-sonnet-4-20250514) or ‘none’ to disable
`llm-provider`	LLM provider	openai, anthropic, google, ollama, openrouter, etc. or ‘none’ to disable
`llm-model`	LLM model ID	e.g., gpt-4-1, claude-sonnet-4-20250514, gemini-3-flash or ‘none’ to disable
`target`	Target app for device connections and custom tools	App target ID. Run ‘trailblaze config target’ to see all.
`agent`	Agent implementation	TRAILBLAZE_RUNNER, MULTI_AGENT_V3, KOOG_STRATEGY_GRAPH
`android-driver`	Android driver type	accessibility, instrumentation, in-process
`ios-driver`	iOS driver type	host, axe
`self-heal`	Enable/disable self-heal (AI takes over) when recorded steps fail	true, false
`require-steps`	Require -s/–step on every tool / step / ask / verify call (default: false)	true, false
`max-llm-calls`	Per-objective LLM call cap for the TRAILBLAZE_RUNNER and KOOG_STRATEGY_GRAPH agents	positive integer, or ‘unset’ to clear
`annotated-screenshots`	Save set-of-mark annotated screenshots to logs (LLM always receives annotated)	true, false
`mode`	CLI working mode: trail (author reproducible trails) or blaze (explore device)	trail, blaze
`web-headless`	Default for `--headless` on web devices (CLI flag still wins when explicitly passed)	true, false
`device`	Default device platform for CLI commands	android, ios, web
`screenshot-format`	Image format used for screenshots sent to the LLM and shown in the timeline	png, jpeg, webp, or ‘unset’ to use the framework default (webp)
`screenshot-max-dimensions`	Max screenshot dimensions as x (e.g. 1536x768, 2048x1024)	WIDTHxHEIGHT (positive ints), or ‘unset’ to use the framework default (1536x768)
`screenshot-quality`	Compression quality 0.05..1.0 for lossy formats (jpeg, webp); ignored for png	0.05..1.0, or ‘unset’ to use the framework default (0.80)
`stream-screenshots`	Experimental: serve agent-loop screenshots from the live device stream on Android, iOS, and web (default: off)	true, false, or ‘unset’ to inherit the default (off)
`capture-video`	Record device screen video for each session (default: off — video is opt-in)	true or false
`ios-baguette-video`	Experimental: record iOS session video from the baguette H.264 stream instead of simctl (default: off)	true, false, or ‘unset’ to inherit the default (off)
`disable-animations`	Experimental: disable OS animations on the device during each session, restored at session end (default: off)	true, false, or ‘unset’ to inherit the default (off)
`turbo`	Experimental: let the Android app under test report when it is idle so the driver waits less (default: off)	true, false, or ‘unset’ to inherit the default (off)

Examples:

trailblaze config                                    # Show all settings
trailblaze config llm                                # Show current LLM provider/model
trailblaze config llm anthropic/claude-sonnet-5      # Set both provider + model
trailblaze config llm-provider openai                # Set provider only
trailblaze config llm-model gpt-5.6-terra            # Set model only
trailblaze config agent MULTI_AGENT_V3               # Set agent implementation
trailblaze config models                             # List available LLM models
trailblaze config agents                             # List agent implementations
trailblaze config drivers                            # List driver types

`trailblaze config show`¶

Show all settings and authentication status

Synopsis:

trailblaze config show [OPTIONS]

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze config target`¶

List or set the target app

Synopsis:

trailblaze config target [OPTIONS] [<<targetId>>]

Arguments:

Argument	Description	Required
`<<targetId>>`	Target app ID to set	No

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze config models`¶

List available LLM models by provider

Synopsis:

trailblaze config models [OPTIONS]

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze config reset`¶

Reset all settings to defaults

Synopsis:

trailblaze config reset [OPTIONS]

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze device`¶

List and connect devices (Android, iOS, Web)

Synopsis:

trailblaze device [OPTIONS]
trailblaze device list
trailblaze device connect
trailblaze device rebind
trailblaze device disconnect
trailblaze device create

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze device list`¶

List available devices

Synopsis:

trailblaze device list [OPTIONS]

Options:

Option	Description	Default
`--all`	Include hidden platforms (e.g. the Compose desktop driver — `desktop/self`).	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze device connect`¶

Connect a device + target and pin them for this terminal so subsequent commands inherit the binding

Synopsis:

trailblaze device connect [OPTIONS] <<platform>>

Arguments:

Argument	Description	Required
`<<platform>>`	Device platform: ANDROID, IOS, or WEB (optionally with instance: android/emulator-5554)	Yes

Options:

Option	Description	Default
`--target`, `-t`	Target app to bind to this device’s session (e.g. `default`, `sampleapp`). Optional. When set, the target is recorded alongside the device in this terminal’s pin so subsequent CLI calls re-apply the binding automatically until you `device disconnect` or pin a different target.	-
`--mcp-session`	Explicit MCP session id to pin to this device (advanced). Default: pin the most-recently-active unbound MCP client (Claude Desktop, Cursor, Goose, …). No-op when no MCP clients are connected.	-
`--headless`	For –device web/…: launch the Playwright browser headless. When omitted, auto-detects: headless on machines with no display (remote workstations, CI), headed otherwise. Falls back to the persisted `web-headless` config when a display is present (see `trailblaze config web-headless`). Pass –headless=false to force a visible browser, –headless=true to force headless. Ignored for non-web devices.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze device rebind`¶

Change the target app for the currently-bound device

Synopsis:

trailblaze device rebind [OPTIONS]

Options:

Option	Description	Default
`-d`, `--device`	Device to rebind. Defaults to `$TRAILBLAZE_DEVICE` if set manually, otherwise this terminal’s pin (set by `trailblaze device connect`).	-
`--target`, `-t`	New target app for the bound device (e.g. `default`, `sampleapp`).	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze device disconnect`¶

Disconnect a device and clear this terminal’s pin

Synopsis:

trailblaze device disconnect [OPTIONS]

Options:

Option	Description	Default
`-d`, `--device`	Device to disconnect. Defaults to `$TRAILBLAZE_DEVICE` if set manually, otherwise this terminal’s pin (set by `trailblaze device connect`).	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze device create`¶

Provision a device with a configured profile (web today; iOS / Android future).

Synopsis:

trailblaze device create [OPTIONS]
trailblaze device create web

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze device create web`¶

Provision a Playwright web browser slot with a viewport / emulation profile. Does NOT launch a browser — the spec is stored on the slot and applied at the next browser launch. Examples: trailblaze device create web –instance-id mobile-iphone –emulate “iPhone 15” trailblaze device create web –instance-id desktop-large –viewport 1920x1080 trailblaze device create web –emulate “Pixel 7”

Synopsis:

trailblaze device create web [OPTIONS]

Options:

Option	Description	Default
`--instance-id`	Slot name. Subsequent commands address this slot as `--device web/<id>`. Defaults to the singleton `playwright-native` when omitted (the same slot the desktop app’s Launch Browser button operates on).	-
`--emulate`	Playwright `devices` preset name. Applies full device emulation: viewport, deviceScaleFactor, userAgent, isMobile, hasTouch. Examples: ‘iPhone 14’, ‘Pixel 7’, ‘iPad Pro 11’. Mutually exclusive with –viewport.	-
`--viewport`	Raw viewport size, e.g. ‘375x812’ or ‘1920x1080’. Sets ONLY the viewport box — does not change User-Agent, deviceScaleFactor, isMobile, or hasTouch, so pages that UA-sniff still serve their desktop variant. Use –emulate for a full mobile/tablet emulation profile. Mutually exclusive with –emulate.	-
`--headless`	Launch the browser headless (–headless) or headed (–no-headless). When omitted, defers to the slot’s stored preference, falling back to the headed-when-display-available default — so running this on a desktop without –headless does NOT force a hidden window.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze show`¶

Open the multi-device live grid (/devices/all) in your default browser

Synopsis:

trailblaze show [OPTIONS]

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze app`¶

Launch the legacy Trailblaze desktop app (use –v2 for Trail Runner or –headless for a daemon-only background service). trailblaze app start is an accepted synonym for this command.

Synopsis:

trailblaze app [OPTIONS]

Options:

Option	Description	Default
`--headless`	Start in headless mode (daemon only, no GUI)	-
`--stop`	Stop the running daemon	-
`--status`	Check if the daemon is running	-
`--foreground`	Run in foreground (blocks terminal). Use for debugging with an attached IDE.	-
`--v2`	Open Trail Runner in its native desktop window	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze mcp`¶

Start a Model Context Protocol (MCP) server for AI agent integration Exposes Trailblaze tools via the Model Context Protocol (MCP) so that AI coding agents can control devices. Quick setup: Claude Code: claude mcp add trailblaze – trailblaze mcp Cursor: Add to .cursor/mcp.json with command ‘trailblaze mcp’ Windsurf: Add to MCP config with command ‘trailblaze mcp’

Synopsis:

trailblaze mcp [OPTIONS]

Options:

Option	Description	Default
`--http`	Use Streamable HTTP transport instead of STDIO. Starts a standalone HTTP MCP server.	-
`--direct`, `--no-daemon`	Run as an in-process MCP server over STDIO instead of the default proxy mode. Runs everything in a single process instead of proxying to a separate daemon process. This is not a way around the HTTP port: the process still starts the daemon’s HTTP server itself when none is running.	-
`-d`, `--device`	Pin this MCP session to a device on startup (e.g. android, android/emulator-5554). Defaults to whatever the launching terminal pinned via `trailblaze device connect`, or `$TRAILBLAZE_DEVICE` if set.	-
`-t`, `--target`	Pin this MCP session to a target app on startup (e.g. default, sampleapp). Only meaningful with –device or $TRAILBLAZE_DEVICE. Defaults to $TRAILBLAZE_TARGET.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze check`¶

Validate a trailmap: materialize manifests, type-check its TypeScript, run its *.test.ts tests. Type-checking covers TypeScript/JavaScript sources; tests run via bun test. On first run, scaffolds a minimal package.json at the workspace root if absent so bun install can be used as the canonical bootstrap (its postinstall hook re-runs trailblaze check).

Synopsis:

trailblaze check [OPTIONS] [<<trailmap-id>>]

Arguments:

Argument	Description	Required
`<<trailmap-id>>`	Name of the trailmap to scope the type-check to (directory name under the workspace’s trailblaze-config/trailmaps/ or legacy trails/config/trailmaps/). Omit when running from inside a trailmap tree (auto-detected) or pass –all to type-check every trailmap. Mutually exclusive with –all.	No

Options:

Option	Description	Default
`--all`	Type-check every trailmap in the discovered workspace, even when running from inside a specific trailmap tree. Mutually exclusive with the positional .	-
`--workspace`	Pin the workspace root explicitly (the directory containing `trailblaze-config/trailmaps/` or the legacy `trails/config/trailmaps/`). Used by CI scripts that run with a fixed cwd; interactive users should rely on the cwd walk-up instead.	-
`--no-typecheck`	Skip the bundled-tsc typecheck pass — materialize the workspace’s SDK + per-trailmap typed bindings and still run `*.test.ts` unit tests via bun. Intended for CI scripts that run tsc with custom settings (e.g., excluding legacy embedded sub-projects); interactive users should leave this off.	-
`--show-typed-tools`	Print the typed scripted tools (`trailblaze.tool<I, O>({...})`) discovered in each trailmap, with a compact one-line schema summary per tool. Useful as a diagnostic when authoring a new tool or chasing a missing-tool / wrong-schema bug; off by default because the per-trailmap subprocess spawn it requires adds noticeable latency to `check`. Has no effect when node, the SDK shim, or the SDK’s `ts-json-schema-generator` install are missing — the analyzer skips cleanly with an explanatory log line.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze inprocess`¶

Check an app APK for in-process driver compatibility, and build a test APK that drives it.

Synopsis:

trailblaze inprocess [OPTIONS]
trailblaze inprocess probe-apk
trailblaze inprocess make-test-apk

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze inprocess probe-apk`¶

Fingerprint an app APK and say whether the in-process driver can attach to it. Reads the APK only — no device, no Android SDK, no signing key. Emits a few KB of YAML: the package, whether a launcher activity exists, every declared ContentProvider, the era of each library that would collide in the shared classloader, the signing certificate digest, and android:debuggable. Pass –shell to compare against the exact test APK the app will be paired with. Without it the dex intersection cannot run, and the verdict is capped at INCOMPLETE — never GO.

Synopsis:

trailblaze inprocess probe-apk [OPTIONS] <<app apk>>

Arguments:

Argument	Description	Required
`<<app apk>>`	The app APK to fingerprint.	Yes

Options:

Option	Description	Default
`--shell`	The processed shell (test) APK this app will be paired with. Adds the dex intersection — classes the shell contributes that the app also ships, which in one classloader is the duplicated-class crash. Required to reach a GO verdict, and it must be the exact APK about to be installed, not a same-shaped build.	-
`--declared-deps`	Library versions the app’s team states, for an APK that packages no META-INF version files and whose era dex markers cannot pin. Format: `libraries:` with `library:` / `version:` entries.	-
`--shell-floor`	Replaces the built-in floor for libraries the shell does not package (so the shell’s own bytes cannot state one). Format: `libraries:` with `library:` / `minVersion:` / `why:` entries.	-
`--fail-on`	Exit non-zero only for these disqualifiers, instead of for any of them. The fingerprint and the printed verdict are unchanged — every reason is still named, and one that fired without being enforced is marked as such. Codes: ERA_BELOW_SHELL_FLOOR, DEX_OVERLAP_WITH_SHELL, NO_LAUNCHER_ACTIVITY, LAUNCHER_IN_OTHER_PROCESS, ERA_UNDETERMINABLE, DEX_OVERLAP_UNCHECKED	-
`--out`	Write the fingerprint here instead of stdout.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze inprocess make-test-apk`¶

Retarget a prebuilt in-process shell APK at one app and sign it with that app’s key. Stamps the instrumentation’s target package, injects trails / target config / scripted-tool bundles, then signs. Writes a build record beside the output APK. KNOWN LIMITATION: an app that uses androidx.startup cannot be attached to by a generic shell yet. AppInitializer is a process-wide singleton and the shell’s duplicate copy latches first, so the app’s own initializers never run and the process crashes before the first session starts. Given –app-apk, this command warns when the app’s manifest declares that provider, and produces the APK anyway - the packaging is fine, the run is not. On the –fingerprint path it cannot warn at all: a fingerprint states the signing facts, not the manifest’s components, so no warning there is not evidence of no androidx.startup. Until the shell stops packaging the duplicate runtime, use the Gradle in-process module for such an app - naming the app as targetProjectPath makes AGP dedupe startup-runtime out of the test APK.

Synopsis:

trailblaze inprocess make-test-apk [OPTIONS]

Options:

Option	Description	Default
`--shell`	Prebuilt Trailblaze in-process shell test APK. Required, and no release publishes one yet: build it from a framework checkout with scripts/build-inprocess-shell.sh and hand the APK to whoever runs this command.	-
`--target-package`	The app’s applicationId — the package the instrumentation is stamped to attach to. Must match the target evidence, so a wrong value is refused rather than signed.	-
`--out`, `-o`	Output APK. Defaults to -trailblaze-test.apk in the CWD.	-
`--keystore`	Keystore holding the app’s signing key (JKS or PKCS12).	-
`--alias`	Key alias inside –keystore.	-
`--app-apk`	The app’s APK, read for its certificate digest and debuggable flag. One of –app-apk or –fingerprint is required — signing blind is refused.	-
`--fingerprint`	A `package:`/`certificate_sha256:`/`debuggable:` description of the app, for a host the app’s APK never reaches. Carries the same two guard inputs –app-apk would be read for.	-
`--release`	Allow a non-debuggable target. Off by default because the usual cause of one is the wrong APK, not a deliberate release target. Signature equality is what actually gates attach, so a release build signed with the SAME key this command signs with is attachable and –release is the explicit override for it. A release build signed with a production key you do not hold stays unattachable no matter what you pass here.	-
`--allow-runtime-tool-source`	Bake `allow_runtime_tool_source: true` into the injected –target-config, letting this APK load scripted-tool bundles pushed to /data/local/tmp at run time instead of the ones packaged in it. Off by default, and written before signing either way, so the signature records the choice and a key-ceremony APK cannot be turned into one by omission.	-
`--target-config`	Target config to inject (`id:`, `display_name:`, `platforms:`, `tools:`). Without one the APK runs framework primitives only — no scripted tools.	-
`--trailmap`	Trailmap directory whose name is the trailmap id and which holds a tools/ subtree. Repeat for several. A tools/ of pre-built .bundle.js files needs no tooling; TypeScript sources are bundled here, which needs esbuild.	-
`--trail`	A *.trail.yaml to inject. Repeat for several. The shell discovers them at run time and reports one test per trail.	-
`--esbuild`	esbuild binary, when –trailmap carries TypeScript and esbuild is not on PATH.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze skill`¶

Print or install the bundled agent skill that teaches a coding agent this CLI

Synopsis:

trailblaze skill [OPTIONS]
trailblaze skill show
trailblaze skill install
trailblaze skill status

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze skill show`¶

Print a bundled skill file to stdout (defaults to SKILL.md)

Synopsis:

trailblaze skill show [OPTIONS] [<<file>>]

Arguments:

Argument	Description	Required
`<<file>>`	Bundled file to print, e.g. references/drive-device.md. Run `trailblaze skill` for the list.	No

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze skill install`¶

Write the bundled skill into an agent’s skill directory (defaults to Claude Code’s)

Synopsis:

trailblaze skill install [OPTIONS]

Options:

Option	Description	Default
`--agent`	Target agent: claude (.claude/skills) or agents (.agents/skills, shared by Codex, Cursor, Gemini CLI, Goose, …). codex/cursor/gemini/goose are aliases for agents. Defaults to claude.	-
`--all`	Install into both locations (.claude/skills and .agents/skills) in one go.	-
`--global`	Install under your home directory instead of the current project.	-
`--dir`	Explicit destination directory. Mutually exclusive with –agent/–all/–global.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze skill status`¶

Report installed skill copies and whether they match this CLI

Synopsis:

trailblaze skill status [OPTIONS]

Options:

Option	Description	Default
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze companion`¶

Attach a coding agent to Trail Runner while it authors a trail.

Synopsis:

trailblaze companion [OPTIONS]
trailblaze companion start
trailblaze companion event
trailblaze companion send
trailblaze companion listen
trailblaze companion disconnect
trailblaze companion respond
trailblaze companion agent-help

Options:

Option	Description	Default
`--agent-help`	Print the complete coding-agent workflow and wire contract.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze companion start`¶

Start a companion authoring session.

Synopsis:

trailblaze companion start [OPTIONS]

Options:

Option	Description	Default
`--folder`	Trail folder relative to the workspace root.	-
`--title`	Human-readable title shown in Trail Runner.	-
`--agent`	Agent type: claude or codex.	`claude`
`--label`	Agent label shown in Trail Runner.	-
`--trails-dir`	Workspace root (default: current directory).	`.`
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze companion event`¶

Append narration to a companion session.

Synopsis:

trailblaze companion event [OPTIONS] <<runId>>

Arguments:

Argument	Description	Required
`<<runId>>`	Companion run id.	Yes

Options:

Option	Description	Default
`--kind`	assistant_message, lifecycle, or error.	-
`--title`	Optional event heading.	-
`--text`	Event body.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze companion send`¶

Send or retract Trail Runner UI guidance.

Synopsis:

trailblaze companion send [OPTIONS] <<runId>> <<directive>>

Arguments:

Argument	Description	Required
`<<runId>>`	Companion run id.	Yes
`<<directive>>`	Directive name.	Yes

Options:

Option	Description	Default
`--text`		-
`--route`		-
`--variant`		-
`--platform`		-
`--app`		-
`--title`		-
`--item`	List item; repeat for multiple items.	-
`--payload`	Additional directive fields as a JSON object.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze companion listen`¶

Stream human and lifecycle events as JSON Lines.

Synopsis:

trailblaze companion listen [OPTIONS] <<runId>>

Arguments:

Argument	Description	Required
`<<runId>>`	Companion run id.	Yes

Options:

Option	Description	Default
`--after`	Resume after this event sequence number.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze companion disconnect`¶

End a companion session.

Synopsis:

trailblaze companion disconnect [OPTIONS] <<runId>>

Arguments:

Argument	Description	Required
`<<runId>>`	Companion run id.	Yes

Options:

Option	Description	Default
`--note`	Optional closing summary.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze companion respond`¶

Settle a request delegated by Trail Runner.

Synopsis:

trailblaze companion respond [OPTIONS] <<runId>>

Arguments:

Argument	Description	Required
`<<runId>>`	Companion run id.	Yes

Options:

Option	Description	Default
`--request`	Request id from the listen stream.	-
`--status`	done or error.	-
`--note`	Optional result note.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze companion agent-help`¶

Print the complete coding-agent workflow and wire contract.

Synopsis:

trailblaze companion agent-help

NOTE: THIS IS GENERATED DOCUMENTATION

Trailblaze CLI¶

Usage¶

Device Claims & Sessions¶

Two execution models¶

Device-claim conflicts (yield-unless-busy)¶

When a step scope leaks across commands¶

Global Options¶

Commands¶

trailblaze step¶

trailblaze ask¶

trailblaze verify¶

trailblaze snapshot¶

trailblaze tool¶

trailblaze toolbox¶

trailblaze run¶

trailblaze usages¶

trailblaze session¶

trailblaze session start¶

trailblaze session stop¶

trailblaze session save¶

trailblaze session recording¶

trailblaze session info¶

trailblaze session list¶

trailblaze session artifacts¶

trailblaze session delete¶

trailblaze session end¶

trailblaze report¶

trailblaze strings¶

trailblaze strings extract¶

trailblaze strings diff¶

trailblaze viewer¶

trailblaze profile¶

trailblaze otel¶

trailblaze waypoint¶

trailblaze waypoint list¶

trailblaze waypoint locate¶

trailblaze waypoint validate¶

trailblaze waypoint capture-example¶

trailblaze waypoint suggest-selector¶

trailblaze waypoint migrate-trail¶

trailblaze waypoint segment¶

trailblaze waypoint segment list¶

trailblaze waypoint graph¶

trailblaze waypoint tune¶

trailblaze waypoint propose¶

trailblaze waypoint shortcut¶

trailblaze waypoint shortcut propose¶

trailblaze waypoint shortcut verify¶

trailblaze results¶

trailblaze results show¶

trailblaze config¶

trailblaze config show¶

trailblaze config target¶

trailblaze config models¶

trailblaze config reset¶

trailblaze device¶

trailblaze device list¶

trailblaze device connect¶

trailblaze device rebind¶

trailblaze device disconnect¶

trailblaze device create¶

trailblaze device create web¶

trailblaze show¶

trailblaze app¶

trailblaze mcp¶

trailblaze check¶

trailblaze inprocess¶

trailblaze inprocess probe-apk¶

trailblaze inprocess make-test-apk¶

trailblaze skill¶

trailblaze skill show¶

trailblaze skill install¶

trailblaze skill status¶

trailblaze companion¶

trailblaze companion start¶

trailblaze companion event¶

trailblaze companion send¶

trailblaze companion listen¶

trailblaze companion disconnect¶

trailblaze companion respond¶

When a `step` scope leaks across commands¶

`trailblaze step`¶

`trailblaze ask`¶

`trailblaze verify`¶

`trailblaze snapshot`¶

`trailblaze tool`¶

`trailblaze toolbox`¶

`trailblaze run`¶

`trailblaze usages`¶

`trailblaze session`¶

`trailblaze session start`¶

`trailblaze session stop`¶

`trailblaze session save`¶

`trailblaze session recording`¶

`trailblaze session info`¶

`trailblaze session list`¶

`trailblaze session artifacts`¶

`trailblaze session delete`¶

`trailblaze session end`¶

`trailblaze report`¶

`trailblaze strings`¶

`trailblaze strings extract`¶

`trailblaze strings diff`¶

`trailblaze viewer`¶

`trailblaze profile`¶

`trailblaze otel`¶

`trailblaze waypoint`¶

`trailblaze waypoint list`¶

`trailblaze waypoint locate`¶

`trailblaze waypoint validate`¶

`trailblaze waypoint capture-example`¶

`trailblaze waypoint suggest-selector`¶

`trailblaze waypoint migrate-trail`¶

`trailblaze waypoint segment`¶

`trailblaze waypoint segment list`¶

`trailblaze waypoint graph`¶

`trailblaze waypoint tune`¶

`trailblaze waypoint propose`¶

`trailblaze waypoint shortcut`¶

`trailblaze waypoint shortcut propose`¶

`trailblaze waypoint shortcut verify`¶

`trailblaze results`¶

`trailblaze results show`¶

`trailblaze config`¶

`trailblaze config show`¶

`trailblaze config target`¶

`trailblaze config models`¶

`trailblaze config reset`¶

`trailblaze device`¶

`trailblaze device list`¶

`trailblaze device connect`¶

`trailblaze device rebind`¶

`trailblaze device disconnect`¶

`trailblaze device create`¶

`trailblaze device create web`¶

`trailblaze show`¶

`trailblaze app`¶

`trailblaze mcp`¶

`trailblaze check`¶

`trailblaze inprocess`¶

`trailblaze inprocess probe-apk`¶

`trailblaze inprocess make-test-apk`¶

`trailblaze skill`¶

`trailblaze skill show`¶

`trailblaze skill install`¶

`trailblaze skill status`¶

`trailblaze companion`¶

`trailblaze companion start`¶

`trailblaze companion event`¶

`trailblaze companion send`¶

`trailblaze companion listen`¶

`trailblaze companion disconnect`¶

`trailblaze companion respond`¶

`trailblaze companion agent-help`¶