Skip to main content
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]
FlagDescription
--schemeXcode scheme to build
--simulatorSimulator name (e.g., “iPhone 16”)
--app-filePath to a pre-built .app bundle or .ipa archive (skips build)
--no-buildNo-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]
FlagDescription
--schemeXcode scheme to build
--simulatorSimulator name (e.g., “iPhone 16”)
--bundle-idApp bundle identifier (derived from Info.plist if using --app-file)
--app-filePath to a pre-built .app bundle or .ipa archive (skips build)
--no-buildSkip 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. 
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]
FlagDescription
--schemeXcode scheme to build
--simulatorSimulator name (e.g., “iPhone 16”)
--bundle-idApp bundle identifier
--app-filePath to a pre-built .app bundle or .ipa archive (skips build)
--no-buildSkip building and installing — assume the app is already on the simulator
--flowRun a single flow YAML file instead of all configured flows
--keep-aliveHold the GrantivaAgent session open after flows complete so grantiva hierarchy can inspect UI state without relaunching. Release with Ctrl-C.
--logsStream simulator app logs into this terminal, prefixed with [log]. Predicate auto-derived from the app’s bundle ID.
--logs-predicateCustom NSPredicate for simctl log stream --predicate. Implies --logs.
--logs-levelLog 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. 
grantiva hierarchy [--udid UDID] [--format xml|json] [--json]
FlagDescription
--udidTarget a specific simulator’s session (defaults to the newest keep-alive session).
--formatOutput 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]
FlagDescription
--schemeXcode scheme to build
--simulatorSimulator name (e.g., “iPhone 16”)
--bundle-idApp bundle identifier
--app-filePath to a pre-built .app bundle or .ipa archive (skips build)
--no-buildSkip 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. 
grantiva diff capture [--scheme SCHEME] [--simulator SIMULATOR]
                      [--bundle-id ID] [--app-file PATH] [--no-build] [--json]
FlagDescription
--app-fileUse a pre-built .app or .ipa instead of building
--no-buildSkip 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]
FlagDescription
--captureCapture fresh screenshots before comparing
--app-fileUse a pre-built binary when capturing (requires --capture)
--no-buildSkip 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.

​
grantiva auth login

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]
FlagDescription
--bundle-idApp bundle identifier (reads from grantiva.yml if omitted)
--simulatorSimulator name or UDID (reads from grantiva.yml if omitted)
--detachDetach 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]
FlagDescription
--portWDA port (auto-detected from active session if omitted)
--formatOutput 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.