Install FinalRun: CLI setup and platform prerequisites

Install the FinalRun CLI on macOS or Linux, set up Android or iOS platform prerequisites, and verify your host is ready to run tests.

FinalRun runs as a Node.js CLI. The install script handles Node.js, the CLI itself, and the platform driver assets needed for Android or iOS test execution. This page covers system requirements, install methods, platform-specific prerequisites, and how to verify your setup.

System requirements

• Node.js 20.0.0 or later

The one-line install script will set up Node.js for you if it isn’t already present.

Install FinalRun

One-line install (recommended):

curl -fsSL https://raw.githubusercontent.com/final-run/finalrun-agent/main/scripts/install.sh | bash

This script installs Node.js (if needed), the finalrun CLI globally, and all bundled platform driver assets for Android and iOS.

npm (if you already have Node.js 20+):

npm install -g @finalrun/finalrun-agent

Verify the installation

After installing, confirm the CLI is on your PATH:

finalrun --help

Then check host readiness for your target platform:

finalrun doctor

finalrun doctor reports which required tools are present, missing, or misconfigured. You can also check a single platform:

finalrun doctor --platform android
finalrun doctor --platform ios

Fix any issues reported before running tests.

Platform prerequisites

Android

Android tests run on emulators via adb. You need the Android SDK and a few additional tools on your PATH.

Required:

Tool	How to provide
adb	Available through ANDROID_HOME, ANDROID_SDK_ROOT, or PATH
emulator	Must be on PATH; used to discover and boot Android Virtual Devices
scrcpy	Must be on PATH; used for screen recording during local runs
FinalRun Android driver assets	Installed automatically by the CLI during installation

Install the Android SDK via Android Studio or the standalone command-line tools. Once installed, make sure platform-tools and emulator directories are on your PATH, or set ANDROID_HOME to your SDK root.

Install scrcpy using your system package manager:

macOS

brew install scrcpy

After setting up these tools, verify readiness:

finalrun doctor --platform android

iOS

iOS testing requires macOS. It is not supported on Linux or Windows.

iOS tests run on simulators via Xcode’s xcrun simctl. You need Xcode command line tools and a few standard utilities.

Required:

Tool	Notes
macOS	iOS simulator support is macOS-only
Xcode command line tools	Provides xcrun
xcrun simctl	Used to manage and boot iOS simulators
unzip	Standard macOS utility
/bin/bash	Standard macOS shell
plutil	Standard macOS utility
FinalRun iOS driver archives	Installed automatically by the CLI during installation

Install Xcode command line tools if you haven’t already:

xcode-select --install

Optional tools:

Tool	Purpose
ffmpeg	Compresses iOS recordings after capture
applesimutils	Enables simulator permission helpers

Install optional tools via Homebrew:

brew install ffmpeg applesimutils

After setting up these tools, verify readiness:

finalrun doctor --platform ios

Next steps

Once finalrun doctor reports your host as ready, follow the Quick Start guide to write and run your first test.