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

# Commands

> Complete reference for all Grantiva CLI commands

All commands support `--json` for machine-readable output.

## `grantiva build`

Build the app for a simulator using xcodebuild.

```bash theme={null}
grantiva build [--scheme SCHEME] [--simulator SIMULATOR]
               [--app-file PATH] [--no-build] [--json]
```

| Flag          | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| `--scheme`    | Xcode scheme to build                                             |
| `--simulator` | Simulator name (e.g., "iPhone 16")                                |
| `--app-file`  | Path to a pre-built `.app` bundle or `.ipa` archive (skips build) |
| `--no-build`  | No-op pass-through (exits immediately)                            |

Boots the simulator, runs `xcodebuild`, and prints a build summary. Exits `1` on build failure.

***

## `grantiva install`

Build, install, and launch the app on a simulator in one step.

```bash theme={null}
grantiva install [--scheme SCHEME] [--simulator SIMULATOR]
                 [--bundle-id ID] [--app-file PATH] [--no-build] [--json]
```

| Flag          | Description                                                                |
| ------------- | -------------------------------------------------------------------------- |
| `--scheme`    | Xcode scheme to build                                                      |
| `--simulator` | Simulator name (e.g., "iPhone 16")                                         |
| `--bundle-id` | App bundle identifier (derived from `Info.plist` if using `--app-file`)    |
| `--app-file`  | Path to a pre-built `.app` bundle or `.ipa` archive (skips build)          |
| `--no-build`  | Skip building and installing — assumes the app is already on the simulator |

**What it does:**

1. Boots the simulator
2. Builds via `xcodebuild` (unless `--app-file` or `--no-build`)
3. Installs via `simctl install`
4. Launches via `simctl launch`

This is the same build/install sequence used by `grantiva ci run`, useful for iterating locally without capturing screenshots.

***

## `grantiva run`

Run Maestro flows against a simulator. Reports step pass/fail for each flow and captures a screenshot on failure. Supports agent-native workflows via `--keep-alive` and `--logs`.

```bash theme={null}
grantiva run [--scheme SCHEME] [--simulator SIMULATOR] [--bundle-id ID]
             [--app-file PATH] [--no-build] [--flow PATH]
             [--keep-alive] [--logs] [--logs-predicate EXPR] [--logs-level LEVEL]
             [--json]
```

| Flag               | Description                                                                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `--scheme`         | Xcode scheme to build                                                                                                                           |
| `--simulator`      | Simulator name (e.g., "iPhone 16")                                                                                                              |
| `--bundle-id`      | App bundle identifier                                                                                                                           |
| `--app-file`       | Path to a pre-built `.app` bundle or `.ipa` archive (skips build)                                                                               |
| `--no-build`       | Skip building and installing — assume the app is already on the simulator                                                                       |
| `--flow`           | Run a single flow YAML file instead of all configured flows                                                                                     |
| `--keep-alive`     | Hold the GrantivaAgent session open after flows complete so `grantiva hierarchy` can inspect UI state without relaunching. Release with Ctrl-C. |
| `--logs`           | Stream simulator app logs into this terminal, prefixed with `[log]`. Predicate auto-derived from the app's bundle ID.                           |
| `--logs-predicate` | Custom `NSPredicate` for `simctl log stream --predicate`. Implies `--logs`.                                                                     |
| `--logs-level`     | Log level: `default` (warnings/errors/default), `info`, or `debug`.                                                                             |

**What it does:**

1. Boots the simulator.
2. Builds, installs the app (unless `--app-file` or `--no-build`).
3. Starts GrantivaAgent on the simulator. The flow drives the app — no pre-launch.
4. If `--logs` is set, tees `xcrun simctl spawn log stream` output inline with the flow output.
5. Runs all configured flows (or the single `--flow` file) and reports step pass/fail.
6. On failure: captures a screenshot of the simulator's current state.
7. If `--keep-alive`, writes a session file to `~/.grantiva/runner/sessions/<udid>.json` and blocks waiting for Ctrl-C so external tools can inspect the final state. Otherwise the GrantivaAgent session is torn down.
8. Saves screenshots to `.grantiva/captures/` (not compared against any baseline).

No authentication required. Useful for functional/smoke testing locally, CI pipelines that don't need visual regression, and agent-driven test authoring / selector repair.

Exit code `0` if all steps pass, `1` if any fail.

***

## `grantiva hierarchy`

Dump the current UI hierarchy of a running simulator via an active keep-alive GrantivaAgent session. Read-only — no app relaunch, no state loss.

```bash theme={null}
grantiva hierarchy [--udid UDID] [--format xml|json] [--json]
```

| Flag       | Description                                                                        |
| ---------- | ---------------------------------------------------------------------------------- |
| `--udid`   | Target a specific simulator's session (defaults to the newest keep-alive session). |
| `--format` | Output format: `xml` (default, unwrapped) or `json`.                               |

**Requires** `grantiva run --keep-alive` to be running in another terminal (or a backgrounded process). If no keep-alive session is live, `grantiva hierarchy` fails with an actionable error rather than spinning up a fresh session (which would relaunch the app and destroy the state you wanted to inspect).

**Typical agent workflow:**

```bash theme={null}
# Terminal 1 (or CI background):
grantiva run --keep-alive --logs --flow flows/onboarding.yaml

# Terminal 2:
grantiva hierarchy > state.xml
```

The output is the full XCUI accessibility tree of the currently foregrounded view — element types, labels, identifiers, bounds, traits. Feed it to an agent to synthesize selectors, diagnose failures, or author new flows.

***

## `grantiva ci run`

Run the full visual regression pipeline: build, capture, compare, upload.

```bash theme={null}
grantiva ci run [--scheme SCHEME] [--simulator SIMULATOR] [--bundle-id ID]
                [--app-file PATH] [--no-build] [--json]
```

