CLI Command Reference

This page lists every command currently published by the Ansight CLI. The installed executable remains authoritative for version-specific details:

ansight help
ansight help --beta
ansight <command> --help

Local tools work before sign-in. Optional cloud account commands:

ansight help
ansight --help
ansight <command> help
ansight <command> --help
ansight version
ansight info
ansight --version
ansight doctor [options]
ansight capabilities [options]
ansight host status [options]
ansight host stop [options]
ansight config list
ansight config get explorer-path
ansight config get explorer-port
ansight config set explorer-path <path>
ansight config set explorer-port <port>
ansight config unset explorer-path
ansight config unset explorer-port
ansight account [open]
ansight account access [--json]
ansight account login [options]
ansight account refresh
ansight account status
ansight account logout [--local]
ansight auth login [options]
ansight auth refresh
ansight auth status
ansight auth logout [--local]

Syntax and global options

ansight <command> [subcommand] [arguments] [options]

Headless device launches

Add --headless to any command that can start a device, including device start (boot), app execute, app-graph explore --launch, replay, test run, test run-all, and profile dotnet|ios|android start. It also applies to device starts performed by agent tools during execution, graph runs, or tasks. The option is preserved when forwarding to a resident host and for detached profiling.

On iOS, Ansight boots the simulator without opening Simulator.app. On Android, new emulators use -no-window. Physical devices are unaffected. The flag does not close existing windows or restart already-running emulators; reused sessions keep their existing window state.

Use the flag on the command doing the work, not just on host run. It applies to every selected target in a multi-device run. It is independent of --json, --silent, and --open; CI does not change the visible-by-default policy.

# Boot a device without its native viewer.
ansight device start ios <simulator-id> --headless
ansight device boot android <avd-name> --headless

# Launch an app for execution or App Graph exploration.
ansight app execute --app-id com.example.app --device-id <device-id> \
  --prompt "Verify the home screen" --headless
ansight app-graph explore com.example.app --launch --headless

# Run tests or replay recorded behavior without opening device windows.
ansight test run . onboarding.smoke --headless --json
ansight test run-all . --headless --json
ansight replay ansight <recorded-session-id> --device-id <device-id> --headless

# Start a profiling capture; the flag also works without --wait on a resident host.
ansight profile dotnet start ./App.apk --app-id com.example.app \
  --device-id <android-device-id> --headless --wait
ansight profile ios start ./App.app --app-id com.example.app \
  --device-id <simulator-id> --headless --wait
ansight profile android start ./App.apk --app-id com.example.app \
  --device-id <android-device-id> --headless --wait

app-graph run, connected-session app execute, test run-inline, task run, and repo task run also accept the flag for any device starts their tools request. It does not replace those commands’ live-session prerequisites.

After installing a newer CLI, compare ansight version --json with ansight host status --json. A running host keeps its loaded code until it is restarted; coordinate that restart before relying on newly added launch options. See Update the CLI.

Command index

Version and updates

ansight version [--json]
ansight update check [--channel public|preview] [--json]
ansight update [--channel public|preview] [--json]
ansight update --version <version> --build-number <YYYYMMDDNN>

The build identity combines the human version string with the monotonically increasing daily integer build number. The public or preview update channel is stored in the installation receipt, so promoting an identical preview archive does not alter its embedded build identity. update check is read-only; update downloads the platform installer and changes the active version only after its archive checksum and executable are validated.

analytics

Mandatory engagement analytics records pseudonymous daily active use, any CLI command at most once per 24 hours without its name, and one engaged event per hour after two local actions. Help, version, update, authentication, diagnostics, analytics, and failed commands do not count as active use. The installer separately records successful installs and updates. Detailed analytics requires sign-in and explicit opt-in for that account, then adds normalized command, action, category, feature scope, outcome, duration bucket, and interactive-use fields; it does not include raw arguments, paths, identifiers, prompts, logs, or captured content.

config

Stores local CLI defaults in the selected Ansight data directory. The settings command is an alias for config.

ansight config list
ansight config get explorer-path
ansight config get explorer-port
ansight config set explorer-path <path>
ansight config set explorer-port <port>
ansight config unset explorer-path
ansight config unset explorer-port

The built-in explorer path is /ansight/. explorer-path accepts / or one URL-safe path segment when a different fixed path is needed. Explicit host run --serve-path and serve --path values take precedence over the configured setting.

The built-in explorer port is 47231, making the default local URL http://127.0.0.1:47231/ansight/. explorer-port accepts an integer from 1 through 65535 when a different fixed port is needed. host run --serve-port and serve --port can supply a one-run override. Restart a running resident host after changing either setting.

Fixed paths are easier for other local software to discover than the random capability path, so only configure one on a trusted machine. Use ansight config unset explorer-path to restore the random path and ansight config unset explorer-port to restore automatic port selection.

The JSON result identifies the selected setting for get, set, and unset and includes the complete settings collection so clients can discover both configured values without parsing terminal text.

account

ansight account, ansight account open, and the portal alias open app.ansight.ai in the default browser. If the browser cannot be opened, the command prints the portal URL and the browser warning and returns exit code 1.

account login, refresh, status, and logout delegate to the corresponding auth commands, so scripts can manage authentication from either family.

account grants reports the plan, effective access status, validity period, retention, limits, and enabled cloud capabilities for every accessible organisation. Pass --team-id <uuid> to inspect one organisation. account grant is an alias.

account access verifies cloud sign-in with the server and reports isAuthorized, reason, evaluatedAt, and authorizedUntil. It remains available after expiry and returns exit code 6 when access cannot be verified. auth status reports sign-in state, not cloud service permissions.

account usage reports the selected organisation, the operational AI token bucket, and the workload-identity OpenAI billing allowance as separate balances. It also reports whether the billing period is current and whether hosted execution is presently available. account budget is an alias. When one current organisation permits hosted computation it is selected automatically; otherwise pass --team-id <uuid>.

serve

Starts a transient loopback web explorer and SDK host until interrupted.

