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 — blaze, blaze --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. blaze --save is the canonical reason — each blaze invocation records steps into a per-device scoped session that blaze --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 blaze workflow that keeps calling into its own scope never trips on this — only cross-session contention with a busy holder does.

When a `blaze` scope leaks across commands¶

blaze --device android "…" opens a blaze-android scoped MCP session that stays alive on the daemon after the CLI exits, holding the device claim until blaze --save (or another blaze --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 blaze 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
`blaze`	Drive a device with AI — describe what to do in plain English
`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
`trail`	Run a trail file (.trail.yaml) — execute a scripted test on a device.
`session`	Every blaze records a session — save it as a replayable trail
`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.
`config`	View and set configuration (target app, device defaults, AI provider)
`device`	List and connect devices (Android, iOS, Web)
`app`	Start or stop the Trailblaze daemon (background service that drives devices)
`mcp`	Start a Model Context Protocol (MCP) server for AI agent integration
`compile`	Compile pack manifests into resolved target YAMLs

`trailblaze blaze`¶

Drive a device with AI — describe what to do in plain English

Synopsis:

trailblaze blaze [OPTIONS] [<<objectiveWords>>]

Arguments:

Argument	Description	Required
`<<objectiveWords>>`	Objective or assertion (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 (e.g., android/emulator-5554). Required for interactive blaze/verify execution.	-
`--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. Scoped to the device as a daemon-process override (dies on daemon restart or device release). 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 blaze 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 (e.g., android/emulator-5554). Required.	-
`-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. Required.	-
`-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. Required.	-
`-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
`--objective`, `-o`	Natural language intent — 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.	-
`--yaml`	Raw YAML tool sequence (multiple tools in one call)	-
`-d`, `--device`	Device: platform (android, ios, web) or platform/id. Required.	-
`-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. Scoped to the device as a daemon-process override (dies on daemon restart or device release). 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`	Show tools for a specific target app	-
`--search`, `-s`	Substring search on tool name and description.	-
`-d`, `--device`	Target device (e.g. android, android/emulator-5554).	-
`--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 trail`¶

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 .trail.yaml / blaze.yaml under them. 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.

Synopsis:

trailblaze trail [OPTIONS] [<<trailFile>>]

Arguments:

Argument	Description	Required
`<<trailFile>>`	Trail files (.trail.yaml or blaze.yaml), shell globs, or directories. Directories expand recursively to every contained trail file. If omitted, defaults to the `trails/` directory at the workspace root (resolved by walking up from the current 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), platform/instance-id, or instance ID	-
`-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)	-
`--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)	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze session`¶

Every blaze records a session — save it as a replayable trail

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. Scoped to the device as a daemon-process override (dies on daemon restart or device release). 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 to bind the session to: platform (android, ios, web) or platform/id (e.g., ios/DEVICE-UUID). Required — the CLI doesn’t durably track an “active” session across single-shot MCP calls, so every device-acting command takes the device explicitly. Examples: –device android, –device ios/DEVICE-UUID, –device web.	-
`--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 whose session to stop: platform (android, ios, web) or platform/id. The CLI is single-shot over MCP and doesn’t durably track an “active” session across calls, so –device is the lookup key — there’s one session per device, and stop refuses to act if the daemon’s currently-bound device doesn’t match. Examples: –device android, –device android/emulator-5554, –device ios/UUID.	-
`--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]

Options:

Option	Description	Default
`--id`	Session ID (defaults to current session, supports prefix matching)	-
`-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]

Options:

Option	Description	Default
`--id`	Session ID (defaults to current session)	-
`-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]

Options:

Option	Description	Default
`--id`	Session ID (defaults to current session)	-
`-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]

Options:

