Skip to main content
The finalrun CLI is the main interface for validating workspaces, running tests, and inspecting reports. CLI flags always take precedence over settings in .finalrun/config.yaml, so you can override any default at the command line without editing your config file.

​
Getting started

Use these commands to verify your environment before running tests.

finalrun check

Validates your .finalrun workspace, environment bindings, selectors, and suite manifests. Falls back to the env set in .finalrun/config.yaml when --env is omitted.

finalrun doctor

Checks host readiness for local Android and iOS runs. Use --platform to check a single platform.
# Check the full workspace
finalrun check

# Validate a specific environment and platform
finalrun check --env dev --platform android

​
Running tests

Executes one or more YAML specs from .finalrun/tests/.
finalrun test <selectors...> [flags]
Examples
# Run a single test
finalrun test smoke.yaml --platform android --model google/gemini-3-flash-preview

# Run with a specific app binary
finalrun test smoke.yaml --platform android --app path/to/your.apk

# Run two specs at once
finalrun test auth/login.yaml auth/logout.yaml --platform ios --env staging

​
Common flags

The following flags apply to both finalrun test and finalrun suite.
​
--platform
android | ios
required
Target platform for the test run. Required when the platform cannot be inferred from the --app extension (.apk implies Android, .app implies iOS).
​
--model
string
AI model to use, in provider/model format. For example: google/gemini-3-flash-preview, anthropic/claude-sonnet-4-6, openai/gpt-5. Falls back to the model key in .finalrun/config.yaml.
​
--env
string
Environment name. Selects the matching file at .finalrun/env/<name>.yaml. Falls back to the env key in .finalrun/config.yaml.
​
--app
path
Path to the .apk or .app binary to install and test. Overrides the app identity defined in .finalrun/config.yaml.
​
--api-key
string
Override the provider API key for this run. Use --api-key for one-off runs; for persistent configuration set the provider environment variable (GOOGLE_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY).
​
--debug
boolean
Enable debug logging for the run.
​
--max-iterations
number
Cap the number of AI action iterations per step. The run aborts when the limit is reached.
CLI flags always take precedence over .finalrun/config.yaml. You can set defaults in config and override them selectively at the command line.

​
Report commands

After a test run, FinalRun saves artifacts locally. These commands let you list, browse, and manage those reports.
CommandDescription
finalrun runsLists local reports from ~/.finalrun/workspaces/<workspace-hash>/artifacts.
finalrun start-serverStarts or reuses the local report UI for the current workspace.
finalrun server-statusShows the current local report server status.
finalrun stop-serverStops the local report server.
All report commands accept --workspace <path> to target a workspace other than the current directory. 
finalrun runs

# Machine-readable output
finalrun runs --json

# Target a different workspace
finalrun runs --workspace /path/to/other/app

​
Getting help

finalrun --help
finalrun <command> --help