ansight serve [--session <id>] [--port <port>] [--path <path>] [--open]

host

host run prints and records its CLI version, daily build number, abbreviated commit, and host log path at startup. CLI-host diagnostics are persisted as <data-directory>/logs/host-<timestamp>-<pid>.log; use ansight host logs instead of locating that path manually. Captured application logs belong to sessions: find them with ansight session list --has-logs, then query them with ansight session logs <session-id>.

On macOS and Windows, the tray menu can restart the resident host. It shows Update Ansight only when the installed channel reports a newer compatible CLI; the update installs in the background, and Restart Ansight activates it.

host run options

The global options select the data directory, SDK ports, platform tool locations, Node.js runtime, output format, and diagnostic verbosity for run, status, logs, and stop. Use ansight config set explorer-path <path> and ansight config set explorer-port <port> to change the pinned local explorer defaults. Unset either setting to use a random path or available port; explicit --serve-path and --serve-port values still win.

ui

ansight ui snapshot [--session <id>|--app <id>] [options]
ansight ui find --automation-id <id>|--text <text>|--role <role> [options]
ansight ui tap <selector> [options]
ansight ui type <selector> --value <text> [--append]
ansight ui swipe [<selector>] [gesture options]
ansight ui pinch [<selector>] --scale <0.1-4> [gesture options]
ansight ui back [--session <id>|--app <id>]
ansight ui wait <selector> [--condition visible|hidden|stable] [options]
ansight ui assert <selector> [assertion options]

These commands are thin adapters over the host semantic UI service. They use the same selector resolution, waits, assertions, evidence capture, and real device-input paths as repository tests and the bounded app agent. Replay widgets use the separate ansight mcp serve stdio command described below.

Target one connected app with --session <id> or --app <id>. The equivalent long forms are --session-id and --app-id; use only one target form.

Embedded replay over MCP

Configure a compatible MCP client to launch ansight mcp serve. This serves the embedded replay viewer over stdio and requires a running local Ansight host. It needs no separate Node server. The replay tools list local recordings and show screenshots, recorded touches, and saved annotations. Open full replay opens that session in the local player’s browser view. Annotation editing and the complete inspection tools are available there.

UI selector options

Selectors apply to every command except snapshot and back. find, tap, type, and assert require one; swipe and pinch may instead target the screen; wait --condition stable does not require a selector.

UI operation options

keyboard

ansight keyboard open <selector> [target options]
ansight keyboard is-open [target options]
ansight keyboard dismiss [target options]

These commands use the same keyboard operations as repository tasks. open focuses a selected text input and verifies that the software keyboard appears; is-open captures fresh keyboard state; and dismiss sends device input only when the keyboard is open, then verifies that it closes. Android reads the system input-method state because UIAutomator does not reliably include Gboard or other IME windows on physical devices.

Use --session/--session-id for an exact connected session. Use --app/--app-id with --device/--device-id to select an application on an exact simulator, emulator, or physical device. A device can be used by itself only when exactly one connected Ansight app session is running on it; otherwise the command requires an app or session identifier. An exact session target cannot be combined with app or device options.

keyboard open accepts the UI selector options and requires at least one selector. --json emits the versioned ansight.keyboard-operation/v1 result.

doctor

ansight doctor [options]

Checks the data directory, credential vault, encrypted secret store, .NET profiling tools, Node.js, image/OCR runtimes, Android and Apple device backends, Android video, and physical-iOS input.

ansight doctor --full --json --output system-report.json
ansight doctor --full --include-secret-metadata --json

Full reports inspect existing state and do not modify installations or skills. Unknown versions and unavailable inventories remain explicit. A generated report returns success even if incomplete; inspect isComplete and section statuses. Secret metadata is not collected without the explicit flag, including when JSON, file output or verbosity is enabled. Use the flag without an assigned value. No report is uploaded.

See System Requirements and Dependencies for what each check enables and how green, amber, and red results behave.

device

Device options

Use the global --adb-path and --xcode-path options to override platform-tool discovery.

By default, device list and the bare devices alias show only live devices: booted virtual targets and connected physical devices. Use --all or --offline to include offline, shut-down, unauthorized, and otherwise unavailable targets.

Use --phone or --tablet to filter by form factor. These flags compose with platform, device-kind, live/offline, and app-ID filters; passing both includes both form factors. The JSON inventory reports the detected formFactor on each classified target and excludes unknown device classes from either filter.

Use ansight devices --app-id com.example.app to search live targets, or add --all or --offline to search every discovered target. Platform and device-kind filters are applied before installed apps are inspected. Shut-down iOS Simulators are inspected from their local Simulator data without booting them. Android and disconnected physical targets that cannot expose their installed apps remain non-matches and produce a warning.

Matching text rows include version=<value> and, when available, build=<value>, installed=<timestamp>, and updated=<timestamp>. Android reports package-manager first-install and last-update times. Simulator installation time is a best-effort bundle container creation time. Physical iOS timestamps remain absent unless devicectl supplies them. JSON output includes the same fields under applicationMatches.

audio

Start with the Microphone Audio Input setup guide for driver installation, permissions, per-run routing and troubleshooting.

iOS audio workflows must run serially on one selected simulator, including when using execute or workspace tests. See audio concurrency restrictions.

Deliver a local WAV to an existing Ansight-connected virtual device’s microphone. Both commands require --session <id>; --session-id is an alias. The resident host uses that session’s device and does not launch the app or choose another session. Start recording and grant microphone permission through the app first.

ansight audio capabilities --session <live-session-id> --json
ansight audio inject --session <live-session-id> \
  --file ./fixtures/audio/quote.wav --timeout-ms 30000 --json

JSON output preserves the host’s ansight.audio-capabilities/v1 or ansight.audio-injection/v1 payload. Completed injection records fixture hash, format, frame count, provider timing and a retained delivery evidence ID. It does not prove app capture or transcription: assert the app’s resulting transcript or saved recording separately. Failures retain diagnostic codes and partial-delivery evidence. Ctrl+C requests cancellation and keeps the control connection open for up to 10 seconds for the host’s final cleanup acknowledgement. If that grace expires or the connection fails, the CLI reports unconfirmed cleanup and possibly partial delivery; it does not claim the audio stopped successfully. Interrupted audio is never retried automatically.

