Inspect and automate your app from the terminal

Investigate app behavior and run repeatable checks from the tools you already use. The Ansight CLI lets you and your coding agent discover a connected app, inspect its UI and internal state, review recorded evidence, and run workspace tests and tasks. Structured output makes those results available to scripts and other automation.

The CLI includes a local host that connects to your app and records sessions. With the latest Ansight SDK on supported mobile devices, those sessions retain available Apple Pencil and Android stylus pressure, angles, hover, and finer move samples alongside ordinary touches. You can review the same sessions and evidence in the browser-based local player.

The CLI, local host and development harness are source available under PolyForm Shield 1.0.0. Local capture, inspection, automation, tests and replay require no account, subscription or online entitlement verification. Cloud logout and expired cloud subscriptions do not stop local tools.

Sign in with ansight account login when using cloud sharing, build/workspace uploads or remote job delegation. Scoped runner keys are also available for their supported cloud operations. Cloud services enforce organisation permissions, scopes, storage limits and hosted-compute allowances independently.

Use ansight account access --json to verify cloud sign-in, or ansight account open to manage cloud services. Cloud access denials return exit code 6; local tools remain available.

Start with the built-in help

Use the built-in help for the version you installed:

ansight help

For a command family or a version check, use:

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

Start the host in one terminal. --open also opens the local player in your browser:

ansight host run --open

Keep this terminal open while you work. The host receives app connections and records sessions; commands in another terminal use that running host.

Launch your SDK-enabled development app, then check the host and list connected sessions from a second terminal. If the app does not appear, follow Getting Started.

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

Copy the connected session ID into <session-id>. Inspect the current UI tree, then find a control by its visible text and role. This example looks for a Sign in button; use a control that exists on your app’s current screen:

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

If the result includes an automation ID for the intended button, use it to tap that control in the same session:

ansight ui tap --session <session-id> --automation-id <automation-id>

Run ui snapshot again to check the resulting UI. See UI commands for other selectors and assertions.

The host accepts commands through the CLI, not an MCP listener. Agents and scripts use the same CLI commands and JSON output.

For a temporary host that lasts for one terminal session, use ansight serve --open instead.

When you are finished

Stop the host with Ctrl+C in its terminal. On macOS and Linux, you can also stop it from the second terminal:

ansight host stop

Stop it only after finishing live inspection and capture.

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. Results use a versioned JSON format. Check the exit status and the command’s structured failure details; for example, UI commands report succeeded: false with a message when an operation fails.

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 mandatory, pseudonymous engagement analytics after successful, meaningful local use outside CI: daily active use, any CLI command at most once per 24 hours without its name, and an hourly engaged event after two actions. It separately records install and update lifecycle events. Signed-in users can opt in to detailed analytics containing 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 enable|disable.

Related docs

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