> ## Documentation Index
> Fetch the complete documentation index at: https://yoqa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Drive Yoqa from your terminal — devices, screen, actions, catalog, and runs.

The `yoqa` CLI talks to the **local runner**. If nothing is listening on `http://127.0.0.1:7420`, the CLI starts `@yoqa/runner` for you (requires [Bun](https://bun.sh)). The desktop app is optional.

<Note>
  Install via **npm** (`npm i -g @yoqa/cli` / `npx @yoqa/cli`) for terminals and CI, or from the desktop app: **Settings → CLI & Agents → Install CLI**. Restart the terminal after a desktop install. For coding agents, also install the skill — see [CLI for agents](/guide/cli-for-agents).
</Note>

## Setup

<Steps>
  <Step title="Install Bun (for the runner)">
    The runner is Bun-only. CI and headless terminals need Bun on `PATH`:

    ```bash theme={null}
    curl -fsSL https://bun.sh/install | bash
    ```
  </Step>

  <Step title="Install the CLI">
    **npm / CI (recommended for pipelines):**

    ```bash theme={null}
    npm install -g @yoqa/cli
    # or one-off
    npx @yoqa/cli health
    ```

    **Desktop:** Settings → **CLI & Agents** → **Install CLI**. Links `yoqa` into `~/.local/bin`.
  </Step>

  <Step title="Start the runner (optional)">
    `yoqa health` and other commands auto-start the runner. To run it in the foreground (typical for a dedicated CI service step):

    ```bash theme={null}
    yoqa serve
    ```

    From a monorepo checkout you can still use `bun run runner`. The desktop app also starts a sidecar on the same port. Disable auto-start with `YOQA_NO_AUTOSTART=1`.
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    yoqa health
    yoqa status
    yoqa doctor
    yoqa devices ios
    ```
  </Step>
</Steps>

## CI / CD

Install Bun and `@yoqa/cli`. The first `yoqa` command starts the runner; later steps reuse it. Host **Node/npm** must be on `PATH` so managed Appium can install under `~/.yoqa/runtime`.

```yaml theme={null}
- uses: oven-sh/setup-bun@v2
  with:
    bun-version: "1.2.23"
- uses: actions/setup-node@v4
  with:
    node-version: "22"
- run: npm install -g @yoqa/cli
- run: yoqa health
- run: yoqa runtime ensure
```

This repo also ships a full device smoke against an Expo fixture (builds CLI from source, iOS Simulator on `macos-26` + Android Emulator on Ubuntu + KVM, no AI provider): see the **Demo Expo E2E** workflow and `examples/expo-demo`. Copy that YAML if you want `yoqa assert` / `yoqa action --label` in your own app repo. Each action writes a screenshot under `artifacts/screenshots`.

For catalog runs plus the same HTML report as desktop **Export HTML**, see [GitHub Actions](/docs/github-actions) (`yoqa report`, `setup-yoqa` / `yoqa-report` composite actions).

```bash theme={null}
yoqa serve                 # foreground (use `yoqa serve &` or a service step)
yoqa serve --stop          # SIGTERM a runner this CLI started (~/.yoqa/runner.pid)
```

Override the runner URL with `YOQA_RUNNER_HOST` / `YOQA_RUNNER_PORT` / `YOQA_RUNNER_URL`. Pin a binary with `YOQA_RUNNER_BIN`.

Device runs need a simulator or emulator and Appium drivers (`yoqa doctor --fix` / `yoqa runtime ensure`). Description grounding and agent runs also need provider secrets. GitHub-hosted iOS needs `macos-*` + Xcode. This is not a cloud device farm — cache `~/.yoqa/runtime` between jobs to skip reinstalling Appium.

## Doctor & servers

```bash theme={null}
yoqa doctor                                  # color bullets: green pass / red fail / yellow warn
yoqa doctor --fix                              # apply safe repairs only
yoqa doctor --json

yoqa servers                                 # list Appium / runner / device session
yoqa servers stop-all                        # stop Appium + disconnect session (not the runner)
yoqa servers stop <id>
yoqa servers restart <id>
```

`yoqa runtime status` / `ensure` remain the thin install-readiness commands. Prefer `yoqa doctor` when something is broken or foreign Appium processes are stuck.

In the desktop app: **Servers** button next to Play, and **Settings → Diagnostics**.

## Devices

```bash theme={null}
yoqa devices ios                             # list devices & simulators (--all for every simulator)
yoqa devices android                         # list devices & emulators (--all for every emulator)
yoqa devices connect <device-id>             # open a session (full id from the list)
yoqa devices active                          # show the connected device
yoqa devices disconnect
```

## Inspect the screen

```bash theme={null}
yoqa screen                                  # cleaned element tree + relative coords (0–1000)
yoqa screen --full                           # raw Appium accessibility tree
yoqa screenshot ./shot.png                   # save a PNG
```

Prefer `yoqa screen` in agent loops — fewer tokens than a screenshot or `--full`. Details: [CLI for agents](/guide/cli-for-agents).

## Actions

Prefer **description grounding** (`-d` / `--description`) when an [AI provider](/docs/providers) is configured. Fall back to relative coordinates (`0–1000`) from `yoqa screen`.

```bash theme={null}
# By description (recommended)
yoqa action tap -d "Login button"
yoqa action tap -d "Login button" --double
yoqa action tap -d "Login button" --duration 2
yoqa action swipe -d "photo carousel, swipe left"
yoqa action drag -d "card onto the drop zone"
yoqa action input -d "email field" --text "hi@yoqa.ai"

# By coordinates (fallback)
yoqa action tap --x 500 --y 320
yoqa action swipe --x1 500 --y1 800 --x2 500 --y2 200
yoqa action drag --x1 300 --y1 500 --x2 700 --y2 500
yoqa action input --x 500 --y 640 --text "hi@yoqa.ai"

# App & system
yoqa action open-url --url "myapp://profile"
yoqa action alert --action accept
yoqa action alert --action dismiss
yoqa action activate-app --bundle-id com.example.app
yoqa action terminate-app --bundle-id com.example.app
yoqa action restart-app --bundle-id com.example.app
yoqa action background-app
```

## Test management

Catalog commands take the app **prefix** as `APP` (`yoqa apps list`).

```bash theme={null}
yoqa apps list
yoqa apps get APP
yoqa apps update APP '{"name": "...", "app_context": "..."}'

yoqa cases list APP
yoqa cases list APP --tag smoke
yoqa cases get APP 42
yoqa cases create APP '{"title": "Login", "tags": ["smoke"], "flows": [{"instructions": "...", "result": "..."}]}'
yoqa cases update APP 42 '{"title": "New title"}'
yoqa cases delete APP 42

yoqa flows list APP
yoqa flows create APP '{"name": "Onboarding", "instructions": "...", "result": "..."}'
yoqa tags APP
```

## Builds & runs

```bash theme={null}
yoqa builds list APP
yoqa builds create APP --path ./MyApp.app

yoqa runs list APP
yoqa runs get <run-id>
yoqa runs create APP --cases 1,2 --wait   # start cases; --wait blocks until finished
yoqa runs wait <run-id>
yoqa report <run-id>                      # HTML / Markdown (same as desktop Export)
yoqa runs report <run-id>                 # alias of yoqa report
yoqa runs delete <run-id>
```

Agent runs require a configured provider. Cloud credits are not required for local Phase 1.

<CardGroup cols={2}>
  <Card title="CLI for agents" icon="robot" href="/guide/cli-for-agents">
    Skill + inspect → act → verify
  </Card>

  <Card title="How the agent works" icon="brain" href="/guide/how-yoqa-agent-works">
    Perception loop for autonomous runs
  </Card>
</CardGroup>