On iOS, install a loopback provider such as BlackHole separately and select it as Simulator audio input. The provider verifies the effective route; the Mac’s default microphone and speakers are unchanged. A loopback route may be shared by multiple simulators, so the current provider requires exactly one booted iOS simulator and serializes injections across the host route. The configured Xcode’s Simulator UI must already be running, with English Audio Input/Sound Input menus and macOS Accessibility access available for route verification. The default device UID is BlackHole2ch_UID; set ANSIGHT_AUDIO_DEVICE_UID in the resident host’s environment to select another supported virtual duplex device. On macOS 14.2 or later, a readiness wait can observe an active input client on that host device; this does not identify the target app’s recording stream. With the default zero wait, iOS verifies the route only; the caller must already have started app recording.

Before iOS audio tests, run this preflight from the same Terminal, IDE, or launcher that starts the resident Ansight host:

ansight doctor --require permission.accessibility --require device.ios.audio.blackhole

The Accessibility check queries the bundled audio helper without prompting or requiring a booted Simulator. A missing grant fails this preflight. To set it up:

open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'

Enable the host launcher in Privacy & Security > Accessibility, using + if it is missing, then rerun doctor. Restart the host from that launcher if access is still denied. macOS normally remembers the grant across restarts; switching launchers or changing signing identity may require approval again. Doctor cannot grant this permission. Permission and driver checks do not establish that the correct Simulator audio input is selected; audio capabilities checks the route.

On Android, active guest capture, disabled host microphone access, and healthy authenticated emulator gRPC are required. Unsupported or degraded states fail with diagnostics. Android Emulator 37.1.11 has an observed native audio-injection race that can crash the emulator. Readiness guards mitigate known unsafe states but do not guarantee stability on that version; Ansight does not restart the emulator or retry injection automatically. Physical devices are unsupported. Use ansight doctor for local dependencies.

The tasks TypeScript API exposes the same host operation as ansight.device.injectMicrophoneAudio. Task fixture paths are relative to the pinned repository root. Local CLI forwarding is not a remote file upload; hosted workers need the fixture present in their own workspace.

input

Android uses ADB display-pixel coordinates. iOS Simulator input uses the packaged macOS Simulator HID bridge and logical screen-point coordinates, normalized against the current screenshot orientation; check the bridge with ansight doctor. iOS HID swipe and pinch durations are clamped to the supported 50–2000 millisecond range.

Input options

app

app watch

Save monitors for installed apps on iOS simulators, Android emulators, or one explicitly selected physical iOS or Android phone. The resident host must be running to capture; monitor definitions survive restarts. The host discovers booted virtual devices, including those booted later. No device registration is required. See External App Monitoring for the local UI and capability limits.

ansight app watch add com.example.notes --platform ios \
  --capture-file Documents/notes.sqlite
ansight app watch list --json

For a physical iPhone with a store-installed app, set up Appium/XCUITest and a provisioned WebDriverAgent, then run:

ansight app watch add <app-id> --platform ios \
  --device-id <coredevice-id> --instruments

This captures screenshots and accessible UI. --instruments retains an Activity Monitor trace and adds CPU and memory channels if its process table exports. Native logs and private sandbox files remain unavailable. See external monitoring for signing and capture setup.

Virtual-device capture follows the process lifetime. A physical iPhone watch ends after two observations with the app outside the foreground. Exit-file copies are best effort on exit, disable, removal, or host shutdown, and are skipped on observed restarts or device loss. One capture can own a virtual device at a time. App registration and workspace linking do not themselves create a monitor.

Execute against an external session

app execute <live-session-id> --prompt <text> can attach to a monitored session. Its capture source determines execution mode, and one execution reserves it at a time. Normal completion or cancellation releases the reservation while leaving the app monitor running. To launch without an existing session, use --execution-mode device:

ansight app execute --app-id com.example.notes --platform android \
  --device-id <emulator-serial> --execution-mode device \
  --prompt "Create a note and verify it appears in the list"

Device mode supports visible UI and available host evidence. SDK app tools and App Graph execution require an SDK session; unavailable operations are refused with capability guidance. See workspace tests without the SDK for installed-app reuse and build artifact restrictions.

App options

With --app-graph, the agent first classifies a published shortest-path route as full coverage, partial coverage, or no match. It follows compatible graph bindings and their postconditions, then continues only the uncovered part of the prompt. Without the flag, App Graphs are not fetched or included in model context. Repository tasks use the same full/partial/no-match check before the agent falls back to live UI exploration.

Full evaluation traces are also opt-in. Add --trace when the run must be reviewed in the local player or exported with test export; normal runs retain lightweight audit metadata without storing model context or tool payload bodies.

app tools uses the same authorization vocabulary as every SDK. Each catalog entry has one ordered policy: read, write, or critical. Friendly output prints the policy and either executable or blocked:<denial-code>; JSON output includes a denial object only when the current app state, local guard, or paired-client maximum prevents execution.

With no catalog filter, app tools preserves the legacy behavior and returns the complete full catalog. Supplying a query, feature, category, ID, policy, availability flag, or result limit activates focused retrieval: direct matches default to 20 and executable-only. --detail alone also activates bounded retrieval, but it does not exclude unavailable tools. Use --include-unavailable when inspecting a denial or unavailable exact ID.

Use a focused --detail summary search to select an exact tool ID, then fetch that ID with --tool-id <id> --detail full before calling it. For example:

ansight app tools <session-id> --query "mapbox surface" --policy read --detail summary --json
ansight app tools <session-id> --tool-id redpoint.mapbox.query_surface_contents --detail full --json

Query the catalog before app call or app batch so stale availability is visible before acting. The host filters the compact index before requesting full definitions, includes published prerequisite tools, and handles conditional revisions and compressed SDK responses transparently; see the Remote Tool Protocol for the underlying contract.

