AltTester® CLI and AI Extension

The AltTester® CLI is a command-line tool for interacting with Unity and Unreal games instrumented with the AltTester® SDK. It lets you connect to a running game, explore its UI, interact with objects, inspect properties, and run automated tests, all from the terminal.

The CLI also powers the AI Extension, which enables AI assistants to control and test your game through natural language.

Note

The AltTester® CLI requires a game instrumented with the AltTester® SDK. See the Unity SDK documentation or Unreal SDK documentation to set up your game.

Note

AltTester® CLI is available only starting with AltTester® Desktop 2.3.2.

Getting Started

When you first start AltTester® Desktop with a compatible license, you’ll be prompted to set up the CLI. Simply click Download to automatically install and configure it for your system.

By default, the CLI is installed to .alttester/CLI/ and is automatically added to your PATH. If you changed the installation path in AltTester® Desktop settings, the CLI will be placed in the path you configured instead. After installation, verify it is available by running:

alttester --version

Set up later from Settings

If you skip the initial prompt, you can install the CLI later:

Open AltTester® Desktop Settings
Look for the Configure AltTester® AI Extension section
Click Open Configuration Setup to download and install the CLI

Command Reference

You can print the version of the CLI with alttester --version and get a list of all available commands with alttester --help. To see the options for a specific command, run alttester <command> --help.

Global Options

These options can be used with any command.

Name	Required	Description
`--host`	No	AltTester® server host address. The default value is: `127.0.0.1`
`--port`	No	AltTester® server port. The default value is: `13000`
`--output-mode`	No	Output mode: `file` saves a snapshot to disk and returns the path; `json` returns the full game state inline. Can also be set with the `ALTTESTER_CLI_OUTPUT_MODE` environment variable. The default value is: `file`
`--session`	No	Session name. Required when more than one session is live at the same time. Defaults to the only live session for routing; on `connect`, defaults to the resolved app ID when omitted.

Connection

`connect`

Connects to an AltTester®-instrumented game and starts a persistent background daemon. The daemon maintains a persistent WebSocket connection so subsequent commands execute instantly without reconnecting.

When two concurrent connect calls target the same game, only the first spawns a daemon; the second reports “Already connected”.

Parameters

Name	Required	Description
`--app-name`	No	Application name to match against registered games. Acts as a case-insensitive substring filter. The default value is: `unknown` (matches any name).
`--platform`	No	Platform to match (e.g. `Android`, `iOS`, `Desktop`). Acts as a case-insensitive substring filter. The default value is: `unknown` (matches any platform).
`--platform-version`	No	Platform version to match. Acts as a case-insensitive substring filter. The default value is: `unknown` (matches any version).
`--app-id`	No	Application ID of the registered game. If omitted, the CLI resolves it automatically using the other filters. Pass this to disambiguate when multiple games are registered. The default value is: `unknown` (auto-resolved).
`--device-instance-id`	No	Device instance ID for exact-match filtering. The default value is: `unknown` (matches any device).
`--timeout`	No	Connection timeout in seconds. The default value is: `5`
`--idle-timeout`	No	Seconds of inactivity before the daemon exits automatically. The default value is: `300`
`--use-secure`	No	Use secure WebSocket (`wss://`). The default value is: `false`

Returns

Connection status confirmation with session details.

Examples

alttester connect
alttester connect --host 192.168.1.10 --port 13000
alttester connect --timeout 10
alttester connect --idle-timeout 600

`status`

Checks whether the CLI is connected to a game.

Parameters

No parameters.

Returns

Connection status (connected or disconnected) with session details.

Examples

alttester status

`disconnect`

Disconnects from the game and stops the background daemon.

Parameters

Name	Required	Description
`--all`	No	Disconnect every live session and remove every session file. The default value is: `false`

Returns

Confirmation.

Examples

alttester disconnect
alttester disconnect --all

`apps`

Lists all games currently registered on the AltTester® server. Use this to see what games are available before connecting, or to find the right --app-id when multiple games are registered.

Parameters

Name	Required	Description
`--timeout`	No	Server query timeout in seconds. The default value is: `5`
`--use-secure`	No	Use secure WebSocket (`wss://`). The default value is: `false`

Returns

List of registered games with their name, platform, platform version, device instance ID, game engine, app ID, and status.

Examples

alttester apps
alttester apps --host 192.168.1.10

Find Objects

`find`

Finds one or more objects in the current scene.

Parameters

Name	Required	Description
value	Yes (or `--contains`)	The object name to find. Required unless `--contains` is used.
`--by`	No	Locator strategy to use when matching objects. See Locator Strategies. The default value is: `NAME`
`--contains`	No	Match all objects whose name contains this text. Can be used instead of a positional `value`.
`--all`	No	Return all matching objects instead of just the first. The default value is: `false`
`--wait`	No	Wait for the object to appear before returning. The default value is: `false`
`--timeout`	No	How long to wait for the object when using `--wait`, in seconds. The default value is: `20`
`--camera-by`	No	Locator strategy for the camera used to calculate screen coordinates. The default value is: `NAME`
`--camera-value`	No	Camera locator value. If omitted, all cameras in the scene are searched.

