CLI

The Ansight CLI is the headless host and automation client. It exposes the same local app sessions, captures, device targets, workspace definitions, and repository modules used by the local host player in a terminal-friendly form.

An Ansight account with a current trial, paid, or explicit organisation product grant is required for all CLI product features, including local and agent-driven workflows. New accounts receive a 14-day trial. When access expires, running features stop and new product commands are blocked. Help, authentication, account management, configuration, diagnostics, updates, legal notices, and host status/stop remain available for setup and recovery.

Run ansight account access --json to check access and its expiry, or ansight account open to manage your account. Verification requires a connection; running commands recheck every 15 seconds and never continue beyond grant expiry or the one-minute verification deadline. Access denials return exit code 6. After renewing access, restart the host. Scoped runner keys remain available for their supported cloud uploads and do not unlock local product features.

Start with the built-in help

The executable owns the authoritative help for the version you installed:

ansight help
ansight <command> help
ansight <command> --help
ansight version
ansight update check

Open the CLI Command Reference for every current command, subcommand, alias, global option, and exit code on one page.

Run ansight doctor after installation, then use System Requirements and Dependencies to interpret the required and feature-specific checks.

Manage the installed release with Update the CLI, or remove the installer-managed CLI safely with Uninstall the CLI.

Run a resident host

Most workflows work best with one long-lived host in the first terminal:

ansight host run --open

The resident host owns SDK discovery, session capture, the loopback explorer, connected app tools, repository triggers, and the data-directory lock. Commands issued from another terminal reuse it through a current-user-only control pipe.

ansight host status --json
ansight session list --connected --json
ansight host stop

Inspect and drive the connected app directly through the semantic CLI:

ansight ui snapshot --session <session-id> --json
ansight ui find --text "Sign in" --role button --json
ansight ui tap --automation-id SignInButton

The resident host does not expose an MCP listener. Automation clients use the same versioned CLI output as scripts and human operators.

Use ansight serve --open when you want a transient host and browser explorer for one terminal session.

Run without simulator or emulator windows

CLI commands show simulator or emulator windows by default when launching a virtual target. Add --headless for windowless operation:

ansight device start ios <simulator-id> --headless
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
ansight test run . onboarding.smoke --headless --json

The same flag works with replay, test suites, and .NET/iOS/Android profiling startup. It also applies to device starts requested by tools during command execution. On iOS it skips opening Simulator.app; newly started Android emulators use -no-window. Existing windows are not closed, running emulators are not restarted, and physical devices are unaffected.

--headless is independent of --json, --silent, and the host’s --open browser option. Scripts and CI must opt in explicitly. See Headless device launches for the full command coverage.

Close the app after execution

app execute leaves the app open by default. Add --close-app-on-completion to close only the target app process after success, failure, or cancellation:

ansight app execute <session-id> --prompt "Verify the home screen" --close-app-on-completion

This works for both existing sessions and launched apps, including one app instance per device in multi-device runs. It does not shut down the device, close its window, or stop the host. Combine it with --headless independently when you also want windowless startup. Cleanup failures are reported as warnings without replacing the execution outcome; see the app command reference.

Machine-readable output

Add --json to commands used by scripts. Successful output uses versioned JSON contracts; failures use machine-readable error codes when JSON output is enabled.

ansight device list --json
ansight session show <session-id> --json
ansight test run . onboarding.smoke --json

--silent suppresses stdout and stderr, including JSON. --verbose adds host, SDK, telemetry, and app-event diagnostics where the command supports them.

Find identifiers

CLI commands use stable IDs rather than display labels:

Data and security

CLI state is local by default. Use ansight doctor or ansight host status --json to find the active data directory. Account and test secrets use the OS credential vault or an explicitly configured encrypted file store. Workspace tests can also resolve a declared secret alias directly from an environment variable with the same name. Values are never accepted as ordinary command-line arguments.

See Data, Privacy, and Analysis for session archives, structured JSON extraction, raw capture folders, and SQLite Trends history.

The CLI records one pseudonymous daily-active event after a successful, meaningful command outside CI. It separately records install and update lifecycle events. Optional detailed analytics contains normalized command categories and outcomes, never raw arguments, paths, App IDs, session IDs, prompts, logs, or captured content. Inspect or change detailed tracking with ansight analytics status and ansight analytics detailed disable.

Related docs

• System Requirements and Dependencies
• CLI Command Reference
• Semantic UI commands
• Update the CLI
• Uninstall the CLI
• Workspace
• Tests
• Tasks
• Triggers
• Skills