With --json, the CLI returns the ansight.app-tool/v1 wrapper and places the catalog in envelope.payload. A filtered catalog reports totalToolCount, matchedToolCount, returnedToolCount, includedPrerequisiteToolCount, isTruncated, and the applied filters. Refine the filters when isTruncated is true; prerequisite entries can make returnedToolCount exceed the direct match limit.

Persistent interactive connection

ansight app interact --session <session-id> --repository <repository-root> --jsonl

Keep the process open and write one JSON object per stdin line. The resident-host pipe remains connected; no agent is started. ready automatically contains a persisted screenshot. Every gesture or task captures and retains its resulting screenshot and timeline event, including failed input. No capture flag is needed. The schema is ansight.app-interaction/v1; correlate responses by id.

The bridge is tree-first: ui includes a fresh accessibility/visual-tree source, timestamp, persisted snapshot ID, and up to 128 visible semantic nodes (text fields bounded to 256 characters). ui.truncated identifies omitted detail. Prefer automation IDs or exact text with role/ancestor constraints. Semantic targets are resolved afresh before input; zero or multiple matches fail safely. Device accessibility is preferred, with SDK tree fallback and a cached fallback capability choice. Tree failure is reported as ui.status: "unavailable"; screenshots remain available for coordinate fallback. Image viewing is not required for ordinary tree-described navigation.

{"id":"query","command":"type","target":{"automationId":"search-field"},"value":"Kalymnos"}
{"id":"select","command":"tap","target":{"text":"Kalymnos","role":"button","ancestorAutomationId":"search-results"}}

Use observed selectors, not these example IDs. target is supported for tap and type; never mix it with coordinates. Targeted typing focuses and replaces by default; replaceExisting:false appends. Role/ancestor alone are insufficient.

{"id":"tap","command":"tap","x":0.5,"y":0.8}
{"id":"swipe","command":"swipe","x":0.5,"y":0.8,"endX":0.5,"endY":0.2}
{"id":"pinch","command":"pinch","x":0.5,"y":0.5,"scale":1.5}
{"id":"type","command":"type","value":"Kalymnos"}
{"id":"back","command":"back"}
{"id":"observe","command":"snapshot"}
{"id":"catalog","command":"tasks"}
{"id":"run","command":"task","taskId":"search.find","input":{"query":"Kalymnos"}}
{"id":"group","command":"batch","commands":[{"id":"focus","command":"tap","x":0.5,"y":0.8},{"id":"query","command":"type","value":"Kalymnos"}]}
{"id":"done","command":"exit"}

Coordinates are normalized to the screenshot (0–1). type appends to the focused field. Swipe and pinch accept durationMs from 50–2000 (default 250); pinch scale is 0.1–4. Read the screenshot before choosing an unknown target. snapshot is an optional refresh for asynchronous state, not an evidence prerequisite. Responses include screenshot.artifactPath, frame IDs, previousScreenshot (the previously observed frame, not a new before-capture), and input/capture/total timings.

Automatic screenshots wait for 300 ms of visual quietness, allowing 900 ms for an unchanged post-input screen to begin transitioning, within a 2 s sampling window (in-flight capture/persistence can extend it; command timeout still applies). Small 256-pixel probes bracket the final 1024-pixel screenshot; only the final frame is added to session image evidence. screenshot.settling reports status (stable, unchanged, timed_out), probeCount, and elapsedMs. Continuing animation returns ui_unsettled with retained evidence and stops a batch. No input is replayed. Visual quietness does not establish semantic or network completion; use returned UI state or task assertions. Do not routinely send another snapshot after each action.

--repository is optional for gestures but required for tasks and task. The task catalog and normal task engine are scoped to the connection’s fixed repository, app and session. Choose exact IDs and inputs from the catalog. The returned task includes status, assertions and tool calls; only Passed succeeds, and a task with no assertions is Inconclusive. Discover matching maintained tasks before manually duplicating their steps. A task that enters and selects a search query should receive that query directly, without an extra preceding focus/type sequence.

Batches contain 1–32 commands, including tasks. They are validated in full before any child executes, run sequentially with evidence for each action, and stop at the first failure. The response contains ordered results and skippedIds, plus the last executed child’s ui and screenshot at the top level (no stale fallback when that child has no evidence). Top-level timing sums child input/capture times and measures actual host batch wall time, excluding agent/tool orchestration. Check all child statuses and inspect final state; intermediate images are optional. Nothing is rolled back or replayed. All IDs within a batch must be unique; nested batches and exit children are rejected. Batch only known sequences that do not require intermediate decisions. Every input line is limited to 65536 characters; unknown properties are rejected.

--timeout-ms bounds each ordinary command (default 15000, range 100–60000). --task-timeout-ms bounds each task (default 120000, range 100–300000). Timeout or disconnect can leave execution uncertain and interrupt evidence capture; do not blindly retry commands or partially completed batches. Missing evidence prevents further gestures until automatic capture recovers. exit or stdin EOF detaches without stopping the app or host; Ctrl+C cancels the connection. Both CLI and resident host must support this protocol. Coordinate any restart of a shared host after upgrading.

Agent-driven execution

app execute accepts three target forms. Pass a connected session ID to keep using that session, pass --app ./Example.app or --app ./Example.apk to install and launch a build, or pass --device-id <id> --app-id com.example.app to launch an already installed app on an exact target. Launch mode boots the target when necessary, installs an artifact when supplied, waits for the app’s Ansight SDK session, and then starts the bounded agent run. Repeat --device-id in launch mode to run the same prompt concurrently on every selected device. The command waits for every device run and reports one aggregate result; it succeeds only when all device runs succeed.

ansight app execute --app-id com.example.app \
  --device-id <ios-simulator-id-1> \
  --device-id <ios-simulator-id-2> \
  --device-id <android-emulator-id> \
  --prompt "Open settings and verify notifications are enabled"