Returns

AltObject when finding a single result, or a list of AltObjects when using --all.

Examples

# Find by name (default)
alttester find PlayButton

# Find by partial name
alttester find --contains Button --all

# Find by tag
alttester find Player --by TAG

# Find by hierarchy path
alttester find --by PATH //Canvas/MainMenu/PlayButton

# Wait for an object to appear (useful after a scene load)
alttester find LoadingScreen --wait --timeout 30

`find-at-coordinates`

Finds the object at specific screen coordinates.

Parameters

Name	Required	Description
`--x`	Yes	X screen coordinate.
`--y`	Yes	Y screen coordinate.

Returns

AltObject at the given screen coordinates.

Examples

alttester find-at-coordinates --x 350 --y 500

`get-all-elements`

Gets every object in the current scene.

Parameters

Name	Required	Description
`--enabled-only`	No	If set, return only objects that are active in the hierarchy. The default value is: `false`

Returns

List of all AltObjects in the scene.

Examples

alttester get-all-elements
alttester get-all-elements --enabled-only

Input Actions

`tap`

Taps on an object. Use for mobile and touch interactions.

Parameters

Name	Required	Description
value	Yes	The object name or locator value.
`--by`	No	Locator strategy. The default value is: `NAME`
`--count`	No	Number of taps to perform. The default value is: `1`
`--camera-by`	No	Locator strategy for the camera. The default value is: `NAME`
`--camera-value`	No	Camera locator value.

Returns

Game state snapshot.

Examples

alttester tap PlayButton
alttester tap PlayButton --count 2
alttester tap --by PATH //Canvas/Menu/StartButton

`click`

Clicks on an object. Use for desktop interactions.

Parameters

Name	Required	Description
value	Yes	The object name or locator value.
`--by`	No	Locator strategy. The default value is: `NAME`
`--camera-by`	No	Locator strategy for the camera. The default value is: `NAME`
`--camera-value`	No	Camera locator value.

Returns

Game state snapshot.

Examples

alttester click PlayButton

`press`

Presses a keyboard key.

Parameters

Name	Required	Description
key	Yes	The key code to press (e.g. `Space`, `Return`, `Escape`, `A`–`Z`, `Alpha0`–`Alpha9`).
`--duration`	No	How long to hold the key, in seconds. The default value is: `0.1`
`--power`	No	Press power from 0.0 to 1.0. The default value is: `1.0`

Returns

Confirmation.

Examples

alttester press Space
alttester press Return
alttester press W --duration 2.0

`key-down`

Presses and holds a keyboard key without releasing it. Useful for key combinations; pair with key-up to release.

Parameters

Name	Required	Description
key	Yes	The key code to hold down.
`--power`	No	Press power from 0.0 to 1.0. The default value is: `1.0`

Returns

Confirmation.

Examples

alttester key-down LeftShift
alttester press A
alttester key-up LeftShift

`key-up`

Releases a previously held key.

Parameters

Name	Required	Description
key	Yes	The key code to release.

Returns

Confirmation.

Examples

alttester key-up LeftShift

`swipe`

Swipes between two screen coordinates.

Parameters

Name	Required	Description
`--start-x`	Yes	X coordinate of the swipe start point.
`--start-y`	Yes	Y coordinate of the swipe start point.
`--end-x`	Yes	X coordinate of the swipe end point.
`--end-y`	Yes	Y coordinate of the swipe end point.
`--duration`	No	Duration of the swipe gesture in seconds. The default value is: `0.5`

Returns

Confirmation.

Examples

alttester swipe --start-x 100 --start-y 500 --end-x 100 --end-y 200 --duration 0.5

`scroll`

Scrolls using the mouse wheel.

Parameters

Name	Required	Description
`--vertical`	No	Vertical scroll amount. Positive values scroll up, negative values scroll down. The default value is: `-1`
`--duration`	No	Duration of the scroll in seconds. The default value is: `0.1`

Returns

Confirmation.

Examples

alttester scroll --vertical 3       # Scroll up
alttester scroll --vertical -3      # Scroll down

`move-mouse`

Moves the mouse cursor to a screen position.

Parameters

Name	Required	Description
`--x`	Yes	Target X screen coordinate.
`--y`	Yes	Target Y screen coordinate.
`--duration`	No	Duration of the movement in seconds. The default value is: `0.1`

Returns

Confirmation.

Examples

alttester move-mouse --x 200 --y 300

`touch`

Manages a multi-touch gesture with explicit begin, move, and end phases.

Parameters