Option	Description	Default
`--id`	Session ID to delete (supports prefix matching)	-
`-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 whose session to end: platform (android, ios, web) or platform/id. Same lookup-key semantics as `session stop` — the CLI doesn’t trust a daemon-side “active” session across single-shot calls, so –device tells us which session you mean and end refuses to act if the daemon’s bound device doesn’t match.	-
`--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]

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

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 packs (workspace + framework classpath) and any additional *.waypoint.yaml files discovered under –root.

Synopsis:

trailblaze waypoint list [OPTIONS]

Options:

Option	Description	Default
`--target`	Pack id to operate on. Resolves –root to /packs//waypoints/. Mutually exclusive with –root (–root wins if both given).	-
`--root`	Additional directory to scan for *.waypoint.yaml files. Overrides –target. Pack 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`	Pack id to operate on. Resolves –root to /packs//waypoints/. Mutually exclusive with –root (–root wins if both given).	-
`--root`	Additional directory to scan for *.waypoint.yaml files. Overrides –target. Pack 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`	Pack id to operate on. Resolves –root to /packs//waypoints/ — the canonical workspace-pack location. Warns if no such pack exists. Mutually exclusive with –root (–root wins if both given).	-
`--root`	Additional directory to scan for *.waypoint.yaml files. Overrides –target. Pack 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`	Pack id to operate on. Resolves –root to /packs//waypoints/ — the canonical workspace-pack location. Warns if no such pack exists. Mutually exclusive with –root (–root wins if both given). Also supplies the pack’s declared `app_ids:` to expand `{{target.appId}}` placeholders during matching; exits with a usage error if the named pack 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). Pack waypoints are always included regardless of –root.	-
`--target`	Pack 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:/waypoints/graph instead.

Synopsis:

trailblaze waypoint graph [OPTIONS]

Options:

Option	Description	Default
`--target`	Pack 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 /packs//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. Pack-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`	Pack id. Resolves –root to /packs//waypoints/. Also supplies the pack’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`	Pack 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 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
`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

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

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 to your session (ANDROID, IOS, or WEB)

Synopsis:

trailblaze device connect [OPTIONS] <<platform>>

Arguments:

Argument	Description	Required
`<<platform>>`	Device platform: ANDROID, IOS, or WEB	Yes

Options:

Option	Description	Default
`--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 app`¶

Start or stop the Trailblaze daemon (background service that drives devices)

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.	-
`-h`, `--help`	Show this help message and exit.	-
`-V`, `--version`	Print version information and exit.	-

`trailblaze compile`¶

Compile pack manifests into resolved target YAMLs

Synopsis:

trailblaze compile [OPTIONS]

Options:

Option	Description	Default
`--input`, `-i`	Directory containing one /pack.yaml per pack. Defaults to /trails/config (workspace root is found by walking up from the current directory looking for `trails/config/`).	-
`--output`, `-o`	Directory to emit resolved .yaml files into. Defaults to /trails/config/dist/targets.	-
`-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 blaze scope leaks across commands¶

Global Options¶

Commands¶

trailblaze blaze¶

trailblaze ask¶

trailblaze verify¶

trailblaze snapshot¶

trailblaze tool¶

trailblaze toolbox¶

trailblaze trail¶

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

trailblaze config show¶

trailblaze config target¶

trailblaze config models¶

trailblaze config reset¶

trailblaze device¶

trailblaze device list¶

trailblaze device connect¶

trailblaze app¶

trailblaze mcp¶

trailblaze compile¶

When a `blaze` scope leaks across commands¶

`trailblaze blaze`¶

`trailblaze ask`¶

`trailblaze verify`¶

`trailblaze snapshot`¶

`trailblaze tool`¶

`trailblaze toolbox`¶

`trailblaze trail`¶

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

`trailblaze config show`¶

`trailblaze config target`¶

`trailblaze config models`¶

`trailblaze config reset`¶

`trailblaze device`¶

`trailblaze device list`¶

`trailblaze device connect`¶

`trailblaze app`¶

`trailblaze mcp`¶

`trailblaze compile`¶