Installation

Requirements

macOS 15 or later
Xcode 16 or later
Swift 6.1+ (only needed to build from source)

Install

Homebrew
Release tarball
From source

brew install grantiva/tap/grantiva

Upgrade the same way:

brew upgrade grantiva

Each release publishes a universal (arm64 + x86_64) macOS binary on GitHub Releases.

curl -fsSL -o grantiva.tar.gz \
  https://github.com/grantiva/cli/releases/download/v1.9.0/grantiva-v1.9.0-macos.tar.gz
tar -xzf grantiva.tar.gz
sudo mv grantiva grantiva_GrantivaCore.bundle /usr/local/bin/

The archive contains two items: the grantiva binary and the grantiva_GrantivaCore.bundle resource bundle. Keep them next to each other — the CLI cannot extract its embedded runner without the bundle.

git clone https://github.com/grantiva/cli.git
cd cli
swift build -c release
cp .build/release/grantiva /usr/local/bin/grantiva

Verify

grantiva --version
grantiva doctor

doctor checks Xcode and its version, whether a simulator is booted, whether the runner is extracted, grantiva.yml, the git repository, your Grantiva auth, and GitHub App configuration. A failing required check exits 1; the optional ones are advisory and do not affect the exit code, so grantiva doctor || exit 1 is a usable CI preflight.

Extract the runner

UI automation runs through GrantivaAgent, a WebDriverAgent embedded in the CLI. Extract it once after installing or upgrading:

grantiva runner install

Commands that drive the simulator extract it on demand too, so this step is optional — running it up front just moves the one-time cost out of your first test run.

Authenticate

Local capture and comparison work with no account. You need credentials for grantiva ci run, cloud baselines, and every grantiva console command.

Browser login
API key
Environment (CI)

grantiva auth login --api-key gpat_your_key

Validates the key and saves it to the same file. Point at a different deployment with --base-url.

export GRANTIVA_API_KEY="gpat_your_key"
export GRANTIVA_API_URL="https://api.grantiva.io"   # optional

The environment variable takes precedence over ~/.grantiva/auth.json, so nothing needs writing to disk on a CI runner.

Check what the CLI is using:

grantiva auth status

It reports the source as env or file, the base URL, and the key prefix. grantiva auth logout deletes ~/.grantiva/auth.json; it does not clear GRANTIVA_API_KEY from your environment.

Next steps

VRT quick start — capture your first screenshots
Configuration — the grantiva.yml reference
Commands — every grantiva command
Console commands — your dashboard from the terminal
Simulator management — capacity, leases, and teardown
CI integration — GitHub Actions, pre-built binaries, parallel runs

Getting Started

SDKs

CLI

Concepts

Push

Dashboard

Requirements

Install

Verify

Extract the runner

Authenticate

Next steps

​Requirements

​Install

​Verify

​Extract the runner

​Authenticate

​Next steps

Requirements

Install

Verify

Extract the runner

Authenticate

Next steps