Each selected target is booted when necessary. Supplying --app installs the artifact only when its checksum differs from the copy already installed on that target; a matching build is reused. Target preparation and prompt execution happen concurrently.

By default, app execute leaves the app open. Add --close-app-on-completion to close only the app process when execution finishes, including failure or cancellation. It applies to both launched apps and an app selected through an existing session; with multiple devices, each run closes its own app instance. The simulator/emulator remains running, its window is left open, and the Ansight host is not stopped. This option is independent of --headless.

ansight app execute <session-id> --prompt "Verify the home screen" --close-app-on-completion
ansight app execute --app-id com.example.app --device-id <device-id> \
  --prompt "Verify the home screen" --headless --close-app-on-completion

Cleanup is also attempted if a successfully launched app never connects to Ansight. Existing sessions must resolve to a known host device; use --device-id when the session cannot report it, such as a physical iOS target. A device that conflicts with the session is rejected before execution. Cleanup has a separate 30-second timeout, including on cancellation. A cleanup failure is reported as [app.close.warning] on stderr without replacing the execution result or exit code; the app may still be running. Forced process termination cannot guarantee cleanup. This option belongs to app execute, not test run-inline or App Graph commands.

Agent runs use an eligible organisation’s entitlement and obtain model credentials automatically through Ansight. If more than one organisation permits the app, pass --team-id. The agent runs on the machine driving the app. The model connection uses Ansight cloud authorization and a brokered credential or proxy. Setting OPENAI_API_KEY or ANSIGHT_AI_TRANSPORT does not enable a local key mode. For unattended runs, set ANSIGHT_RUNNER_API_KEY and ANSIGHT_TEAM_ID with an app-scoped key granting ai:execute. This supports app execution, AI tests, replay, App Graph execution/exploration, and task extraction/refinement without a saved user login. Keys use the hosted model proxy and the organisation’s existing AI permissions and allowance. See runner key issuance. Use local App Graph storage with runner keys; --graph-store hosted still requires the existing signed-in cloud storage access. Restart an older resident host after upgrading so it can accept credentials scoped to an individual AI command; these credentials are not saved to host settings.

App execution, test runs, replay, App Graph runs and exploration share the same Reasoning mode setting as task extraction. Use --reasoning fast|balanced|deep; omitting it selects fast. Fast prioritises speed and economical execution, Balanced balances speed with additional reasoning, and Deep allocates more reasoning to complex workflows. Every mode follows the same requested steps and verification requirements.

The server resolves the mode using the client’s configuration. The initial model mappings are Fast → gpt-5.6-luna, Balanced → gpt-5.6-terra, and Deep → gpt-5.6-sol, each with provider reasoning effort medium. Run audits record the resolved model, provider reasoning effort, and configuration revision.

ansight app execute --app-id com.example.app --reasoning fast --prompt "Open Settings and verify the account details."
ansight test run ./ansight smoke-test --reasoning deep

The legacy --model flag remains available for diagnostics; it cannot be combined with an explicit --reasoning selection.

--model-transport auto tries WebSocket when available and falls back to HTTP on a WebSocket transport failure. Use --model-transport websocket to require WebSocket, or --model-transport http to use HTTP. --openai-transport has been renamed to --model-transport.

app-graph

app-graph explore builds a semantic navigation directory rather than executing a user goal. Each destination records a canonical name, evidence-backed synonyms, and its user-facing purpose. Each transition records the interacted element’s stable automation ID and the product-level meaning of using it, alongside its executable binding. The command performs up to 1024 safe navigation actions and receives a dedicated allowance of 1024 model round trips by default. It refuses destructive and financially meaningful interactions, records its agent audit, and creates a live_exploration observation. When targeting an existing graph, the graph remains unchanged until a reviewer accepts that observation in the portal and creates a new immutable draft version. A successful exploration that creates a new graph instead uses the candidate for its initial draft and attaches the observation to that version.

The ansight.app-graph/v1 graph contract accepts only screen, dialog, and state destinations. Destinations require name and purpose; named states also require parentScreen. Every edge requires action.automationId and action.semanticMeaning. Workflow node kinds and alternate graph fields are rejected rather than inferred.

The command targets an App ID rather than a generated session ID: the resident host selects the most recently active linked session for that app from its connection and feedback activity. Use --session-id <id> only to override that selection when the app has multiple connected instances. When no linked session is live, an interactive invocation offers to launch the installed app on a compatible simulator or device and waits up to 45 seconds for its Ansight connection. Scripts and JSON callers can opt in with --launch; use --wait-seconds, --device-id, --platform, or --device-kind to constrain startup, and --no-launch to suppress the prompt.

The App ID is optional when the current folder is connected to one Ansight workspace app. Interactive terminals prompt when the folder maps to multiple apps or no workspace app can be inferred; scripts and JSON callers should pass --app-id <id>. With no --graph, the command reuses the app’s Default graph or creates it as a reviewable draft after the exploration succeeds. --graph <name-or-id> selects an existing graph, while --new-graph <name> deliberately starts another one. Use --team-id <uuid> when the app is registered with multiple organisations, --focus <text> to prioritise an app area, --max-actions to adjust the bound, --no-save for local output only, and --result-file <path> to retain the structured candidate. Advanced runs can lower the exploration allowance with --max-turns, --max-round-trips, and --max-tool-calls.

App Graph options

pairing

Pairing options

The pairing code is a one-use credential. Request it with --code, --qr, or --qr-output; when one of those flags is present, --json returns the credential in the structured issue result instead of rendering terminal QR artwork.

companion

Companion options

Start a CLI companion host with ansight host run --companion-access session --machine-name "Development Mac". Use the same global --data-dir on management commands when the resident host uses a custom state directory.

Companion access must first be enabled for the organisation by a superadmin. The organisation then allows new named, hardware-fingerprinted machines by default or requires administrator authorization. Required-authorization requests email organisation admins; approval in the portal emails the requesting member. Use --team-id when the signed-in member has more than one eligible organisation.

machine aliases machines; connection aliases connections; show aliases machines get; remove aliases permanent machines delete; and --mode once aliases --mode session.

