---
name: ansight-cli-setup
description: Use this skill when preparing a developer workstation or agent to use the Ansight CLI. Verify the ansight executable, inspect capabilities, start or reuse the resident host, and confirm app and session discovery with structured CLI output.
---

# Ansight CLI Setup Skill

Use this skill when a user wants an agent or developer workstation prepared for Ansight without modifying an app SDK integration.

## Goal

Make the `ansight` executable the canonical local interface, verify its dependencies, start or reuse its resident host, and prove that structured CLI commands can discover apps and sessions.

## Required Constraints

- Use `ansight` commands directly and do not add a separate client bridge or daemon configuration.
- Prefer `--json` whenever command output will be consumed by an agent or script.
- Preserve any running host and its selected data directory.
- Do not install or modify an app SDK unless the user separately requests it.
- Do not start a second host against the same data directory.
- Keep the resident host on the developer machine and do not expose its local ports publicly.

## Workflow

1. Confirm the executable and command surface:

   ```sh
   ansight help
   ansight version --json
   ansight update check --json
   ansight doctor --json
   ```

2. Check for a resident host:

   ```sh
   ansight host status --json
   ```

3. If no host is running, start one in a persistent terminal:

   ```sh
   ansight host run
   ```

   Use `ansight host run --open` when the user also wants the local browser explorer. Use the same `--data-dir` on status and management commands when a custom data directory is required.

4. From another terminal, verify the host and discovery surface:

   ```sh
   ansight host status --json
   ansight app list --json
   ansight session list --connected --json
   ```

5. A simulator, emulator, Mac Catalyst app, or desktop app registers
   automatically with the local host. To enroll a physical device, issue a
   generic one-use terminal QR and scan it from the app's developer-only Ansight
   surface:

   ```sh
   ansight pairing issue --qr
   ```

   Do not require app registration before this first connection. Once the SDK
   supplies its real App ID, optionally link it to a repository with
   `ansight app register <app-id> --name <name> --codebase <path>`.

6. For agent workflows, prove the machine-readable inspection path with the selected session:

   ```sh
   ansight session show <session-id> --json
   ansight app tools <session-id> --json
   ```

7. Report the executable used, doctor result, host state, data directory, discovered app/session identifiers, and any manual pairing or persistent-terminal step that remains.

## Troubleshooting

- Run `ansight doctor --json` first and use its required/optional capability results instead of guessing at missing dependencies.
- If a command cannot find the resident host, compare the `--data-dir` value and current OS user.
- If no live session appears, confirm the host is running and the app is a development build. Host-local targets should auto-register; a physical device should have scanned a current `ansight pairing issue --qr` invite.
- If multiple sessions match, select one explicitly; never guess.
- Use `ansight help` and `ansight <command> help` as the authoritative syntax for the installed version.

## Done Criteria

- `ansight version --json` reports the expected version string, daily build
  number, and public or preview channel, and any available update is reported.
- `ansight doctor --json` completes and required capabilities are understood.
- Exactly one intended resident host is running or the user has the explicit command needed to start it.
- `ansight host status --json` succeeds.
- App and connected-session discovery has been checked through the CLI.
- No separate client bridge or legacy daemon configuration was added.