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). The desktop app is optional.

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.

Setup

1. Install Bun (for the runner)

   The runner is Bun-only. CI and headless terminals need Bun on PATH:

   curl -fsSL https://bun.sh/install | bash
   
2. Install the CLI

   npm / CI (recommended for pipelines):

   npm install -g @yoqa/cli
   # or one-off
   npx @yoqa/cli health
   

   Desktop: Settings → CLI & Agents → Install CLI. Links yoqa into ~/.local/bin.

3. 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):

   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.

4. Verify

   yoqa health
   yoqa status
   yoqa doctor
   yoqa devices ios
   

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.

- 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 (yoqa report, setup-yoqa / yoqa-report composite actions).

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

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

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

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.

Actions

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

# 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 "[e-mail]"

# 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 "[e-mail]"

# 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).

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

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.

CLI for agents

Skill + inspect → act → verify

How the agent works

Perception loop for autonomous runs