profile

The first argument selects ios, android, dotnet, or sample. Use ansight profile <technology> --help for the technology-specific reference.

Native profiling

Native profiling options

The authoritative iOS artifact is an Instruments .trace bundle, which Ansight validates by exporting its table of contents. The authoritative Android artifact is a raw .perfetto-trace file. Inspection never modifies either authoritative artifact. Android overview and query use trace_processor or trace_processor_shell from PATH; set ANSIGHT_TRACE_PROCESSOR_PATH to an executable or containing directory when it is installed elsewhere. Overview still reports the retained manifest and Perfetto configuration when Trace Processor is unavailable.

Resident hosts expose the same inspection layer through ansight_native_list_captures, ansight_native_get_capture_manifest, ansight_native_get_capture_artifact, ansight_native_get_trace_overview, ansight_ios_get_instruments_toc, and ansight_android_query_perfetto. Inspection responses are produced from artifacts under the capture directory; ad-hoc Perfetto query results are returned to the caller and are not added to the immutable capture manifest.

Local process stack sampling

profile sample wraps the macOS /usr/bin/sample tool and attaches to an already-running local process. It supports macOS applications, Mac Catalyst applications, and iOS Simulator application processes. It cannot attach to an application process running on a physical iOS device.

For example:

ansight profile sample start 12345 --duration-seconds 3 --interval-milliseconds 1 --wait

The authoritative artifact is the plain-text sampled call graph produced by sample. Ansight retains it alongside a manifest and diagnostic capture log.

.NET profiling

Profiling capture options

Ansight never restores, builds, publishes, or modifies an application. The supplied artifact must already have .NET diagnostics enabled and use the target-specific DiagnosticConfiguration. --app-id and --device-id are required for capture.

For an exact application-ready boundary, the app can emit a StartupComplete event from an EventSource named Ansight-DotNet-Startup. Without that event, startup analysis uses runtime and trace-boundary milestones.

The recommended way to prepare the app is the opt-in Ansight.Profiling.DotNet package. Reference it normally, then enable it only for a dedicated profiling configuration owned by the app. Use Version="*" to resolve the latest published release:

<ItemGroup>
  <PackageReference Include="Ansight.Profiling.DotNet" Version="*" />
</ItemGroup>

<PropertyGroup Condition="'$(Configuration)' == 'Profile'">
  <AnsightProfilingEnabled>true</AnsightProfilingEnabled>
  <AnsightProfilingTarget>android-emulator</AnsightProfilingTarget>
</PropertyGroup>

Supported values are android-emulator, android-device, ios-simulator, and ios-device. The package configures the diagnostic endpoint and embeds ansight/dotnet-profiling.json. Ansight validates that manifest against the selected device before installation. Artifacts configured manually remain supported when the manifest is absent.

Call the package API when the first usable screen is ready:

using Ansight.Profiling;

AnsightProfiler.ApplicationReady();

The call is idempotent and supplies the exact application-ready boundary. The app or its CI remains responsible for building the artifact; Ansight never invokes this build.

Profiling analysis options

Global --json output uses the ansight.dotnet-analysis/v1 schema and includes the source trace hash and analysis warnings.

The .NET technology aliases are .net and net. Analysis aliases are startup-timeline/timeline, hotspots/cpu-hotspots, calltree, thread-activity, gc-summary, and jit-summary.

task

Task options

A resident host and matching live app session are required. Global --json emits the complete versioned task result. See Task API Reference.

replay

replay converts recorded interaction evidence into at most 50 semantic steps and asks the same bounded UI-control agent used by app execute and workspace tests to reproduce them against a separate live app session. Every plan and run also carries a prominent beta notice in CLI output.

# Inspect derived actions without controlling an app.
ansight replay ansight <recorded-session-id> --plan-only
ansight replay posthog recording.json --app-id com.example.app --plan-only

# Reproduce an Ansight capture. If necessary, Ansight starts a compatible local
# target, launches the installed app, and waits for its fresh SDK session.
ansight replay ansight <recorded-session-id>

# Select an exact target or install a build before launching it.
ansight replay ansight <recorded-session-id> \
  --device-id <simulator-or-emulator-id> \
  --app <path-to-app-or-apk> \
  --repository <app-repository>

# Download Sentry recording segments without putting the token on the command line.
export SENTRY_AUTH_TOKEN=sntrys_...
ansight replay sentry <replay-id> \
  --organization acme --project mobile \
  --app-id com.example.app \
  --target-session-id <live-session-id>

Replay options

Replay validates its complete option contract before contacting a resident host or performing target discovery. Unknown options, missing option values, and values attached to boolean flags return a usage error without starting a device, launching an app, or driving a session. Use --plan-only to inspect a replay; --plan is intentionally rejected with a suggestion.

Replay stops after its first failed step because later steps depend on reaching the preceding recorded state. The --stop-on-failure flag remains accepted for existing scripts but is no longer needed.

Before target discovery or app launch, an Ansight replay measures screenshot support around the actions in the selected source range. The plan reports retained-change FPS, observed frame intervals, the percentage of timed replay steps with a screenshot within 1.5 seconds, and how many actions have distinct supporting change frames. Distinct support considers all frames within that window, assigning each frame to at most one step; two steps sharing a nearest frame can still have distinct nearby support. Exact consecutive duplicate JPEGs are suppressed, so quiet frame gaps are reported but do not by themselves reduce the rating. Support is rated reliable, degraded, or unreliable; degraded and unreliable captures are blocked unless --allow-sparse-frames is explicit. Prefer making a new capture over using the override. Sentry and PostHog RRWeb exports use an event-driven DOM mutation stream rather than periodic Ansight screenshots, so this screenshot-cadence gate does not apply to those sources.

For Ansight captures, taps are correlated with nearby visual-tree nodes and screenshots. Ordinary text-entry actions are inferred by matching stable input nodes across consecutive visual trees and comparing their visual.value content. Intermediate values in one typing burst are compacted to the final replacement, while an empty final value becomes a clear-field action. Generated steps retain source visual-tree, screenshot, and normalized touch-coordinate references for review; live execution always resolves the current semantic target instead of reusing a capture-local node ID.