Name	Required	Description
action	Yes	The touch phase: `begin`, `move`, or `end`.
`--x`	Yes (begin, move)	X screen coordinate of the touch point.
`--y`	Yes (begin, move)	Y screen coordinate of the touch point.
`--finger-id`	No	The finger ID returned by a previous `begin` action. Pass it to `move` and `end` to target the same touch point. The default value is: `1`

Returns

The finger ID (integer) assigned to the touch point on begin. Confirmation on move and end.

Examples

alttester touch begin --x 100 --y 200        # Returns a finger-id
alttester touch move --x 150 --y 250 --finger-id 1
alttester touch end --finger-id 1

`reset-input`

Resets all active input operations to a neutral state.

Parameters

No parameters.

Returns

Confirmation.

Examples

alttester reset-input

Other Commands

`get-text`

Gets the text content of a UI element.

Parameters

Name	Required	Description
value	Yes	The object name or locator value.
`--by`	No	Locator strategy. The default value is: `NAME`
`--camera-by`	No	Locator strategy for the camera. The default value is: `NAME`
`--camera-value`	No	Camera locator value.

Returns

The text content of the element as a string.

Examples

alttester get-text ScoreLabel
alttester get-text --by PATH //Canvas/Header/Title

`set-text`

Sets the text of an input field.

Parameters

Name	Required	Description
value	Yes	The object name or locator value.
`--text`	Yes	The text to set on the input field.
`--by`	No	Locator strategy. The default value is: `NAME`
`--camera-by`	No	Locator strategy for the camera. The default value is: `NAME`
`--camera-value`	No	Camera locator value.

Returns

Confirmation.

Examples

alttester set-text UsernameInput --text "player1"

`scene`

Gets the current scene name, lists all loaded scenes, or loads a scene by name.

Parameters

Name	Required	Description
`--list`	No	If set, returns all currently loaded scenes instead of just the active one.
`--load`	No	Name of the scene to load.

Returns

The current scene name by default. A list of scene names when using --list. Confirmation when using --load.

Examples

alttester scene                     # Current scene
alttester scene --list              # All loaded scenes
alttester scene --load MainMenu     # Load a scene

`game-state`

Gets the full game object hierarchy for the current scene.

Parameters

Name	Required	Description
`--root`	No	Limit the hierarchy to objects under this root object path.
`--output`	No	File path to save the game state to. If omitted, saved to `.alttester-cli/`.

Returns

Game state snapshot containing the full object hierarchy, scene info, and screen positions.

Examples

alttester game-state
alttester game-state --root Canvas
alttester game-state --output my-state.json

`snapshot`

Captures and saves a game state snapshot, or reads back a previously saved one.

Parameters

Name	Required	Description
`--root`	No	Limit the snapshot to objects under this root object path (capture mode).
`--output`	No	File path to save the snapshot to. If omitted, saved to `.alttester-cli/` (capture mode).
`--show`	No	Read and print the latest snapshot instead of capturing a new one. Does not require a connected game.
`--file`	No	Path to a specific snapshot file to read when using `--show`. Defaults to `.alttester-cli/latest`.
`--json`	No	When used with `--show`, print the raw snapshot JSON instead of the rendered hierarchy.

Returns

Path to the saved snapshot file (capture mode), or the rendered hierarchy / raw JSON (read-back mode).

Examples

alttester snapshot
alttester snapshot --root Canvas/Menu
alttester snapshot --output menu-snapshot.json

# Read back the latest snapshot (no game connection needed)
alttester snapshot --show
alttester snapshot --show --json
alttester snapshot --show --file path/to/snapshot.json

`screen-size`

Gets the game’s screen resolution.

Parameters

No parameters.

Returns

Width and height of the screen in pixels.

Examples

alttester screen-size

`get-property`

Reads a component property from an object.

Parameters

Name	Required	Description
value	Yes	The object name or locator value.
`--component`	Yes	The component type name.
`--property`	Yes	The property name on the component.
`--assembly`	Yes	The name of the assembly containing the component.
`--by`	No	Locator strategy. The default value is: `NAME`
`--max-depth`	No	Maximum depth for nested property traversal. The default value is: `2`

Returns

The value of the requested property.

Examples

alttester get-property Player \
  --component PlayerController \
  --property Health \
  --assembly Assembly-CSharp

`set-property`

Sets a component property on an object.

Parameters

Name	Required	Description
value	Yes	The object name or locator value.
`--component`	Yes	The component type name.
`--property`	Yes	The property name on the component.
`--assembly`	Yes	The name of the assembly containing the component.
`--set-value`	Yes	The new value to assign to the property.
`--by`	No	Locator strategy. The default value is: `NAME`

Returns

Confirmation.

Examples

alttester set-property Player \
  --component PlayerController \
  --property Health \
  --assembly Assembly-CSharp \
  --set-value 100

`wait-for-property`

Waits until a component property reaches an expected value.

Parameters

