CLI Usage Scenarios¶
Auto-generated from @Scenario test annotations. Each scenario has a passing test that verifies the behavior.
Configuration¶
Configure CLI settings¶
Read or write CLI configuration keys. Valid keys: llm, self-heal, agent, android-driver, ios-driver, mode, device, target. Values are validated before persisting.
CLI:
trailblaze config llm anthropic/claude-sonnet-4-6
trailblaze config self-heal true
trailblaze config agent MULTI_AGENT_V3
Verified by: CliCommandValidationTest.config executeConfig with unknown key returns USAGE
Specify a target app for the session¶
The –target flag selects which app configuration to use, enabling target-specific tools and launch behavior.
CLI:
trailblaze blaze --target myapp Tap login
Verified by: CliCommandValidationTest.picocli parses blaze target flag
Set or list the target app¶
The target subcommand sets the active app target when given an ID, or lists available targets when called without arguments.
CLI:
trailblaze config target myapp
trailblaze config target
Verified by: CliCommandValidationTest.picocli parses config target subcommand with ID
Direct Tool Execution¶
Execute tools directly with a natural language objective¶
Use trailblaze tool with --yaml for direct tool execution. The -o flag provides a natural language objective so the step is recorded with context for self-healing replays.
CLI:
trailblaze tool tap ref=p386 --device=android -o "Tap the Sign In button"
Verified by: CliCommandValidationTest.blaze without goal returns USAGE
Verify a UI assertion without executing actions¶
The –verify flag runs observation-only: the agent checks whether a condition holds on the current screen without tapping or typing.
CLI:
trailblaze blaze --verify Check the login button is visible
Verified by: CliCommandValidationTest.picocli parses blaze verify flag
MCP: Execute YAML tools directly via blaze¶
MCP clients pass YAML tool sequences to blaze(). Tools execute sequentially, bypassing the AI agent. The step is recorded with the NL objective for trail quality.
MCP:
blaze(objective="Sign in", tools="- tap: {x: 100, y: 200}\n- tap: {x: 300, y: 400}")
Verified by: StepToolSetDirectToolsTest.direct tools - happy path executes tools and returns success
Tool Discovery¶
Discover available tools for current target¶
Shows platform toolsets and target-specific tools. Use before constructing –yaml tool sequences.
CLI:
trailblaze toolbox
MCP:
toolbox()
Verified by: ToolDiscoveryToolSetTest.INDEX mode without target or platform shows platform toolsets and all other targets
Get detailed tool descriptors with parameters¶
Expands each tool with full parameter descriptors (name, type, description). Useful for constructing –yaml tool sequences with correct parameter names.
CLI:
trailblaze toolbox --detail
MCP:
toolbox(detail=true)
Verified by: ToolDiscoveryToolSetTest.INDEX mode with detail=true includes full tool descriptors
Look up a specific tool by name¶
Returns the full descriptor for a single tool, including which categories it belongs to.
CLI:
trailblaze toolbox --name tapOnPoint
MCP:
toolbox(name="tapOnPoint")
Verified by: ToolDiscoveryToolSetTest.NAME mode finds tool from available tools
Query tools for a specific target app¶
Returns target-specific info including supported platforms and custom tools registered for that app.
CLI:
trailblaze toolbox --target myapp
MCP:
toolbox(target="myapp")
Verified by: ToolDiscoveryToolSetTest.TARGET mode returns target info for valid target
Search tools by keyword¶
Searches tool names and descriptions for matching keywords. Results include full descriptors with source info.
CLI:
trailblaze toolbox --search launch
MCP:
toolbox(search="launch")
Verified by: ToolDiscoveryToolSetTest.SEARCH mode finds tools matching keyword in name
Trail Management¶
Save session as trail file¶
The –save flag writes the session to a trail file. Use –setup to mark leading steps as setup, or –no-setup to mark none. One of –setup or –no-setup is required with –save.
CLI:
trailblaze blaze --save trails/test.trail.yaml
trailblaze blaze --save trails/test.trail.yaml --setup 1-3
trailblaze blaze --save trails/test.trail.yaml --no-setup
Verified by: CliCommandValidationTest.blaze -- setup without save returns USAGE
MCP: Recorded steps include tool call details¶
When recording is active, each blaze() call records the objective, executed tools, and success/failure status for trail replay.
MCP:
blaze(objective="Tap the login button", tools="- tapOnPoint:\n x: 100\n y: 200")
Verified by: StepToolSetDirectToolsTest.direct tools - successful execution records step with correct type and tool calls
NOTE: THIS IS GENERATED DOCUMENTATION