Cancelled touch gestures are omitted with a plan diagnostic. Replaying a cancelled gesture as a completed tap or swipe could perform a different action.

Text inference requires a capture mode that records visual trees. A touch-triggered tree can observe the final value at the next touch; a session that ends with the keyboard still open may need screenshot-aligned periodic trees or an explicit post-edit capture. Secure or provider-omitted values are never reconstructed. Use --secret <alias> or an explicit repository task input for those fields. Return/Done/Search keys, shortcuts, selection, cursor movement, and IME composition are not represented by a value transition. Because this is state diffing rather than key logging, paste, autofill, and programmatic value changes can look identical; uncorrelated changes are marked for review in plan diagnostics.

Sentry and PostHog replay data is also best-effort input: privacy masking can remove field values and labels, coordinates may not map to a different viewport, and unsupported gestures are skipped. These cases are returned as diagnostics in the plan and run output. Provider tokens are used only for the download request and are never included in command output.

Live execution first reuses a compatible connected app session. When none is available, it uses the same target launcher as workspace tests: it discovers a compatible local device, boots it when necessary, optionally installs the supplied app artifact, launches the app, and waits for a fresh Ansight SDK session. Native Ansight captures infer their platform and, when available, their native device identifier from the recorded device profile. Ambiguous target inventories require --device-id; missing installations require --app or --ipa.

Replay uses the same authenticated test-run preparation and metering path as workspace tests. A signed-in session with an expired access token is refreshed automatically when its refresh token is available, then the organisation AI execution credential is supplied to the replay agent. A runner key with ai:execute and ANSIGHT_TEAM_ID can use the same flow without a saved login.

Before live control begins, the target session is durably tagged with replay-driven, replay-beta, replay-source-<provider>, and replay-status-running. Completion replaces the running tag with the latest replay-status-succeeded, replay-status-failed, or replay-status-cancelled value while preserving unrelated user tags.

post-hog is accepted as an alias for the posthog replay source.

repo

Repository options

automations, trigger, and triggers alias automation. Linked Agent workspaces restore enabled trigger connections whenever the resident host starts.

workspace

Workspace options

See Workspace for the generated files and authoring APIs.

Workspace ZIPs contain files rooted under ansight/, excluding .git, node_modules, and .DS_Store. Host secrets, registrations, and session history are not transferred. Import validates and decompresses the archive before updating the destination; it does not register or execute imported definitions. Both commands enforce 100,000 entries (including parent directories) and 2 GiB expanded size. Unsafe paths, links, duplicate paths, and corrupt entries are rejected. Use --json for the ansight.workspace-archive/v1 result. See Export and import a workspace ZIP for a complete transfer and registration example.

initialize aliases workspace init; create aliases workspace add. Definition kinds accept their plural forms, automation for trigger, and the British spellings sanitiser and sanitisers.

auth

sign-in aliases login, and sign-out aliases logout. The same aliases are accepted beneath account.

Authentication options

With no mode flag, login opens app.ansight.ai. The portal accepts the normal account sign-in and returns the session to a state-validated HTTP loopback callback using a form POST, so tokens are not placed in the browser URL. The portal creates a non-persistent session specifically for the CLI instead of sharing the browser portal’s rotating refresh token.

Choose at most one alternate login mode:

Additional authentication flags are:

Without --stdin or --from-env, an interactive terminal uses a hidden prompt. Secret values are never accepted as ordinary command-line arguments or printed.

secret

Secret options

Without an input flag, an interactive terminal uses a hidden prompt. Secret values are never accepted as ordinary command-line arguments and are never returned by list.

--from-env copies a value into the configured secret store. Workspace and inline test runs can instead resolve a requested secret directly from an environment variable whose name exactly matches the alias. An app-scoped stored value takes precedence when both sources contain that alias.

test

Test target options

Test runner and output options

Concurrent test execution

Repeat --device-id with test run to execute the same test concurrently on every selected device:

ansight test run . onboarding.complete \
  --device-id <ios-simulator-id-1> \
  --device-id <ios-simulator-id-2> \
  --device-id <android-emulator-id>

Audio APIs reject parallel test batches on both platforms. Do not use --parallel or select multiple devices. Calls reject with audio-parallel-execution-unsupported and are logged in test progress and the task call audit. For iOS, also avoid overlapping audio jobs on the same Mac. Removing --parallel alone does not serialize a multi-device run. See audio concurrency restrictions.

Without --parallel, test run-all uses matrix scheduling: the current test runs on every selected device as one concurrent cohort, Ansight waits for the whole cohort, and then the next test starts.

ansight test run-all . \
  --device-id <ios-simulator-id-1> \
  --device-id <ios-simulator-id-2> \
  --device-id <android-emulator-id>

Pass --parallel to use the selected devices as a worker pool instead. Every selected test runs exactly once. Each device runs at most one test at a time and receives the next pending test as soon as it becomes available; extra devices remain idle when there are fewer tests than devices.

ansight test run-all . --parallel \
  --device-id <ios-simulator-id-1> \
  --device-id <ios-simulator-id-2> \
  --device-id <android-emulator-id>

Both modes wait for all active device runs before returning. With --stop-on-failure, active runs finish, but no pending tests are started after a failure is known. Explicitly selected stopped devices are started automatically. When --app is supplied, a matching installed artifact is reused by checksum instead of being reinstalled.

Test history options

test run-all creates and maintains its own batch run ID automatically. Use --batch when tests must be launched by separate test run commands but still reviewed as one correlated group:

ansight test run . onboarding.complete --batch release_20260901
ansight test run . checkout.purchase --batch release_20260901
ansight test history --batch release_20260901
ansight test inspect release_20260901

A correlated batch does not create or overwrite a managed run-all batch audit. test inspect <batch-id> resolves every locally retained execution with the matching correlation ID.

trends

Trends history options

