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
`-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.
`session`	Manage the current device session — save it as a replayable trail, inspect steps, end it
`report`	Generate an HTML report for session recordings, plus a best-effort JSON summary, and optionally MP4/GIF/WebP exports for a single session. JSON-only failures log a warning and still exit 0 — HTML is the primary artifact and is what gates the exit code.
`waypoint`	Match named app locations (waypoints) against captured screen state.
`results`	Query the persisted test-result index for a TestRail 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.
`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 Trailblaze desktop app for viewing sessions and managing trails (use –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 TypeScript/JavaScript sources, and run `*.test.ts` unit tests 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`).

`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 one trail per containing directory (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 one trail per containing directory (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: 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.	-
`-a`, `--agent`	Agent: TRAILBLAZE_RUNNER, MULTI_AGENT_V3. Default: TRAILBLAZE_RUNNER	-
`--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).	-
`-v`, `--verbose`	Enable verbose output	-
`--driver`	Driver type to use (e.g., PLAYWRIGHT_NATIVE, ANDROID_ONDEVICE_INSTRUMENTATION). 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.	-
`--max-llm-calls`	Cap the number of LLM calls per objective for the legacy TRAILBLAZE_RUNNER agent. Useful on metered or expensive providers to cut off a stuck self-heal loop. Must be a positive integer. Default: 50 (the runner’s built-in cap). Not compatible with –agent MULTI_AGENT_V3.	-
`--no-report`	Skip HTML report generation after execution	-
`--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 no .trail.yaml exists yet next to the source — 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)	-
`--capture-video`	Record device screen video for the session (on by default, use –no-capture-video to disable)	-
`--capture-logcat`	Capture logcat output filtered to the app under test (local dev mode)	-
`--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.	-
`--capture-all`	Enable all capture streams: video, logcat, 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 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.	-
`--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)	-
`-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.	-
`-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 for session recordings, plus a best-effort JSON summary, and optionally MP4/GIF/WebP exports for a single session. JSON-only failures log a warning and still exit 0 — HTML is the primary artifact and is what gates the exit code.

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.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 timeline artifact (–gif / –video / –webp) at the given byte size. Accepts plain bytes (1024000) or human-readable suffixes (10MB, 5M, 1.5G). 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, the export fails with an actionable error — drop GIF for –webp or –video (both compress dramatically better), or shorten the recorded session (fewer trail steps, or split into multiple sessions). The flag is applied per artifact, so `--gif --webp --max-size=10MB` caps each one independently.	-
`-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.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze waypoint suggest-selector`¶

Suggest waypoint-ready selector YAML for a specific element ref in a captured screen. Pair with ./trailblaze snapshot --all to see refs, then run this on the matching session log to translate ref → selector. Returns up to –max named candidates (the TrailblazeNodeSelectorGenerator strategies that uniquely resolve to the target), plus one structural-only candidate at the bottom for forbidden-clause use.

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 return (default: 5)	-
`--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 legacy selector (Maestro-shape) → nodeSelector (accessibility shape) for every selector-bearing tool in a trail YAML, 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 containing *_TrailblazeLlmRequestLog.json files captured during a recorded run of this trail. The Nth selector-bearing tool in the YAML is paired with the Nth log step that carries both viewHierarchy and trailblazeNodeTree.	-
`--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.	-
`-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 TestRail 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>>`	TestRail 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 TestRail case ID

Synopsis:

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

Arguments:

Argument	Description	Required
`<<case-id>>`	TestRail 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
`android-driver`	Android driver type	accessibility, instrumentation
`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 legacy TRAILBLAZE_RUNNER agent	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)

Examples:

trailblaze config                                    # Show all settings
trailblaze config llm                                # Show current LLM provider/model
trailblaze config llm anthropic/claude-sonnet-4-6    # Set both provider + model
trailblaze config llm-provider openai                # Set provider only
trailblaze config llm-model gpt-4-1                  # 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 Trailblaze desktop app for viewing sessions and managing trails (use –headless for a daemon-only background service)

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.	-
`-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. Bypasses the Trailblaze daemon and runs everything in a single process. Use this for environments where the HTTP daemon cannot run.	-
`--tool-profile`	Tool profile: FULL or MINIMAL (only device/blaze/verify/ask/trail). Defaults to MINIMAL for STDIO, FULL for HTTP.	-
`-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 TypeScript/JavaScript sources, and run *.test.ts unit tests 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 /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 `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.	-

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 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 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¶

When a `step` scope leaks across commands¶

`trailblaze step`¶

`trailblaze ask`¶

`trailblaze verify`¶

`trailblaze snapshot`¶

`trailblaze tool`¶

`trailblaze toolbox`¶

`trailblaze run`¶

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