Name	Required	Description
value	Yes	The object name or locator value.
`--component`	Yes	The component type name.
`--property`	Yes	The property name on the component.
`--assembly`	Yes	The name of the assembly containing the component.
`--expected`	Yes	The expected value to wait for.
`--by`	No	Locator strategy. The default value is: `NAME`
`--timeout`	No	How long to wait before failing, in seconds. The default value is: `20`
`--interval`	No	How often to poll the property, in seconds. The default value is: `0.5`

Returns

The matched property value.

Examples

alttester wait-for-property Player \
  --component PlayerController \
  --property Health \
  --assembly Assembly-CSharp \
  --expected 0 \
  --timeout 30

`get-time-scale`

Gets the current game time scale.

Parameters

No parameters.

Returns

The current time scale as a float.

Examples

alttester get-time-scale

`set-time-scale`

Sets the game time scale. Useful for speeding up or pausing gameplay during tests.

Parameters

Name	Required	Description
value	Yes	The time scale to set. Use `0` to pause, `1` for normal speed, values below `1` for slow motion, and values above `1` to speed up.

Returns

Confirmation.

Examples

alttester set-time-scale 0       # Pause
alttester set-time-scale 0.5     # Half speed
alttester set-time-scale 1       # Normal
alttester set-time-scale 2       # Double speed

Screenshot

`screenshot`

Takes a screenshot of the game.

Parameters

Name	Required	Description
`--path`	No	File path for the saved PNG. The default value is: `screenshot.png`

Returns

Path to the saved PNG screenshot file.

Examples

alttester screenshot
alttester screenshot --path my-screenshot.png

Other

`run-tests`

Runs Robot Framework tests with automatic environment setup and report generation.

Results are saved to a timestamped directory under results/ and include report.html and log.html. An interactive dashboard aggregating all runs is also generated at results/dashboard.html.

Parameters

Name	Required	Description
file	No	Path to a test file or directory to run. The default value is: `tests/`
`--test`	No	Run only the test with this exact name.
`--include`	No	Run only tests tagged with this tag.
`--status`	No	Report the state of the current or latest test run instead of starting a new one. Used mainly with the AI Extension, where test runs are started in the background.

Returns

Test results summary and path to the report directory.

Examples

alttester run-tests                             # Run all tests in tests/
alttester run-tests tests/login.robot           # Run a specific file
alttester run-tests --test "Test Login Flow"    # Run a specific test by name
alttester run-tests --include smoke             # Run tests tagged 'smoke'

`run-keyword`

Executes a single Robot Framework keyword from your test library.

Keywords are loaded from .resource files in tests/actions/, tests/checks/, and tests/flows/.

Parameters

Name	Required	Description
keyword	No	The keyword name to execute. Omit when using `--list`.
`--args`	No	Arguments to pass to the keyword.
`--list`	No	If set, lists all available keywords instead of running one.

Returns

The keyword execution result, or a list of available keywords when using --list.

Robot output files are written to <working_dir>/.alttester-cli/keyword-results/.

Examples

alttester run-keyword --list                    # List available keywords
alttester run-keyword "Click Play Button"       # Run a keyword
alttester run-keyword "Set Player Name" --args "Player1"

`setup-project`

Creates a new test automation project from a starter template.

Parameters

Name	Required	Description
language	Yes	The language for the starter project. Supported values: `python`, `dotnet`.
`--name`	No	Name of the game being tested. The default value is: `MyGame`
`--path`	No	Directory where the project will be created. The default value is the current directory.
`--description`	No	A brief description of the game, used in generated documentation.

Returns

Confirmation and the path to the created project directory.

Examples

alttester setup-project python
alttester setup-project dotnet --name "MyGame" --description "Platform adventure game"

`docs`

Accesses built-in AltTester® documentation.

At least one of --list, --read, or --search must be provided. Running alttester docs without any option prints usage instructions.

Parameters

Name	Required	Description
`--list`	Yes (if `--read` and `--search` are omitted)	List all available documents.
`--read`	No	Name of the document to read.
`--search`	No	Search term to look for across all documents.

Returns

List of document names (--list), document content (--read), or matching excerpts (--search).

The available documents include the general AltTester® docs plus Robot Framework skill guides, which are namespaced as robot/<topic> (e.g. alttester docs --read robot/authoring).

Examples

alttester docs --list
alttester docs --read overview
alttester docs --search "locator"

`start-desktop`

Launches the AltTester® Desktop application.

Parameters

No parameters.

Returns

Confirmation.

Examples

alttester start-desktop

`start-game`

Launches a game executable.

Parameters

Name	Required	Description
path	Yes	Full path to the game executable.

Returns

Confirmation.

Examples

alttester start-game /path/to/MyGame.app

`uninstall`

Removes the AltTester® CLI binary from your system.

Parameters