trends rebuild replays stored metrics in chronological order. It recomputes baselines, pinned release comparisons, and consecutive-run confirmation from the current registered workspace rules, then replaces the selected comparisons atomically. It does not re-extract metric values from session replays.

session

Inspection

session list filters the lightweight summary index and does not hydrate logs, telemetry, network requests, screenshots, trees, or artifacts. JSON output uses ansight.sessions/v3 and reports matchedCount, returnedCount, limit, isTruncated, nextCursor, and the current sessions page.

Inspection options

Connectivity options

ansight session connectivity <session-id> summary --json
ansight session connectivity <session-id> at --offset 01:15 --json
ansight session connectivity <session-id> events --from 00:30 --to 02:00 --json
ansight session connectivity <session-id> quality --limit 100 --json
ansight session connectivity <session-id> timeline --annotation <annotation-id> --before 120 --after 30 --json

summary is the default. events excludes quality-only observations; quality includes observations carrying quality; timeline includes every kind. Results describe capture bounds, clipping, and supported measurements. An absent flag is unknown, and availability alone does not establish internet or server reachability.

See Connectivity Review for player and agent workflows, Connectivity Capture for SDK setup, and Offline Capture to import a raw SDK ZIP, including password-protected archives.

Telemetry analysis options

Editing and evidence export

Editing and export options

Management and cache

Metadata options

Cache options

Automatic cache maintenance defaults to compacting inactive captures after 30 days and deleting eligible unpinned captures after 90 days. Run compaction on demand with:

ansight session cache compact
ansight session cache compact --compaction-age-days 14
ansight session cache compact --json

Compaction is non-lossy: the expanded session folder becomes a ZIP archive on disk. Opening the session expands it automatically and resets its compaction age, so it must remain unopened for another threshold period before it is compacted again. Live sessions are skipped. Pinned historical sessions may be compacted because their data remains preserved; pinning continues to protect them from deletion.

Replay, sharing, and archives

Replay options

Cloud sharing options

The default session summary action requires an existing team share. Run session share first when using Cloud AI with a local-only capture. The local player’s Cloud AI results and Flowchart use the selected capture’s newest cloud share.

Use session summary <session-id> --local to keep the capture in local storage. The brokered model receives a bounded selection of session evidence; the session is not uploaded as a team share. Local describes where the result is saved: the AI still runs in Ansight’s hosted service and receives selected evidence and screenshots. Authenticate with a signed-in account, or an app-scoped runner key with sessions:summarize (or ai:execute) and ANSIGHT_TEAM_ID. The organisation must permit hosted AI/workspace model runs and have AI allowance remaining. Use --team-id <uuid> to select an organisation for a signed-in account or assert the runner key’s organisation. The app is taken from the session and must match the key. The saved result appears in session analyses and is included when that session is subsequently shared. Use --json for the summary and analysis ID.

An owner or administrator issues the key once from a signed-in machine:

ansight auth login
ansight cloud app register com.example.app --team-id <team-id>
ansight cloud key issue --team-id <team-id> --app-id com.example.app \
  --name "Tester summaries" --scope sessions:summarize --scope sessions:write

Store the returned an_run_... value in your CI or tester secret store. On the unattended machine, inject it as an environment secret and run:

export ANSIGHT_RUNNER_API_KEY='<secret from the key issuer>'
export ANSIGHT_TEAM_ID='<team-id>'
ansight session summary <session-id> --local --team-id "$ANSIGHT_TEAM_ID" &&
ansight session share <session-id> --team-id "$ANSIGHT_TEAM_ID" --access team

No interactive login is required on that machine. ANSIGHT_API_KEY remains an alias; ANSIGHT_RUNNER_API_KEY takes precedence. Expired or revoked keys and keys for another app or organisation are rejected. The issuing member must remain in the organisation; reissue the key if they leave. Summaries consume the same organisation AI allowance as signed-in runs. Existing upload-only keys do not gain AI access.

Archive options

session share and session export preserve the raw capture unless --sanitize or --sanitizer is supplied. session sanitize applies the built-in policy when no custom module is supplied. The built-in policy redacts structured PII, masks screenshots whose raster content cannot be proven safe, excludes artifacts, and records its work in sanitization/report.json.

share-url and replay-url alias session url; sanitise aliases session sanitize.

cloud

Registers cloud App IDs and administers uploaded Trends history, test-run summaries, sessions, attachments, and hosted analysis. Administration uses the current auth session. Headless uploads and AI actions can instead use an app-scoped runner credential through ANSIGHT_RUNNER_API_KEY and ANSIGHT_TEAM_ID. The app identity is derived from the key; ANSIGHT_APP_ID is only an optional default for commands that select matching local app data. Registering an App ID expresses cloud intent but does not start billing. Uploads and other cloud writes require the organisation’s corresponding trial, paid entitlement, or explicit grant.

Cloud query and transfer options

For all CLI AI actions, issue an explicit ai:execute key instead of the summary-only scope. Add upload scopes separately when the workflow uploads data:

ansight cloud key issue --team-id <team-id> --app-id com.example.app \
  --name "CI AI" --scope ai:execute --scope sessions:write --scope tests:write

With that key and ANSIGHT_TEAM_ID configured, session summary on an existing share and cloud analysis run|summary|list|archive|restore work without login. Session discovery and analysis results are restricted to the key’s app and team. ai:execute also covers local summaries, app execution, AI tests, replay, App Graph AI execution/exploration, and task extraction/refinement. It does not grant uploads, key administration, remote runner administration or unrelated cloud access. Default key scopes remain sessions:write, trends:write, and tests:write; neither AI scope is granted automatically.

Hosted analysis options

Every cloud resource accepts its plural alias. Runner-key aliases are keys, runner-key, and runner-keys; add aliases app registration; and delete aliases app removal. remove aliases session, attachment, and key deletion or revocation as appropriate.

licenses

Exit codes

Related docs

• CLI Overview
• Workspace
• Task API Reference
• Trigger API Reference
• Data, Privacy, and Analysis