Agent Workflow with the bellatrix CLI

Every step is a separate bellatrix process that re-attaches to the session by name. A desktop example:

bellatrix desktop list-apps --json
bellatrix desktop start-session --app calculator --session s1 --json
bellatrix desktop snapshot --session s1 --json
#   -> {"path":".bellatrix/snapshots/....json","elementCount":47,"summary":{...}}
bellatrix desktop find --session s1 --snapshot <path> --name "Equals" --json
bellatrix desktop click --session s1 --locator "//Button[@Name='Equals']" --json
bellatrix desktop get-text --session s1 --locator "//*[@AutomationId='CalculatorResults']" --json
bellatrix desktop close-session --session s1 --json

Once the steps work against the live app, the agent's generator writes the page object (actions, map, assertions) and the test with the validated locators.

A full UI tree can be thousands of nodes. The scaffolded instructions make two rules mandatory:

1. Delegate each locator to the domain's isolated locator-specialist subagent (bellatrix-<domain>-locator-specialist), handing it the description and the snapshot path. Only the locator comes back.
2. Otherwise query narrowly with bellatrix <domain> find --snapshot <path> …, which returns a handful of matching nodes.

The agent never reads a snapshot file, snapshot --inline or get-page-source into its main context.

• Desktop (XPath only): //*[@AutomationId='…'] first, then //Button[@Name='…'], then //<ControlType>[@Name='…']; never dynamic AutomationIds or generated class names.
• Web: data-testid, then #id, then aria-label, then role + text (XPath), then CSS. A locator starting with / is XPath, anything else CSS.
• Mobile: accessibility id first, then resource id, then the platform query languages, then class name. A value starting with / is XPath, anything else an accessibility id.

All three domains take the same --locator <expr> [--strategy <s>] flags.

bellatrix web start-session --browser chrome --session w1 --json
bellatrix web navigate --session w1 --url https://demos.bellatrix.solutions/ --json
bellatrix web snapshot --session w1 --json
bellatrix web find --session w1 --snapshot <path> --grep "Falcon 9. to your cart" --json
bellatrix web click --session w1 --locator "a[href='?add-to-cart=28']" --json
bellatrix web close-session --session w1 --json

Mobile follows the same shape with bellatrix mobile start-session --platform android|ios --app <path>, plus mobile-only verbs such as swipe, scroll-to-element and set-context.

Set BELLATRIX_TRACE to a file and every CLI call appends one JSON line: the verb, the arguments (typed text redacted), the exit code, the output size and whether the call was context-heavy (an inline snapshot, a page source or more than 8 KB of output).

$env:BELLATRIX_TRACE = "$PWD\trace.jsonl"
# ... let the agent work ...
Get-Content .\trace.jsonl