Name	Required	Description
`--yes` / `-y`	No	Skip the confirmation prompt. Required in non-interactive terminals such as Git Bash.
`--purge`	No	Also remove the `~/.alttester-cli/` data directory (configuration, update cache, and WDA session).

Returns

Confirmation that the CLI has been removed.

Examples

alttester uninstall
alttester uninstall --yes
alttester uninstall --yes --purge

`update`

Updates the CLI to the latest version.

The CLI also checks for updates automatically (see Updating the CLI below), so you usually don’t need to run this manually.

Parameters

Name	Required	Description
`--check`	No	Check whether a newer version is available without downloading or installing it.
`--auto-update`	No	Enable or disable automatic updates on startup. Accepts `on` or `off`.

Returns

The current and latest versions, and confirmation when an update is installed.

Examples

alttester update                      # Update to the latest version
alttester update --check              # Check for a new version only
alttester update --auto-update off    # Disable automatic updates
alttester update --auto-update on     # Re-enable automatic updates

iOS Device Management

Note

iOS commands require macOS with Xcode installed.

`ios devices` / `ios install` / `ios launch` / `ios uninstall`

Parameters

Name	Required	Description
`--device`	No	UDID of the target device. If omitted and only one device is connected, it is auto-detected.

Returns

List of connected devices (devices). Confirmation for install, launch, and uninstall.

Examples

alttester ios devices                        # List connected devices
alttester ios install path/to/App.ipa        # Install an app
alttester ios launch com.example.game        # Launch an app
alttester ios uninstall com.example.game     # Uninstall an app

`ios wda-setup` / `ios wda-start` / `ios wda-stop` / `ios wda-status` / `ios wda-find` / `ios wda-tap` / `ios wda-source`

WDA is required for interacting with native iOS UI elements such as alerts, permission dialogs, and system popups.

Parameters

Name	Required	Description
`--team-id`	Yes (setup); first `wda-start` only	Your Apple Developer Team ID, used to sign the WDA build. Required for `wda-setup` and the first `wda-start`; reused automatically afterwards.
`--by`	No	Locator strategy for `wda-find` and `wda-tap`. One of `name` (default), `accessibility-id`, `class`, or `predicate`.
`--device`	No	UDID of the target device. Auto-detected when only one device is connected.

Returns

Confirmation for wda-setup, wda-start, wda-stop. Status details for wda-status. AltObject for wda-find. Confirmation for wda-tap. Native UI hierarchy XML for wda-source.

Examples

# One-time setup: clone and build WDA
alttester ios wda-setup --team-id YOUR_TEAM_ID

# Start/stop the WDA server
alttester ios wda-start --team-id YOUR_TEAM_ID
alttester ios wda-stop
alttester ios wda-status

# Interact with native elements
alttester ios wda-find Allow
alttester ios wda-tap Allow --by accessibility-id
alttester ios wda-source

`ios run`

Installs, launches, and sets up an app for testing in one command.

Parameters

Name	Required	Description
path	Yes	Path to the `.ipa` file to install.
`--team-id`	No	Your Apple Developer Team ID. When provided, WDA is set up so native UI elements (alerts, permission dialogs) can be interacted with. The app still installs and launches without it.
`--accept-alerts`	No	Automatically dismiss system permission alerts using WDA after launch. The default value is: `true`
`--connect`	No	Connect the AltTester® driver after launch. The default value is: `false`. Currently a no-op placeholder; run `alttester connect` separately after the app starts.
`--device`	No	UDID of the target device. Auto-detected when only one device is connected.

Returns

Confirmation that the app is installed, launched, and ready for testing.

Examples

alttester ios run path/to/App.ipa --team-id YOUR_TEAM_ID --accept-alerts

Android Device Management

`android devices` / `android install` / `android launch` / `android uninstall`

Parameters

Name	Required	Description
`--device`	No	Serial number of the target device. Requires `adb` on your PATH.

Returns

List of connected devices (devices). Confirmation for install, launch, and uninstall.

Examples

alttester android devices                     # List connected devices
alttester android install path/to/game.apk    # Install an APK
alttester android launch com.example.game     # Launch an app
alttester android uninstall com.example.game  # Uninstall an app

`android forward` / `android clear-forward`

Required when testing on a physical Android device so the CLI can reach the AltTester® server running inside the game.

Parameters

Name	Required	Description
`--port`	No	The port to forward. The default value is: `13000`
`--device`	No	Serial number of the target device.

Returns

Confirmation.

Examples

alttester android forward --port 13000
alttester android clear-forward

`android find` / `android tap` / `android source`

Parameters

Name	Required	Description
value	Yes (find, tap)	The element to find or tap.
`--by`	No	Locator strategy for `find` and `tap`. One of `text` (default), `resource-id`, `class`, or `content-desc`.
`--device`	No	Serial number of the target device.

Returns

AltObject for find. Confirmation for tap. Native UI hierarchy XML for source.

Examples

alttester android find Allow
alttester android tap Allow --by resource-id
alttester android source