| Flag          | Description                                                               |
| ------------- | ------------------------------------------------------------------------- |
| `--scheme`    | Xcode scheme to build                                                     |
| `--simulator` | Simulator name (e.g., "iPhone 16")                                        |
| `--bundle-id` | App bundle identifier                                                     |
| `--app-file`  | Path to a pre-built `.app` bundle or `.ipa` archive (skips build)         |
| `--no-build`  | Skip building and installing — assume the app is already on the simulator |

**What it does:**

1. Boots simulator
2. Builds the app (unless `--app-file` or `--no-build` is used)
3. Installs the app and starts GrantivaAgent
4. Captures screenshots for all configured screens
5. Compares against baselines (pixel + perceptual)
6. Uploads results to the Grantiva dashboard
7. Posts a GitHub Check Run with results

When `--app-file` is provided, the binary is validated to be a simulator build and the bundle ID is derived from its `Info.plist` if not specified. `.ipa` archives are automatically extracted.

Exit code `0` if all screens pass, `1` if any fail.

***

## `grantiva diff capture`

Capture screenshots without comparing.

```bash theme={null}
grantiva diff capture [--scheme SCHEME] [--simulator SIMULATOR]
                      [--bundle-id ID] [--app-file PATH] [--no-build] [--json]
```

| Flag         | Description                                                     |
| ------------ | --------------------------------------------------------------- |
| `--app-file` | Use a pre-built `.app` or `.ipa` instead of building            |
| `--no-build` | Skip building and installing (app must already be on simulator) |

Saves `.png` files to `.grantiva/captures/`.

***

## `grantiva diff compare`

Compare captures against baselines.

```bash theme={null}
grantiva diff compare [--capture] [--app-file PATH] [--no-build]
                      [--scheme SCHEME] [--simulator SIMULATOR]
                      [--bundle-id ID] [--json]
```

| Flag         | Description                                                  |
| ------------ | ------------------------------------------------------------ |
| `--capture`  | Capture fresh screenshots before comparing                   |
| `--app-file` | Use a pre-built binary when capturing (requires `--capture`) |
| `--no-build` | Skip build/install when capturing (requires `--capture`)     |

Baselines are loaded from the Grantiva server (if authenticated) or `.grantiva/baselines/` locally. Diff images for failures are saved to `.grantiva/captures/diffs/`.

***

## `grantiva diff approve`

Promote current captures as new baselines.

```bash theme={null}
grantiva diff approve [SCREEN_NAME ...] [--json]
```

Pass specific screen names to approve selectively, or omit to approve all.

***

## `grantiva auth login`

Authenticate with Grantiva.

```bash theme={null}
grantiva auth login [--api-key KEY] [--base-url URL] [--json]
```

Without `--api-key`, opens a browser login flow. With `--api-key`, validates the key directly. Credentials saved to `~/.grantiva/auth.json`.

***

## `grantiva auth status`

Show current authentication status.

```bash theme={null}
grantiva auth status [--json]
```

Checks `GRANTIVA_API_KEY` env var first, then `~/.grantiva/auth.json`.

***

## `grantiva auth logout`

Remove stored credentials.

```bash theme={null}
grantiva auth logout [--json]
```

***

## `grantiva doctor`

Check environment and dependencies.

```bash theme={null}
grantiva doctor [--json]
```

Verifies macOS version, Xcode, Swift, simulator availability, and command-line tools.

***

## `grantiva runner install`

Extract or update the embedded UI automation runner binary.

```bash theme={null}
grantiva runner install [--json]
```

Run once after installing or upgrading the CLI.

***

## `grantiva runner start`

Start the runner with WebDriverAgent and keep it alive for interactive use.

```bash theme={null}
grantiva runner start [--bundle-id ID] [--simulator SIMULATOR] [--detach] [--json]
```

| Flag          | Description                                                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `--bundle-id` | App bundle identifier (reads from `grantiva.yml` if omitted)                                                                 |
| `--simulator` | Simulator name or UDID (reads from `grantiva.yml` if omitted)                                                                |
| `--detach`    | Detach the runner from the terminal using `nohup`. The process survives terminal closure. Prints the log file path on start. |

Boots the simulator, launches WDA, and writes a session file so other commands can auto-detect the port. Use `grantiva runner dump-hierarchy` to inspect the view hierarchy while running.

With `--detach`, the runner is launched via `nohup` in its own shell session so it keeps running after the terminal closes. The log file path is printed on startup — tail it with `tail -f <path>` to follow runner output.

***

## `grantiva runner stop`

Stop the running runner session.

```bash theme={null}
grantiva runner stop [--json]
```

***

## `grantiva runner dump-hierarchy`

Dump the view hierarchy from a running app.

```bash theme={null}
grantiva runner dump-hierarchy [--port PORT] [--format FORMAT] [--json]
```

| Flag       | Description                                             |
| ---------- | ------------------------------------------------------- |
| `--port`   | WDA port (auto-detected from active session if omitted) |
| `--format` | Output format: `tree` (default), `json`, or `xml`       |

Requires an active session started with `grantiva runner start`.

***

## `grantiva runner version`

Show the embedded runner version.

```bash theme={null}
grantiva runner version [--json]
```

***

## `grantiva mcp`

Start the Grantiva MCP server for AI agent integration.

```bash theme={null}
grantiva mcp
```

Runs an MCP-compatible server that exposes the live view hierarchy and device state as resources, enabling AI coding assistants to query the running app.

***

## `grantiva init`

Generate a `grantiva.yml` configuration file.

```bash theme={null}
grantiva init [--scheme SCHEME] [--bundle-id BUNDLE_ID]
```

Auto-detects workspace/project and scheme if not specified.