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

--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.

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

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.

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).