`android run`

Installs, launches, and sets up an app for testing in one command.

Parameters

Name	Required	Description
path	Yes	Path to the `.apk` file to install.
`--package`	No	The application package name (e.g. `com.example.game`). Auto-detected from the APK when omitted.
`--forward`	No	Set up ADB reverse port forwarding automatically. The default value is: `true`
`--port`	No	The port to forward. The default value is: `13000`
`--connect`	No	Connect the AltTester® driver after launch. The default value is: `false`. Currently a no-op placeholder; run `alttester connect` separately after the app starts.
`--device`	No	Serial number of the target device.

Returns

Confirmation that the app is installed, launched, and ready for testing.

Examples

alttester android run path/to/game.apk
alttester android run path/to/game.apk --package com.example.game --port 13000

AltObject

The AltObject represents an object found in the game. It is returned by commands in the Find Objects group.

Fields

Name	Type	Description
name	string	The name of the object.
id	int	The object’s id.
x	int	The x axis coordinate on screen.
y	int	The y axis coordinate on screen.
mobileY	int	The y axis coordinate for mobile (Appium).
type	string	The object’s type. For objects from the app this is `gameObject`.
enabled	bool	The local active state of the object. Note that an object may be inactive because a parent is not active, even if this returns `true`.
worldX	float	The x axis coordinate in the app’s world.
worldY	float	The y axis coordinate in the app’s world.
worldZ	float	The z axis coordinate in the app’s world.
idCamera	int	The id of the camera used to calculate screen coordinates.
transformId	int	The transform component’s id.
transformParentId	int	The transform parent’s id.

Locator Strategies

The --by option controls how objects are matched. Available strategies:

Strategy	Description
`NAME`	Matches by object name. This is the default strategy.
`PATH`	Matches by hierarchy path using XPath syntax (e.g. `//Canvas/Menu/PlayButton`).
`ID`	Matches by the object’s instance ID.
`TAG`	Matches by Unity/Unreal tag.
`LAYER`	Matches by rendering layer.
`TEXT`	Matches by the text content of the object.
`COMPONENT`	Matches by component type attached to the object.

For partial name matching, use --contains instead of --by:

alttester find --contains Button --all          # All objects with "Button" in the name

Snapshots

After most state-changing commands, the CLI automatically saves a snapshot of the game state to the .alttester-cli/ directory in your project. Snapshots are JSON files containing the full object hierarchy, scene information, and screen positions. (A few read-only commands such as get-property, screen-size, screenshot, and the time-scale commands skip this capture.)

.alttester-cli/
  latest                                  # Symlink to most recent snapshot
  snapshot-2026-04-05T10-30-45Z.json
  snapshot-2026-04-05T10-31-12Z.json

In file output mode (the default), commands return a compact response with the path to the snapshot file. In json mode, the full game state is returned inline.

Updating the CLI

The CLI keeps itself up to date automatically. On startup, most commands check for a newer version, and if one is found the CLI updates itself before running the command. When an update is available you’ll see a short notice in the terminal.

To update on demand or just check, use the update command:

alttester update            # Update now
alttester update --check    # Check only, don't install

To turn automatic updates off (or back on):

alttester update --auto-update off
alttester update --auto-update on

Automatic updates are skipped when running the MCP server (alttester mcp).

AI Extension

The AI Extension enables AI assistants such as Claude, GitHub Copilot, and Cursor to control and test your game through natural language. Instead of writing CLI commands manually, you describe what you want and the AI does it.

The extension works in two ways:

Skills: structured AI workflow guides installed into your project that guide the AI through test planning, generation, execution, and debugging
MCP Server: running alttester mcp to connect any MCP-compatible AI IDE to your game

Note

The AI Extension requires a license that supports this functionality. For the moment, all Pro licenses include it, but this is subject to change.

Note

Unreal Engine support is limited at this stage. We welcome feedback to guide future improvements.

Setting Up with Skills

What Are Skills?

Skills are structured AI workflow guides installed into your project directory. When you ask the AI for help, it reads the skill files and follows the workflows they define, knowing which commands to run, what questions to ask, and how to interpret results.

Skills provide deeper, more context-aware assistance than the MCP server alone because they contain domain-specific knowledge about test automation patterns, project structure conventions, and step-by-step workflows.

Installing Skills

By default, skills are installed in the current project directory, making them available only for that project.

# Interactive: choose which skill you want
alttester install-skills

# Install a specific skill directly
alttester install-skills robot
alttester install-skills helper

This creates a .claude/skills/ directory in your project. The AI reads these automatically when you ask for help.

To install a skill globally (available in all projects), run the command from your home directory:

# macOS / Linux
cd ~ && alttester install-skills robot

# Windows (PowerShell)
cd $HOME; alttester install-skills robot

This installs to ~/.claude/skills/, which Claude Code reads in every project.

