Commands

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

`grantiva build`

Build the app for a simulator using xcodebuild.

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.

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:

Boots the simulator
Builds via xcodebuild (unless --app-file or --no-build)
Installs via simctl install
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.

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:

Boots the simulator.
Builds, installs the app (unless --app-file or --no-build).
Starts GrantivaAgent on the simulator. The flow drives the app — no pre-launch.
If --logs is set, tees xcrun simctl spawn log stream output inline with the flow output.
Runs all configured flows (or the single --flow file) and reports step pass/fail.
On failure: captures a screenshot of the simulator’s current state.
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.
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.

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:

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

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:

Boots simulator
Builds the app (unless --app-file or --no-build is used)
Installs the app and starts GrantivaAgent
Captures screenshots for all configured screens
Compares against baselines (pixel + perceptual)
Uploads results to the Grantiva dashboard
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.

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.

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.

grantiva diff approve [SCREEN_NAME ...] [--json]

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

Authenticate with Grantiva.

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.

grantiva auth status [--json]

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

`grantiva auth logout`

Remove stored credentials.

grantiva auth logout [--json]

`grantiva doctor`

Check environment and dependencies.

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.

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.

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.

grantiva runner stop [--json]

`grantiva runner dump-hierarchy`

Dump the view hierarchy from a running app.

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.

grantiva runner version [--json]

`grantiva mcp`

Start the Grantiva MCP server for AI agent integration.

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.

grantiva init [--scheme SCHEME] [--bundle-id BUNDLE_ID]

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

Getting Started

iOS SDK

CLI

Concepts

Push

Dashboard

`grantiva build`

`grantiva install`

`grantiva run`

`grantiva hierarchy`

`grantiva ci run`

`grantiva diff capture`

`grantiva diff compare`

`grantiva diff approve`

`grantiva auth status`

`grantiva auth logout`

`grantiva doctor`

`grantiva runner install`

`grantiva runner start`

`grantiva runner stop`

`grantiva runner dump-hierarchy`

`grantiva runner version`

`grantiva mcp`

`grantiva init`

​grantiva build

​grantiva install

​grantiva run

​grantiva hierarchy

​grantiva ci run

​grantiva diff capture

​grantiva diff compare

​grantiva diff approve

​grantiva auth login

​grantiva auth status

​grantiva auth logout

​grantiva doctor

​grantiva runner install

​grantiva runner start

​grantiva runner stop

​grantiva runner dump-hierarchy

​grantiva runner version

​grantiva mcp

​grantiva init

`grantiva build`

`grantiva install`

`grantiva run`

`grantiva hierarchy`

`grantiva ci run`

`grantiva diff capture`

`grantiva diff compare`

`grantiva diff approve`

`grantiva auth login`

`grantiva auth status`

`grantiva auth logout`

`grantiva doctor`

`grantiva runner install`

`grantiva runner start`

`grantiva runner stop`

`grantiva runner dump-hierarchy`

`grantiva runner version`

`grantiva mcp`

`grantiva init`