CLI Command Reference
Complete reference for Ansight CLI commands, subcommands, aliases, global options, identifier discovery, and process exit codes.
CLI v0.23.1
This page lists every command currently published by the Ansight CLI. The installed executable remains authoritative for version-specific details:
ansight help
ansight <command> --helpCanonical interface. Use this reference for command discovery and confirm version-specific details against the help shipped with the installed CLI.
Syntax and global options
ansight <command> [subcommand] [arguments] [options]| Option | Meaning |
|---|---|
--help, -h, -? | Show help for the selected command family. |
--json | Emit a versioned machine-readable result. |
--silent | Suppress stdout and stderr, overriding JSON output. |
--verbose | Include debug, telemetry, and app-event diagnostics. |
--data-dir <path> | Select host state; also supported through ANSIGHT_DATA_DIR. |
--adb-path <path> | Select an ADB executable or Android SDK directory. |
--xcode-path <path> | Select an Xcode app or Developer directory. |
--secret-store-file <path> | Use an encrypted file instead of the OS credential vault. |
--secret-key-file <path> | Read the encrypted store’s AES key from a protected file. |
--discovery-port <port> | Override the UDP SDK discovery port. |
--websocket-port <port> | Override the SDK WebSocket port. |
--node-path <path> | Select the Node.js runtime used for repository modules. |
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.
| Option | Applies to | Meaning |
|---|---|---|
--json | version, update check, update | Emit the complete versioned build or update result. |
--channel <public|preview> | update check, update | Check or select a release channel. Without this flag, the installed channel is used. |
--version <version> | update check, update | Select an exact human-readable release version. It must be supplied with --build-number. |
--build-number <YYYYMMDDNN> | update check, update | Select the exact positive daily build number. It must be supplied with --version. |
analytics
Daily active-use analytics records one pseudonymous event per installation and UTC date after a successful, meaningful product command outside CI. 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 adds only 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.
| Option | Meaning |
|---|---|
--data-dir <path> | Read or change analytics settings in a non-default Ansight data directory. |
--json | Emit the versioned analytics status result. |
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.
| Option | Meaning |
|---|---|
--json | For account or account open, emit the portal URL, whether it opened, and any browser warning. Authentication actions use the authentication options. |
serve
Starts a transient loopback web explorer and SDK host until interrupted.
ansight serve [--session <id>] [--port <port>] [--path <path>] [--open]| Option | Meaning |
|---|---|
--session <id> | Select the session shown when the explorer opens. |
--port <port> | Bind the explorer to this HTTP port. The default, 0, selects an available port. |
--path <path> | Use / or a fixed URL-safe segment instead of the default random capability path. Fixed paths are easier to discover. |
--open | Open the explorer in the default browser after it starts. |
--enable-repository-automations | Permit trusted repository trigger execution in this host. |
--automation-repository <path> | Load a trusted trigger repository at startup. Repeat the flag to load more than one repository. |
host
host run options
| Option | Meaning |
|---|---|
--pair <app-id> | Start the host and create a one-use phone enrollment code and terminal QR for the supplied app ID. |
--name <name> | Set a human-readable name on the invitation created by --pair. |
--duration <duration> | Set the pairing lifetime using mo, w, d, h, or m, such as 15m or 1h. The default is one month. |
--host-address <LAN-IP> | Put an address reachable by the phone into the pairing payload instead of relying on automatic host-address selection. |
--serve-port <port> | Bind the local explorer to this port. The default, 0, selects an available port. |
--serve-path <path> | Use / or a fixed URL-safe explorer path instead of the default random capability path. |
--open | Open the local explorer in the default browser after the host starts. |
--no-serve | Run without the local explorer. It cannot be combined with --open, --serve-port, or --serve-path. |
--companion-access [session|always] | Publish simulators to the signed-in macOS companion app. Omitting the value selects session; always keeps access enabled for CLI management. |
--enable-repository-automations | Permit trusted repository trigger execution in this host. |
--automation-repository <path> | Connect a trusted trigger repository when the host starts. Repeat the flag to connect more than one. |
The global options select the data directory,
SDK ports, platform tool locations, Node.js runtime, output format, and
diagnostic verbosity for run, status, and stop.
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.
| Option | Meaning |
|---|---|
--data-dir <path> | Inspect a non-default host state directory. |
--secret-store-file <path> | Inspect an encrypted file store instead of the operating-system credential vault. |
--secret-key-file <path> | Validate the externally protected AES key used by the encrypted file store. |
--adb-path <path> | Check an explicit ADB executable or Android SDK directory. |
--xcode-path <path> | Check an explicit Xcode app or Developer directory. |
--json | Return every check, whether it is required, and its status as versioned structured output. |
See System Requirements and Dependencies for what each check enables and how green, amber, and red results behave.
device
Device options
| Option | Applies to | Meaning |
|---|---|---|
--ios | device list | Return only iOS targets. |
--android | device list | Return only Android targets. |
--simulator | device list | Return only iOS simulators. --simulators is an alias. |
--emulator | device list | Return only Android emulators. --emulators is an alias. |
--physical | device list | Return only physical devices. --physical-devices is an alias. |
--offline | device list | Include offline, shut-down, unauthorized, and unavailable targets. |
--latitude <number> | device location set | Set the latitude. This flag and --longitude are both required. |
--longitude <number> | device location set | Set the longitude. This flag and --latitude are both required. |
--mode <recorded|fixed-speed> | device location play | Use the route timestamps, or replay at a fixed speed. The default is recorded; recorded-timing and fixed are accepted aliases. |
--speed <number> | device location play | Set a positive recorded-timing multiplier. The default is 1. |
--fixed-speed-kph <number> | device location play | Set a positive fixed replay speed in kilometres per hour. The default is 30; --speed-kph is an alias. |
--loop | device location play | Repeat the route until it is stopped. |
--wait | device location play | Keep the command attached until resident-host playback finishes. Transient playback waits automatically. |
--output <path> | device screenshot | Write the screenshot to this path instead of a timestamped default path. |
Use the global --adb-path and --xcode-path options to override platform-tool
discovery.
input
Android uses ADB. iOS support depends on the packaged macOS simulator input
bridge; check it with ansight doctor.
Input options
| Option | Applies to | Meaning |
|---|---|---|
--x <px> | input tap | Required horizontal screen coordinate from 0 to 100000. |
--y <px> | input tap | Required vertical screen coordinate from 0 to 100000. |
--start-x <px> | input swipe | Required horizontal coordinate where the swipe begins. |
--start-y <px> | input swipe | Required vertical coordinate where the swipe begins. |
--end-x <px> | input swipe | Required horizontal coordinate where the swipe ends. |
--end-y <px> | input swipe | Required vertical coordinate where the swipe ends. |
--duration-ms <ms> | input swipe | Set the swipe duration from 1 to 60000 milliseconds. The default is 300. |
--value <text> | input text | Required text to send through the platform input bridge. |
app
App options
| Option | Applies to | Meaning |
|---|---|---|
--name <name> | app register | Set the app’s human-readable name. |
--codebase <path> | app register | Link a trusted repository root for automatic monitoring and repository definitions. |
--arguments <JSON> | app call | Pass an inline JSON object to the tool. It cannot be combined with --arguments-file. |
--arguments-file <path> | app call | Read the tool’s JSON object from a file. Comments and trailing commas are accepted. It cannot be combined with --arguments. |
--sandbox-root <root> | app push-file | Select one of the sandbox roots published by the connected app. |
--file-name <name> | app push-file | Override the destination filename; otherwise the local filename is used. |
--overwrite | app push-file | Replace an existing destination file. |
--no-create-directory | app push-file | Fail unless the remote directory already exists. |
--limit <count> | app audit | Return at most this many recent app-tool outcomes, from 1 to 1000. The default is 100. |
pairing
Pairing options
| Option | Applies to | Meaning |
|---|---|---|
--code | pairing issue | Print the one-use pairing code for manual entry. |
--qr | pairing issue | Render a scannable QR in the terminal. A resident host must be running. |
--qr-output <path> | pairing issue | Write the QR as a PNG at this path. A resident host must be running. |
--host-address <LAN-IP> | pairing issue | Put an address reachable by the phone into the pairing payload instead of relying on automatic selection. |
--overwrite | pairing issue | Replace an existing file selected by --qr-output. |
--name <name> | pairing issue | Set a human-readable invitation name. |
--duration <duration> | pairing issue | Set the invitation lifetime using mo, w, d, h, or m. The default is one month. |
--app-id <app-id> | pairing list | Return invitations for one application ID. |
--active-only | pairing list | Hide consumed, revoked, and expired invitations. |
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
| Option | Applies to | Meaning |
|---|---|---|
--mode <session|always> | companion access enable | Use session to publish only for the current host lifetime, or always to keep access enabled for later CLI management. The default is session. |
--include-revoked | companion machines list | Include revoked developer-machine registrations. |
--force | companion machines delete | Confirm permanent deletion. Without it, use revoke for the recoverable operation. |
Start a CLI companion host with ansight host run --companion-access session.
Use the same global --data-dir on management commands when the resident host
uses a custom state directory.
profile
The first argument selects the profiler technology. The currently available
technology is dotnet; additional profilers use the same profile <technology> ... hierarchy.
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.
| Target | DiagnosticConfiguration |
|---|---|
| Android emulator | 10.0.2.2:9000,suspend,connect |
| Android physical device | 127.0.0.1:9000,suspend,connect |
| iOS Simulator or physical device | 127.0.0.1:9000,suspend,listen |
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:
<ItemGroup>
<PackageReference Include="Ansight.Profiling.DotNet" Version="0.1.0-preview.1" />
</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.
| Option | Applies to | Meaning |
|---|---|---|
--wait | profile dotnet start | Keep the command attached until capture completion. A detached capture requires a resident host. |
--duration-seconds <n> | profile dotnet start | Set the capture duration from 1 to 300 seconds. The default is 30. |
--app-id <id> | profile dotnet start, profile dotnet import | Supply the bundle/package ID to launch, or associate an imported trace. |
--device-id <id> | profile dotnet start | Target an exact simulator, emulator, or physical device. |
--symbols <path> | profile dotnet start | Copy a portable PDB file or directory into capture storage. |
--limit <count> | profile dotnet list | Return between 1 and 1000 recent captures. The default is 100. |
--application-path <path> | profile dotnet import | Associate an imported .nettrace with an application artifact. |
Profiling analysis options
| Option | Applies to | Meaning |
|---|---|---|
--start-ms <n> | All analysis commands | Set the inclusive start offset from the beginning of the trace. It cannot be negative. |
--end-ms <n> | All analysis commands | Set the inclusive end offset. It cannot be negative or earlier than --start-ms. |
--process-id <id> | All analysis commands | Restrict analysis to one non-negative process ID. |
--thread-id <id> | All analysis commands | Restrict analysis to one non-negative managed or operating-system thread ID. |
--limit <count> | profile dotnet cpu | Return between 1 and 500 hotspots. The default is 50. |
--limit <count> | profile dotnet gc, profile dotnet jit, profile dotnet exceptions | Return between 1 and 1000 results. The default is 100. |
--max-depth <count> | profile dotnet call-tree | Limit tree depth to 1–128. The default is 32. |
--max-children <count> | profile dotnet call-tree | Limit children per node to 1–200. The default is 50. |
Global --json output uses the ansight.dotnet-analysis/v1 schema and includes
the source trace hash and analysis warnings.
task
Task options
| Option | Applies to | Meaning |
|---|---|---|
--app-id <app-id> | task list, task run | Required application bundle or package ID. |
--repository <path> | task list, task run | Use this repository root instead of the current directory. |
--device-id <id> | task run | Select the connected session on this simulator or emulator. It cannot be combined with --session-id. |
--session-id <id> | task run | Select an exact connected Ansight session. It cannot be combined with --device-id. |
--input <JSON> | task run | Pass task input as an inline JSON object. It cannot be combined with --input-file. |
--input-file <path> | task run | Read the task input object from a JSON file. Comments and trailing commas are accepted. It cannot be combined with --input. |
--start <timestamp|offset> | task extract | Required interval start as an ISO-8601 timestamp or seconds after session start. |
--end <timestamp|offset> | task extract | Required interval end as an ISO-8601 timestamp or seconds after session start; it must follow --start. |
--workspace <path> | task extract | Select the workspace root. The default is the current directory; --repository is also accepted. |
--title <title> | task extract | Set the generated task title. The session name or app name is used by default. |
--output <path> | task extract | Write the generated TypeScript to an explicit destination instead of ansight/tasks/<suggested-name>.ts. |
--force | task extract | Replace an existing output file. --overwrite is an alias. |
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 test run-inline to reproduce
them against a separate live app session. Replay is a beta feature: every plan
and run carries a prominent beta notice, and live runs should be supervised.
# 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
| Option | Meaning |
|---|---|
--plan-only | Print the versioned ansight.replay-plan/v1 plan without requiring or controlling a live target. |
--allow-sparse-frames | Explicitly allow a supervised Ansight replay when screenshot support is rated degraded or unreliable. This does not improve the source evidence. |
--app-id <id> | Associate an external Sentry or PostHog recording with the target app. This is optional when --target-session-id supplies the app identity. |
--target-session-id <id> | Control this exact connected Ansight session. --session-id is an alias. The source and target Ansight sessions must be different. |
--device-id <id> | Start and select an exact simulator, emulator, or physical device. --device is an alias. |
--platform <ios|android> | Restrict automatic target selection to one platform. Ansight captures infer this from recorded device metadata when possible. |
--device-kind <virtual|physical> | Restrict automatic target selection by device kind. |
--app <path> | Install an .app or .apk before launch. --ipa <path> installs an .ipa. |
--wait-seconds <count> | Time to wait for the launched app to connect to Ansight. The default is 45 seconds. |
--team-id <uuid> | Select an organisation when more than one organisation permits the app. |
--start <timestamp|offset> | Start an Ansight source range at an ISO-8601 timestamp or a non-negative seconds offset. |
--end <timestamp|offset> | End an Ansight source range at an ISO-8601 timestamp or a non-negative seconds offset. |
--repository <path> | Link trusted repository tasks for the app so the replay agent can use an exact matching task. |
--secret <alias> | Expose a configured host-managed app secret to the run. Repeat for multiple aliases. |
--model <id> | Select the replay-agent model. The default is gpt-5.6-terra. |
--max-turns <count> | Limit turns per step to 1–512. The default is 64. |
--max-round-trips <count> | Limit model round trips per step to 1–500. The default is 64. |
--max-tool-calls <count> | Limit total tool calls to 1–4000. The default is 512. |
--stop-on-failure | Stop after the first failed replay step. |
--organization <slug> | Select the Sentry organization for API download. |
--project <id|slug> | Select the Sentry project slug or PostHog project ID for API download. |
--host <url> | Override the provider host for a region or self-hosted deployment. |
--token-env <name> | Read the provider token from this environment variable. Defaults are SENTRY_AUTH_TOKEN and POSTHOG_PERSONAL_API_KEY. |
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.
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. 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.
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 proxy is supplied to the replay agent. Signed-out development can instead use a locally configured OpenAI API key.
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.
repo
Repository options
| Option | Applies to | Meaning |
|---|---|---|
--session-id <id> | repo task run | Select an exact connected session. It cannot be combined with --device-id; without either flag, the newest connected session for the app is used. |
--device-id <id> | repo task run | Select the connected session on this simulator or emulator. It cannot be combined with --session-id. |
--input <JSON> | repo task run | Pass task input as an inline JSON object. It cannot be combined with --input-file. |
--input-file <path> | repo task run | Read the task input object from a JSON file. Comments and trailing commas are accepted. It cannot be combined with --input. |
--limit <count> | repo automation runs | Return between 1 and 500 recent runs. The default is 100. |
automations, trigger, and triggers alias automation. Connections require
a resident host started with --enable-repository-automations.
workspace
Workspace options
| Option | Applies to | Meaning |
|---|---|---|
--app-id <id> | workspace init | Register this application ID and link it to the new workspace without prompting. It cannot be combined with --no-register. |
--name <name> | workspace init | Set the human-readable name used when --app-id registers the app. |
--no-register | workspace init | Skip app registration without prompting. It cannot be combined with --app-id. |
--title <text> | workspace add task | Set the task’s human-readable title. |
--description <text> | workspace add task | Set the task’s purpose and expected result. |
--app-id <id> | workspace add task | Restrict the task to one application ID. |
--app-id <id> | workspace add test | Set the required application bundle or package ID. |
--name <text> | workspace add test | Set the test’s human-readable name. |
--prompt <text> | workspace add test | Set the scenario instructions for the test runner. |
--validation <text> | workspace add test | Set the final-state validation instructions. |
--assertion <text> | workspace add test | Add an observable assertion. Repeat the flag to add more than one. |
--required-secret <name> | workspace add test | Declare a required secret alias. Repeat the flag for multiple secrets. |
--quality-check <id> | workspace add test | Add a post-run quality definition. Repeat the flag for multiple checks. |
--event-kind <kind> | workspace add trigger | Select the event handled by the trigger. The default is app.event. |
--app-id <id> | workspace add trigger | Restrict the trigger to one application ID. |
--force | All workspace authoring commands | Replace existing definitions or generated support files. --overwrite is an alias. |
See Workspace for the generated files and authoring APIs.
auth
Authentication options
Choose exactly one login mode:
| Option | Meaning |
|---|---|
--provider <name> | Start browser authorization-code login with PKCE for this provider. |
--email <address> | Sign in with email and a password read through secret input. |
--otp | With --email, request an email one-time code and read that code through secret input instead of reading a password. |
--access-token | Validate and save a Supabase access token read through secret input. |
--device | Use OAuth RFC 8628 device flow. Provider endpoint and client settings must also be supplied by flags or environment variables. |
Additional authentication flags are:
| Option | Applies to | Meaning |
|---|---|---|
--no-browser | Provider login | Print the PKCE authorization URL instead of opening the browser. |
--callback-port <port> | Provider login | Bind the local callback to a fixed port from 1024 to 65535; otherwise an available port is selected. ANSIGHT_AUTH_CALLBACK_PORT is the environment alternative. |
--timeout <seconds> | Provider login | Set the browser-login timeout from 0 to 1800 seconds. The default is 300. |
--device-authorization-endpoint <url> | Device login | Set the absolute HTTPS authorization endpoint. ANSIGHT_OAUTH_DEVICE_AUTHORIZATION_ENDPOINT is the environment alternative. |
--device-token-endpoint <url> | Device login | Set the absolute HTTPS token endpoint. ANSIGHT_OAUTH_DEVICE_TOKEN_ENDPOINT is the environment alternative. |
--device-client-id <id> | Device login | Set the required OAuth client ID. ANSIGHT_OAUTH_DEVICE_CLIENT_ID is the environment alternative. |
--device-scope <scope> | Device login | Set the requested OAuth scopes. The default is openid email offline_access; ANSIGHT_OAUTH_DEVICE_SCOPE is the environment alternative. |
--supabase-url <url> | auth login, auth refresh, auth logout | Override the configured Supabase project URL. |
--supabase-publishable-key <key> | auth login, auth refresh, auth logout | Override the public Supabase client key. |
--stdin | Email or access-token login | Read the password, OTP, or access token from standard input. |
--from-env <NAME> | Email or access-token login | Read the password, OTP, or access token from the named environment variable. |
--local | auth logout | Clear local credentials without attempting remote session revocation. |
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
| Option | Applies to | Meaning |
|---|---|---|
--stdin | secret set, secret openai set | Read the secret value from standard input. |
--from-env <NAME> | secret set, secret openai set | Read the secret value from the named environment variable. |
--secret-store-file <path> | All secret commands | Use an encrypted file instead of the operating-system credential vault. |
--secret-key-file <path> | All secret commands | Read the encrypted file store’s AES key from an owner-only file. |
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 or status.
--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
| Option | Applies to | Meaning |
|---|---|---|
--session-id <id> | test run, test run-inline | Reuse an exact connected app session. It is required for run-inline. |
--device-id <id> | test run, test run-inline, test run-all | Select an exact simulator, emulator, or physical device. --device is an alias. For run-inline, this narrows the live app target associated with the selected session. |
--device-kind <physical|virtual> | test run, test run-all | Restrict automatic discovery to physical or virtual targets. |
--platform <ios|android> | test run, test run-all | Restrict automatic target discovery by platform. |
--app <path> | test run, test run-all | Install an .app or .apk before launch. It cannot be combined with --ipa or --application-path. |
--ipa <path> | test run, test run-all | Install a signed physical-device IPA. The path must end in .ipa; the flag cannot be combined with --app or --application-path. |
--application-path <path> | test run, test run-all | Generic application-artifact option. It cannot be combined with --app or --ipa. |
--team-id <uuid> | test run, test run-all | Select the organisation used by hosted execution. The value must be a non-empty UUID. |
Test runner and output options
| Option | Applies to | Meaning |
|---|---|---|
--instruction <text> | test run-inline | Add an instruction to the ordered run. Repeat the flag for multiple instructions; at least one instruction or instruction file is required. |
--instructions-file <path> | test run-inline | Read additional instructions from a text file, one non-empty instruction per line. |
--secret <alias> | test run-inline | Grant an existing app-scoped test secret to the inline run. Repeat the flag for multiple aliases. |
--model <id> | test run, test run-inline, test run-all | Select the model. The default is gpt-5.6-terra. |
--wait-seconds <seconds> | test run, test run-all | Set the app-session connection timeout. The default is 45; the accepted range is 0–86400. |
--max-turns <count> | test run, test run-inline, test run-all | Limit agent turns to 1–512. The default is 64. |
--max-round-trips <count> | test run, test run-inline, test run-all | Limit model round trips to 1–4096. The default is 64. |
--max-tool-calls <count> | test run, test run-inline, test run-all | Limit tool calls to 1–16384. The default is 512. |
--test <id> | test run-all | Select one test instead of the full catalog. Repeat the flag to select multiple tests. |
--stop-on-failure | test run, test run-inline, test run-all | Stop continued execution after the first failed instruction, test step, or batch item. |
--no-workspace-tools | test run, test run-all | Do not expose trusted repository tasks to the test agent. |
--result-file <path> | test run, test run-all | Write the versioned JSON result to this path instead of the generated result path. |
--audit | test run, test run-all | Add token, tool-call, timing, and cost attribution to human-readable output. |
--json | test run, test run-inline, test run-all | Emit the complete versioned result on standard output. |
--silent | test run, test run-inline, test run-all | Suppress standard output and standard error, overriding --json. |
--verbose | test run, test run-inline, test run-all | Include model progress, telemetry, and app events. |
Test history options
| Option | Applies to | Meaning |
|---|---|---|
--app-id <id> | test history, test quality-history | Return history for one application ID. |
--workspace <path> | test history | Restrict batches and executions to one workspace. |
--measurement <key> | test quality-history | Restrict measurements to a quality-id.measurement-id key. |
--trend <id> | test quality-history | Restrict results to one trend definition. |
--group <name> | test quality-history | Restrict measurements and trends to one flow group. |
--limit <count> | test history, test quality-history | Return from 1 to 10000 entries of each kind. The default is 100. |
Trend history rebuild options
test quality-history rebuild replays stored measurements in chronological
order. It recomputes baselines, pinned release comparisons, and consecutive-run
hysteresis from the current registered workspace rules, then replaces the
selected decisions atomically. It does not re-extract measurement values from
session captures.
| Option | Meaning |
|---|---|
--app-id <id> | Rebuild one app. Omit it to rebuild every app that has stored measurements and a registered codebase. |
--app-version <version> | Rebuild only this version of the selected app. Requires --app-id; earlier measurements remain available as baselines. |
--trend <id> | Rebuild only one current trend rule. |
--workspace <path> | Override the selected app’s registered codebase. Requires --app-id. |
--dry-run | Calculate and report the rows that would be replaced without changing the history database. |
session
Inspection
Inspection options
| Option | Applies to | Meaning |
|---|---|---|
--app-id <id> | session list | Return sessions for one application ID. |
--connected | session list | Return only currently connected sessions. |
--platform <key> | session list | Require ios, android, macos, windows, or other. Repeat the flag to accept multiple platforms. |
--device-form-factor <value> | session list | Require an exact device form factor. Repeat the flag for multiple values; --form-factor is an alias. |
--os-name <value> | session list | Require an exact operating-system name. Repeat the flag for multiple values. |
--os-version <value> | session list | Require an exact operating-system version. Repeat the flag for multiple values. |
--device-type <value> | session list | Require an exact device type. Repeat the flag for multiple values. |
--physical | session list | Require a physical device. |
--virtual | session list | Require a virtual target. |
--emulator | session list | Require an emulator. --simulator is accepted as an equivalent filter. |
--tag <tag> | session list | Require a session tag. Repeat the flag to require multiple tags. |
--from <utc> | session list | Keep sessions updated at or after this ISO-8601 timestamp. |
--to <utc> | session list | Keep sessions created at or before this ISO-8601 timestamp. |
--has-logs | session list | Require retained log evidence. |
--has-telemetry | session list | Require retained telemetry evidence. |
--search <text> | session list | Search session identity, app, device, OS, and tags. --contains is an alias. |
--limit <count> | session list | Return at most 1–10000 sessions. The default is 200. |
--limit <count> | session logs | Return the newest 1–10000 matching logs. The default is 200. |
--contains <text> | session logs | Keep logs whose message contains this text, ignoring case. --query is an alias. |
--stream <id> | session logs | Keep logs from this exact stream. Repeat the flag for multiple streams. |
--tag <tag> | session logs | Keep logs with this exact tag. Repeat the flag for multiple tags. |
--source <source> | session logs | Keep logs from this exact source. Repeat the flag for multiple sources. |
--start <utc> | session logs | Set the inclusive beginning of the ISO-8601 timestamp range. |
--end <utc> | session logs | Set the inclusive end of the ISO-8601 timestamp range. |
--priority <level> | session logs | Keep an exact log priority. |
--minimum-priority <level> | session logs | Keep this priority and higher, using verbose, debug, information, warning, error, or fatal. --minimum-severity and --severity are aliases. |
--id <request-id> | session network | Keep one exact request identifier. |
--method <method> | session network | Keep an exact HTTP method. Repeat the flag for multiple methods. |
--status <code|class> | session network | Keep an exact status, a 2xx–5xx class, or failed/error requests. Repeatable. |
--host <host> | session network | Keep requests whose hostname contains this value. |
--start <utc> | session network | Set the inclusive beginning of the request start-time range. |
--end <utc> | session network | Set the inclusive end of the request start-time range. |
--contains <text> | session network | Search URL, method, and error message. --query is an alias. |
--failed | session network | Keep transport errors and HTTP 4xx/5xx responses. |
--limit <count> | session network | Return the newest 1–10000 matching requests. The default is 200. |
--limit <count> | session metrics | Return the newest 1–50000 samples. The default is 500. |
--channel <id> | session metrics | Keep samples and channel metadata for numeric channel ID 0–255. |
--limit <count> | session images, touches, trees, artifacts, annotations, analyses | Return the newest 1–10000 collection items. The default is 200. |
Telemetry analysis options
| Option | Meaning |
|---|---|
--kind <all|fps-drop|memory-spike> | Select the detectors to run. The default is all; fps and memory are accepted aliases for the two individual detectors. |
--memory-min-percent <percent> | Require a relative memory increase from 1 to 100 percent. The default is 15. |
--memory-min-mb <megabytes> | Require an absolute memory increase from 1 to 4096 MB. The default is 128. |
--max-events <count> | Return at most 1–10000 findings per detector. The default is 12. |
--fail-on-detection | Return exit code 11 when the selected detectors find any event. |
Editing and evidence export
Editing and export options
| Option | Applies to | Meaning |
|---|---|---|
--annotation <id> | session extract | Use the bounds of this annotation. It cannot be combined with --start or --end. |
--start <utc> | session extract, session trim, session annotation upsert | Set the required inclusive start as an ISO-8601 timestamp when explicit bounds are used. |
--end <utc> | session extract, session trim, session annotation upsert | Set the end timestamp. It is required for extraction and trimming and optional for annotations. |
--name <name> | session extract | Set the extracted session name. |
--mode <cut|keep> | session trim | Remove the selected interval or retain only that interval. remove/cut-selection and keep-only/keep-selection are accepted aliases. |
--file <annotation.json> | session annotation upsert | Read the complete annotation from JSON instead of individual annotation flags. |
--annotation-id <id> | session annotation upsert | Set the annotation ID. A new compact GUID is generated by default. |
--label <label> | session annotation upsert | Set the required annotation label when --file is not used. |
--notes <text> | session annotation upsert | Set optional annotation notes. |
--source <source> | session annotation upsert | Set the annotation source. The default is cli. |
--frame-id <id> | session screenshot export | Export a specific frame. Without a frame or timestamp, the newest screenshot is exported. |
--timestamp <utc> | session screenshot export | Export the screenshot nearest this ISO-8601 timestamp. |
--snapshot-id <id> | session artifact export | Select an artifact snapshot. Without it, the newest matching snapshot is used. |
--path <artifact-path> | session artifact export | Select the required artifact path within the snapshot. |
--output <path> | session screenshot export, session artifact export | Write the exported evidence to this required local path. |
--force | session screenshot export, session artifact export | Replace an existing output file. --overwrite is an alias. |
Management and cache
Metadata options
| Option | Meaning |
|---|---|
--name <name> | Set the session’s display name. |
--notes <text> | Set notes, replacing the current value. |
--clear-notes | Remove all notes. |
--tag <tag> | Replace the current tags with the supplied values. Repeat the flag for multiple tags. |
--clear-tags | Remove every tag. |
--pin | Protect the session from cache cleanup. It cannot be combined with --unpin. |
--unpin | Remove cache-cleanup protection. It cannot be combined with --pin. |
Cache options
| Option | Applies to | Meaning |
|---|---|---|
--compaction-age-days <days> | session cache compact | Compact inactive sessions at least 1–365 days old. The default is 30. |
--retention-days <days> | session cache status, plan, prune | Select sessions older than 1–365 days. The default is 90. |
--max-cache <size> | session cache status, plan, prune | Set the target cache limit from 256MiB to 1TiB, using a value such as 5GB or 5GiB. The default is 5GiB. |
--max-cache-size <size> | session cache status, plan, prune | Alias for --max-cache. |
--apply | session cache prune | Delete the sessions in the plan. Without this flag, prune is a dry run. |
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 --jsonCompaction 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
| Option | Applies to | Meaning |
|---|---|---|
--port <port> | session serve | Bind the replay server to this port. The default, 0, selects an available port. |
--open | session serve | Open the replay in the default browser after the server starts. |
Cloud sharing options
| Option | Applies to | Meaning |
|---|---|---|
--team-id <uuid> | session share, session url | Select an organisation by non-empty UUID. |
--team-name <name> | session share | Select an organisation by name when an ID is not supplied. |
--public | session share | Shorthand for public replay access. It cannot be combined with a non-public --access value. |
--access <team|authenticated|public> | session share | Set the replay access level. The default is team. |
--include-native-logs | session share | Include native device logs in the upload. They are excluded by default. |
--sanitizer <module.ts> | session share | Run named sanitization functions from this local TypeScript module in addition to the built-in policy. |
--policy <module.ts> | session share | Alias for --sanitizer. |
--no-sanitize | session share | Upload raw capture data instead of applying the default sanitization policy. |
--include-archived | session url | Allow an archived share when resolving the newest replay URL. |
Archive options
| Option | Applies to | Meaning |
|---|---|---|
--exclude-native-logs | session export, session sanitize | Omit native device logs from the archive. |
--sanitize | session export | Apply the built-in PII policy while exporting. |
--sanitizer <module.ts> | session export, session sanitize | Run named sanitization functions from this local TypeScript module. The file must end in .ts. |
--policy <module.ts> | session export, session sanitize | Alias for --sanitizer. |
--password-env <NAME> | session import | Read an archive password from the named environment variable. |
Cloud sharing and session sanitize apply the built-in policy by default. It
redacts structured PII, masks screenshots whose raster content cannot be proven
safe, excludes artifacts, and records its work in sanitization/report.json.
cloud
Registers cloud App IDs and administers uploaded trends, test-run summaries,
sessions, attachments, and hosted analysis. Administration uses the current
auth session. Headless uploads can instead use an app-scoped runner
credential through ANSIGHT_RUNNER_API_KEY, ANSIGHT_TEAM_ID, and
ANSIGHT_APP_ID. 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
| Option | Applies to | Meaning |
|---|---|---|
--search <text> | cloud team list, cloud session list | Search organisation or session results. |
--team-id <uuid> | Cloud app, trend, test, key, and session commands | Select or restrict the organisation. ANSIGHT_TEAM_ID supplies the headless default. |
--include-archived | cloud session list | Include archived sessions. |
--limit <count> | cloud session list | Return from 1 to 1000 sessions. The default is 200. |
--limit <count> | cloud trend upload|sync, cloud test sync | Limit the local history records considered for upload. |
--name <name> | cloud app register | Set the portal display name; the App ID is used by default. |
--platform <name> | cloud app register | Add optional platform context. |
--app-id <id> | Cloud test imports/uploads and runner-key issue | Supply the registered App ID. ANSIGHT_APP_ID supplies the headless default. |
--app-version <value> | Cloud test uploads | Add the tested app version. |
--branch <name>, --commit <sha> | Cloud test uploads | Add source-control context without uploading source or prompts. |
--run-id <id> | cloud test import | Set a stable CI execution prefix. Otherwise the JUnit file digest is used. |
--session-id <id> | cloud test import | Link imported results to the newest uploaded Ansight session with this source ID. |
--scope <scope> | cloud key issue | Grant sessions:write, trends:write, or tests:write; repeat as needed. All three are granted when omitted. |
--expires-at <timestamp> | cloud key issue | Set an optional future ISO-8601 expiry. |
--output <path> | cloud session download | Set the archive destination. The default is ansight-cloud-<session-id>.zip in the current directory. |
--output <path> | cloud attachment download | Set the required local attachment destination. |
--name <name> | cloud attachment upload | Set the attachment name. The local filename is used by default. |
--notes <text> | cloud attachment upload | Add attachment notes. |
--force | Cloud downloads | Replace an existing destination file. --overwrite is an alias. |
Hosted analysis options
| Option | Meaning |
|---|---|
--kind <analysis|mermaid|performance> | Select the analysis result kind. The default is analysis. |
--mode <fast|thorough> | Select the analysis depth. The default is fast. |
--provider <openai|anthropic|gemini> | Select the hosted provider. The default is openai. |
--model <id> | Override the provider’s default model. |
--source-part <part> | Include logs, screenshots, visual_tree, metrics, annotations, or artifacts. Repeat the flag for multiple parts. With no source flags, all six are included. |
--slice-start-ms <value> | Set a non-negative inclusive start offset in milliseconds. |
--slice-end-ms <value> | Set a non-negative inclusive end offset in milliseconds. |
--instructions <text> | Add instructions for the hosted analysis. |
licenses
| Command | Purpose |
|---|---|
licenses list | Show bundled and optional external software attribution. |
licenses export <output.md|output.json> | Export Markdown or versioned JSON. |
| Option | Applies to | Meaning |
|---|---|---|
--format <markdown|json> | licenses export | Override the format inferred from the .md, .markdown, or .json output extension. |
--force | licenses export | Replace an existing output file. |
Exit codes
| Code | Meaning |
|---|---|
0 | Success. |
1 | General failure. |
2 | Invalid command usage. |
3 | Configuration is invalid or incomplete. |
4 | Required Ansight host or app session is unavailable. |
5 | Target capability is unavailable. |
10 | A test or required assertion failed. |
11 | Telemetry findings were detected with --fail-on-detection. |
130 | Operation cancelled. |