For claude.ai (web): Export the skill as a zip file, then open claude.ai, click Customize in the left sidebar, and install it under Skills:

alttester install-skills robot --zip

Choosing a Skill

Robot Skill (`robot`)

Choose this if you don’t have tests yet and prefer not to write code yourself.

The Robot skill uses Robot Framework with keyword-driven tests that read like natural language. The AI guides you through exploring your game, creating a test plan, generating tests, and running them.

Tests are organized into three layers:

Layer	Purpose	Example
Actions	Low-level interactions	"Click Play Button", "Enter Username"
Checks	Assertions and verifications	"Score Should Be", "Scene Should Be MainMenu"
Flows	Multi-step scenarios	"Complete Login Flow", "Navigate To Settings"

Helper Skill (`helper`)

Choose this if you already have tests in any language or framework.

The Helper skill works with existing test projects in C#, Python, Java, Robot Framework, or any other language. It helps with debugging failures, healing broken tests, writing new tests that match your project’s conventions, and understanding your game’s object hierarchy.

Setting Up as MCP Server

MCP (Model Context Protocol) is a standard way for AI applications to access external tools. Running alttester mcp starts a local server that lets AI assistants run CLI commands on your behalf.

Pick the IDE you use and add the configuration below.

Claude Desktop

Open Claude Desktop, go to Settings → Developer, then click Edit Config to open the configuration file. Add the following entry:

{
  "mcpServers": {
    "alttester": {
      "command": "alttester",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop after saving.

VS Code with GitHub Copilot

Note

Requires VS Code 1.99 or later and the GitHub Copilot extension. MCP tools appear in Copilot Chat when using Agent mode.

Create .vscode/mcp.json in your project:

{
  "servers": {
    "alttester": {
      "type": "stdio",
      "command": "alttester",
      "args": ["mcp"]
    }
  }
}

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global access):

{
  "mcpServers": {
    "alttester": {
      "command": "alttester",
      "args": ["mcp"]
    }
  }
}

JetBrains IDEs (PyCharm, Rider, IntelliJ IDEA)

Note

MCP support in JetBrains IDEs may require specific plugins or newer versions of the AI Assistant. Check JetBrains documentation for the latest MCP integration capabilities.

Go to File → Settings (or Preferences on macOS) → Tools → AI Assistant
Add a new MCP server configuration and choose “As JSON”
Enter:

{
  "mcpServers": {
    "alttester": {
      "command": "alttester",
      "args": ["mcp"]
    }
  }
}

Apply settings and restart the IDE if prompted.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "alttester": {
      "command": "alttester",
      "args": ["mcp"]
    }
  }
}

Claude Code

# Add to current project
claude mcp add --transport stdio alttester -- alttester mcp

# Or add globally (all projects)
claude mcp add --transport stdio --scope user alttester -- alttester mcp

Note

When using Claude Code, we recommend also installing a skill for a more guided experience. The MCP server provides the commands; the skill provides the workflow knowledge.

For the best experience in Claude Code, set up both:

# MCP server for commands
claude mcp add --transport stdio alttester -- alttester mcp

# Skill for guided workflows
alttester install-skills robot

Common Workflows

Exploring a Game

“Connect to my game and tell me what’s on screen.”

The AI will connect, capture the object hierarchy, and describe the current scene, listing visible UI elements, their positions, and their types.

Creating a Test Plan

“Explore the main menu and settings screens and create a test plan.”

The AI navigates between scenes, discovers interactive elements, and produces a markdown test plan. You review and approve it before any code is generated.

Generating and Running Tests

“Generate Robot Framework tests for the main menu based on the test plan.”

The AI creates tests using the three-layer structure (actions, checks, flows), sets up the Python environment if needed, and can run them:

“Run the tests and tell me the results.”

Debugging Failed Tests

“My test ‘Test Login Flow’ is failing because it can’t find the LoginButton. Can you help?”

The AI connects to the game, inspects the current state, identifies the root cause (renamed object, changed hierarchy, timing issue), and suggests or applies a fix.

Testing on Mobile Devices

“Set up my iOS device for testing with the app at builds/MyGame.ipa”

The AI handles device setup (WDA for iOS, port forwarding for Android), installs the app, connects to it, and is ready for testing.

What You Can Ask

Exploration:

“What objects are on the current screen?”
“Show me the hierarchy under the Canvas object”
“What scenes are loaded?”

Interaction:

“Tap the Play button”
“Type ‘player1’ into the username field”
“Swipe left on the inventory panel”

Testing:

“Create a test plan for the shop screen”
“Generate tests for the login flow”
“Run all smoke tests and show me the results”
“This test is failing, help me debug it”

Inspection:

“What’s the health value on the Player object?”
“Find all clickable elements in the scene”
“What’s the best locator strategy for this button?”

Device management:

“List connected iOS devices”
“Install and launch this APK on my Android device”
“Set up WDA for my iPhone”

