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.
For a first session with the CLI, see Using the AltTester® CLI.
Commands#
Connection commands: commands that connect the CLI to an app on AltTester® Server, and list the apps there.
Finding objects: commands that find objects in the app. They return AltObjects.
Input actions: commands that tap, click, type, swipe and scroll in the app.
Game state and properties: commands that read and change text, scenes, properties and time scale, and save the game state or a screenshot.
Tests, setup and updates: commands that run tests, set up a test project, start AltTester® Desktop or the app, and update or remove the CLI.
iOS devices: commands that manage iOS devices: install and launch the app, and use WebDriverAgent for native elements.
Android devices: commands that manage Android devices: install and launch the app, set up port forwarding, and work with native elements.
Global Options#
These options can be used with any command.
Name |
Required |
Description |
|---|---|---|
|
No |
AltTester® server host address. The default value is: |
|
No |
AltTester® server port. The default value is: |
|
No |
Output mode: |
|
No |
Session name. Required when more than one session is live at the same time. Defaults to the only live session for routing; on |
Locator Strategies#
The --by option controls how objects are matched. Available strategies:
Strategy |
Description |
|---|---|
|
Matches by object name. This is the default strategy. |
|
Matches by hierarchy path using XPath syntax (e.g. |
|
Matches by the object’s instance ID. |
|
Matches by Unity/Unreal tag. |
|
Matches by rendering layer. |
|
Matches by the text content of the object. |
|
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
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 |
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 |
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. |
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).