Troubleshooting

`alttester` command not found

If running alttester returns a “command not found” error:

Restart your terminal or command prompt. The PATH update applied during installation only takes effect in new sessions. Close and reopen your terminal, then try again.
Add the CLI directory to your PATH manually if restarting does not help. The default installation path is .alttester/CLI/ inside your AltTester® data directory. If you changed the path during setup, use that directory instead.

On macOS/Linux, add the following line to your shell profile (e.g. ~/.zshrc or ~/.bashrc):
```
export PATH="$HOME/.alttester/CLI:$PATH"
```
On Windows, add the directory to your PATH environment variable via System Properties > Environment Variables.
Re-run the download from AltTester® Desktop Settings if the CLI binary is missing entirely.

Cannot connect to the game

Verify the game is running and instrumented with the AltTester® SDK
Check that the AltTester® server port matches (default: 13000)
If the game uses a secure WebSocket (wss://), pass --use-secure: alttester connect --use-secure
If testing on a mobile device, make sure port forwarding is set up (alttester android forward or network route to the device)
Try increasing the timeout: alttester connect --timeout 15

Daemon is stale or unresponsive

If alttester status hangs or reports a stale connection:

alttester disconnect
alttester connect

Object not found

Use alttester game-state to see what’s actually on screen
Check for typos in the object name
The object might not be loaded yet. Use alttester find MyObject --wait
Try a different locator strategy: --by PATH, --by TEXT, or --contains

macOS: MCP server not working when CLI is in a protected folder

On macOS, Apple’s TCC (Transparency, Consent, and Control) system restricts access to certain user folders — Desktop, Documents, and Downloads. If the AltTester® CLI is installed inside one of these directories, AI applications such as Claude Desktop or Cursor may be blocked from executing it, causing the MCP server to silently fail to start.

To fix this, move the CLI to a location outside these protected folders. You can change the installation path in AltTester® Desktop Settings and re-download the CLI from there.

iOS: WDA fails to build

Ensure you have a valid Apple Developer Team ID
Run alttester ios wda-setup --team-id YOUR_TEAM_ID before starting WDA
Check that Xcode command line tools are installed: xcode-select --install

Android: adb not found

Install Android SDK Platform Tools
Set ANDROID_HOME or ANDROID_SDK_ROOT environment variable, or add adb to your PATH

AltTester® CLI and AI Extension

Getting Started

Set up later from Settings

Command Reference

Global Options

Connection

connect

status

disconnect

apps

Find Objects

find

find-at-coordinates

get-all-elements

Input Actions

tap

click

press

key-down

key-up

swipe

scroll

move-mouse

touch

reset-input

Other Commands

get-text

set-text

scene

game-state

snapshot

screen-size

get-property

set-property

wait-for-property

get-time-scale

set-time-scale

Screenshot

screenshot

Other

run-tests

run-keyword

setup-project

docs

start-desktop

start-game

uninstall

update

iOS Device Management

ios devices / ios install / ios launch / ios uninstall

ios wda-setup / ios wda-start / ios wda-stop / ios wda-status / ios wda-find / ios wda-tap / ios wda-source

ios run

Android Device Management

android devices / android install / android launch / android uninstall

android forward / android clear-forward

android find / android tap / android source

android run

AltObject

Locator Strategies

Snapshots

Updating the CLI

AI Extension

Setting Up with Skills

What Are Skills?

Installing Skills

Choosing a Skill

Robot Skill (robot)

Helper Skill (helper)

Setting Up as MCP Server

Claude Desktop

VS Code with GitHub Copilot

Cursor

JetBrains IDEs (PyCharm, Rider, IntelliJ IDEA)

Windsurf

Claude Code

Common Workflows

Exploring a Game

Creating a Test Plan

Generating and Running Tests

Debugging Failed Tests

`connect`

`status`

`disconnect`

`apps`

`find`

`find-at-coordinates`

`get-all-elements`

`tap`

`click`

`press`

`key-down`

`key-up`

`swipe`

`scroll`

`move-mouse`

`touch`

`reset-input`

`get-text`

`set-text`

`scene`

`game-state`

`snapshot`

`screen-size`

`get-property`

`set-property`

`wait-for-property`

`get-time-scale`

`set-time-scale`

`screenshot`

`run-tests`

`run-keyword`

`setup-project`

`docs`

`start-desktop`

`start-game`

`uninstall`

`update`

`ios devices` / `ios install` / `ios launch` / `ios uninstall`

`ios wda-setup` / `ios wda-start` / `ios wda-stop` / `ios wda-status` / `ios wda-find` / `ios wda-tap` / `ios wda-source`

`ios run`

`android devices` / `android install` / `android launch` / `android uninstall`

`android forward` / `android clear-forward`

`android find` / `android tap` / `android source`

`android run`

Robot Skill (`robot`)

Helper Skill (`helper`)

`alttester` command not found