@autifyhq/aximo-cli

CLI for the Autify Aximo API, built for coding agents. Every command returns a JSON envelope ({ok, data} or {ok: false, error}) so output pipes cleanly into scripts and other tools.

Install

npm i -g @autifyhq/aximo-cli

Quick Start

# 1. Configure credentials (interactive) — or set env vars, see Configuration below
aximo configure

# 2. Verify the connection
aximo health check

# 3. Run a desktop test session
aximo project list
aximo session create \
    --project-id PROJECT_ID \
    --title "Login test" \
    --prompt "Go to https://example.com and verify the page loads."

# 4. Poll session status
aximo session get SESSION_ID

Get your API key from Settings → API Keys in the Aximo dashboard.

Configuration

Each credential resolves independently: the value in $AXIMO_HOME/config.json (written by aximo configure) wins, then the environment variable, then the default.

| Variable | Required | Default | Notes | | ---------------- | -------- | -------------------------- | ------------------------------------------------------------ | | AXIMO_API_KEY | Yes | — | Organization API key | | AXIMO_BASE_URL | No | https://aximo.autify.com | Override for sandbox / self-hosted | | AXIMO_HOME | No | ~/.aximo | Data directory (config, device credentials, embedded Python) |

Set them interactively or pass flags — config is written to $AXIMO_HOME/config.json (mode 0600 where the OS supports it; Windows falls back to file ACLs), and an empty prompt keeps the existing value:

aximo configure                              # interactive prompts
aximo configure --base-url URL --api-key KEY # non-interactive

Or keep credentials out of a file (CI, ephemeral shells) with env vars:

export AXIMO_API_KEY=your-api-key
export AXIMO_BASE_URL=https://aximo-sbx.autify.dev   # optional, prod is the default

Credentials and device registrations are per-environment — to switch between production and sandbox (https://aximo-sbx.autify.dev), re-run aximo configure with the other --base-url.

Commands

Run aximo <command> --help for detailed usage. aximo schema [command.path] returns machine-readable argument introspection (e.g. aximo schema session.create).

| Command | Description | | ---------------------------- | ------------------------------------------------------- | | aximo configure | Save credentials to $AXIMO_HOME/config.json | | aximo health check | Check API reachability | | aximo project list | List organization projects | | aximo session create | Create and queue a test session | | aximo session get | Get session status | | aximo session save-as-case | Save a finished session as a reusable test case | | aximo case create | Create a test case | | aximo case delete | Delete a test case | | aximo plan create | Create a test plan | | aximo plan add-case | Add a case to a plan | | aximo plan remove-case | Remove a case from a plan | | aximo trigger case run | Trigger a dashboard-created test case | | aximo trigger case get | Get triggered case status | | aximo trigger plan run | Trigger a test plan | | aximo trigger plan get | Get plan run status | | aximo upload create | Create an upload slot for an APK/IPA | | aximo upload list | List previously uploaded apps | | aximo upload get | Poll upload processing status | | aximo upload put | Upload binary file to the slot | | aximo upload submit | Finalize upload and trigger processing | | aximo device list | List mobile devices from Device Farm | | aximo device setup | First-time BYOD onboarding (API + Python + register) | | aximo device register | Register this machine as a BYOD device | | aximo device connect | Start the BYOD agent and connect to the relay | | aximo device status | List your organization's BYOD devices | | aximo device ping | Check your BYOD device's server-side status | | aximo device doctor | Diagnose BYOD setup (env, Python, relay, status) | | aximo device logs | Show the BYOD agent log | | aximo device unregister | Remove a BYOD device server-side + clear local creds | | aximo device reset | Remove BYOD local state (Python, deps, credentials) | | aximo mobile list | List physically-connected phones (Android adb, iOS idb) | | aximo mobile setup | Install the Appium drivers used to drive phones | | aximo mobile doctor | Diagnose prerequisites (adb/idb, SDK/Xcode, driver) | | aximo mobile register | Register a connected Android phone or iPhone | | aximo mobile install | Install an app (.apk via adb, .ipa via idb) | | aximo mobile connect | Start managed Appium + open the tunnel for the phone | | aximo mobile unregister | Remove a local mobile device server-side + local creds | | aximo schema | Show CLI surface as JSON | | aximo mcp | Run a stdio MCP server for agents (see below) |

Mutating commands support --json '<raw body>' for direct OpenAPI payloads and --dry-run to preview requests without executing.

Health

aximo health check

Returns {ok: true, data: {status: "ok"}} when the API is reachable and your API key is valid.

Projects

aximo project list

Lists active workspaces in your organization. Grab the id to pass as --project-id for session creation.

Sessions

aximo session create --title <t> --prompt <p> --project-id <id> \
  [--platform ANDROID|IOS] [--model <m>] [--start-url <url>] \
  [--case-id <id>] [--tags <comma-separated>] \
  [--device-arn <arn>] [--device-name <name>] \
  [--upload-arn <arn>] [--upload-type ANDROID_APP|IOS_APP] \
  [--app-name <name>] [--bundle-id <id>] \
  [--json '<body>'] [--dry-run]

aximo session get <sessionId>

Desktop sessions default to platform=desktop, model=sonnet. Mobile sessions require both --device-arn and --upload-arn.

Test cases

aximo case create --project-id <id> --scenario <text> \
  [--type web|mobile|desktop] [--title <t>] [--description <d>] \
  [--format gherkin|markdown|plain_text] [--start-url <url>] \
  [--directory-id <id>] [--json '<body>'] [--dry-run]

aximo case delete <caseId> [--dry-run]

aximo session save-as-case <sessionId> \
  [--title <t>] [--type web|mobile|desktop] \
  [--scenario <text>] [--format gherkin|markdown|plain_text] \
  [--json '<body>'] [--dry-run]

case create returns a caseId you can run with aximo trigger case run. session save-as-case persists a finished session (terminal status, not yet linked to a case) as a reusable case, carrying over its scenario and run config. Cases created either way have API access enabled by default, so they are triggerable immediately. case delete permanently removes a case: it is dropped from any plans it belongs to, and past run sessions are kept but detached.

Test plans

aximo plan create --project-id <id> --title <t> [--description <d>] [--json '<body>'] [--dry-run]
aximo plan add-case    <planId> --case-id <caseId> [--json '<body>'] [--dry-run]
aximo plan remove-case <planId> <caseId> [--dry-run]

Build a runnable plan: plan create → plan add-case (repeat per case) → aximo trigger plan run. Plans created this way have API access enabled by default. Cases must belong to the same workspace as the plan.

Triggers (test cases and plans)

aximo trigger case run  <caseId> [...]
aximo trigger case get  <caseId> <sessionId>
aximo trigger plan run  <planId> [...]
aximo trigger plan get  <planId> <planRunId>

Triggers a test case or plan. API access must be enabled on the resource — on by default for cases/plans created via this CLI; for dashboard-created ones, enable it in the Aximo dashboard settings. trigger case run returns a sessionId you can poll; trigger plan run returns a per-case breakdown.

Uploads

aximo upload create --file-name <name> [--file-size <bytes>] [--platform ANDROID|IOS]
aximo upload put    <uploadId> --file <path>
aximo upload submit <uploadId>
aximo upload get    <uploadId>
aximo upload list   [--file-type ANDROID_APP|IOS_APP]

Typical flow: create → put (sends binary to the presigned URL) → submit → poll get until status=succeeded → extract uploadArn for mobile sessions. upload list auto-re-uploads expired Device Farm entries.

Schema

aximo schema               # all commands
aximo schema session.create # one command's arg schema

Machine-readable JSON view of the CLI surface — used by agent skills for discovery.

Device (BYOD — Bring Your Own Device)

The device commands let you register your own desktop as a test execution target. Aximo's agent controls it remotely over WebSocket to run tests against apps on your machine (useful when tests need access to your LAN, VPN, or a specific desktop environment).

Terminology note: aximo device list returns mobile devices from Device Farm; aximo device status returns BYOD devices you've registered. Don't confuse the two.

Prerequisites

• Node.js 20+, plus aximo-cli installed globally (see Install).
• An Aximo API key, configured via aximo configure or env vars.
• Active desktop session — the agent uses pyautogui for screenshots and input, so the screen must be unlocked and awake while tests run.
• Outbound WebSocket to port 443 — most corporate firewalls allow this; if yours doesn't, see Troubleshooting.

Python is not a prerequisite. On first connect (or via device setup), the CLI downloads a self-contained CPython build into $AXIMO_HOME/python/ (~35 MB download, ~130 MB installed) and installs the required packages. Your system Python is untouched.

First-time setup

One-command onboarding:

aximo device setup --name "My Windows PC"

This verifies API reachability, installs the embedded Python runtime, installs Python dependencies, and registers this machine. If the device is already registered locally, it skips registration and reports alreadyRegistered: true.

Or step-by-step, if you'd rather see each stage:

aximo health check                          # confirm credentials + connectivity
aximo device register --name "My Windows PC"  # creates server-side device, writes $AXIMO_HOME/device.json (0600)
aximo device connect                         # installs embedded Python on first run, then connects

On success, device connect prints something like:

Preparing Python environment...
Fetching embedded Python 3.12.13 (x86_64-pc-windows-msvc)...
Extracting...
Installing Python dependencies...
Python ready: C:\Users\<you>\.aximo\python\python.exe
Agent version: 8f3a1c04
Starting desktop agent, relay: wss://aximo.autify.com/devices/tunnel
Device "My Windows PC" is online. Press Ctrl+C to disconnect.

Subsequent connect runs skip the Python download and dep install — they re-run only when the server-hosted agent script changes.

Daily use

aximo device connect     # start the agent; keep the terminal open while tests run
# Ctrl+C to disconnect

Your device shows up in the Aximo UI under Settings → Devices with status online while connected. In the session form, pick your device as the execution target; Aximo routes the agent's actions through the tunnel to your machine.

Self-hosted servers (self-signed / custom CA)

On-prem Aximo servers often present a self-signed certificate (a private "Aximo CA"). BYOD has two TLS clients: the Node CLI (API calls) and the embedded Python desktop agent (the wss://…/devices/tunnel relay). They trust a custom CA differently, so configure both:

# 1. Save the server's CA on this machine (or copy aximo-ca.pem from your admin).
openssl s_client -connect YOUR_SERVER:8443 -showcerts </dev/null 2>/dev/null \
  | awk '/BEGIN CERTIFICATE/{i++} i==2{print} /END CERTIFICATE/{if(i==2) exit}' > ~/aximo-ca.pem

# 2. Point the CLI (Node) at it. Used for API calls AND auto-forwarded to the agent.
export NODE_EXTRA_CA_CERTS="$HOME/aximo-ca.pem"

aximo device connect

With NODE_EXTRA_CA_CERTS set, device connect automatically builds a combined trust store (the embedded Python's certifi roots plus your CA) and points the agent at it via SSL_CERT_FILE, so the relay connection verifies without extra steps.

To override the agent's trust store explicitly, set SSL_CERT_FILE yourself. It must include public roots and your CA — SSL_CERT_FILE replaces the entire store, so your CA alone would break any other TLS the agent does (browser launch, uploads):

PYBIN="$HOME/.aximo/python/bin/python3"
cat "$($PYBIN -m certifi)" ~/aximo-ca.pem > ~/.aximo/agent-ca-bundle.pem
export SSL_CERT_FILE="$HOME/.aximo/agent-ca-bundle.pem"

Persist whichever variables you use in your shell profile. Public-CA servers (e.g. aximo.autify.com) need none of this.

Managing devices

aximo device status                       # list YOUR BYOD devices, with online/offline + lastSeenAt
aximo device ping                         # server-side status for the locally registered device
aximo device ping --device-id DEVICE_ID   # same, for a specific device
aximo device unregister                   # delete server-side + clear local credentials
aximo device unregister --device-id DEVICE_ID  # unregister an orphaned device (no local creds)

device ping returns what the server knows, including lastSeenAgoSeconds and the HTTP round-trip latencyMs. It does not round-trip through the relay, so a passing ping tells you "the server thinks this device is online," not "the local agent is responding right now."

Re-registering

aximo device register refuses to overwrite an existing local registration. To move a registration to a different device name:

aximo device unregister                      # clean up the old one server-side
aximo device register --name "New Name"

If you've lost the original local credentials and need to delete the orphaned server-side device:

aximo device status                          # find its deviceId
aximo device unregister --device-id DEVICE_ID

Or use aximo device register --force — but that silently orphans the previous server-side device, so the explicit unregister + register path is safer.

Inspecting and resetting local state

aximo device logs                          # tail the last 50 lines of the agent log
aximo device logs --follow                 # stream new lines (not JSON-enveloped; human use)
aximo device logs --path                   # print the log file path and exit
aximo device logs --clear                  # truncate the log

aximo device doctor                        # run all checks: env, API, Python, relay, status
aximo device doctor --skip-relay           # skip WebSocket reachability probe
aximo device doctor --skip-api             # offline checks only

aximo device reset --python                # remove embedded Python + its cache
aximo device reset --deps                  # reinstall deps on next setup
aximo device reset --device                # delete local credentials (server-side stays; run `unregister` first to also delete there)
aximo device reset --all                   # wipe $AXIMO_HOME entirely

doctor is the first thing to run when anything's off — it covers the whole stack in one shot.

BYOD troubleshooting

"No API key configured." Either run aximo configure, or set AXIMO_API_KEY in your environment. Verify with echo $AXIMO_API_KEY (or echo $env:AXIMO_API_KEY on PowerShell).

"Authentication failed." Your device token is invalid (deleted server-side, or the server URL changed). Clean up and re-register:

aximo device unregister
aximo device register --name "My PC"
aximo device connect

"Disconnected. Reconnecting in Xs..." Normal for brief network blips — the agent retries with exponential backoff (1 s → 30 s max). If it keeps failing:

• Check your internet connection.
• Confirm AXIMO_BASE_URL is correct and reachable: aximo health check.
• Confirm outbound WebSocket on 443 isn't blocked: aximo device doctor runs a handshake probe.

Python download or pip install fails (corporate proxy). The embedded Python is fetched from github.com/astral-sh/python-build-standalone/releases and packages come from PyPI, so aximo device setup needs outbound access to both. On a network that only reaches the internet through a proxy, set the standard proxy variables — the CLI, pip, and the desktop agent all honor them:

# macOS / Linux
export HTTPS_PROXY=http://your-proxy:port
export HTTP_PROXY=http://your-proxy:port

# Windows (PowerShell)
$env:HTTPS_PROXY = "http://your-proxy:port"
$env:HTTP_PROXY  = "http://your-proxy:port"

Loopback and a private-range AXIMO_BASE_URL (e.g. an on-prem 172.30.x.x server) are always reached directly, so you don't have to list them in NO_PROXY. If your proxy performs TLS interception, also point NODE_EXTRA_CA_CERTS at the proxy's CA so the download's certificate verifies.

If the proxy cannot reach GitHub at all, ask your network team to allow-list both github.com and its release-asset CDN release-assets.githubusercontent.com — the download redirects from the former to the latter, so allow-listing only github.com is not enough.

To retry from a clean slate: aximo device reset --python && aximo device setup.

Device shows online, but tests fail on screenshot / click. Your screen is locked or the session is inactive. pyautogui needs an active desktop session.

macOS: actions seem to do nothing. System Settings → Privacy & Security → Accessibility and Screen Recording — both need to be granted to the terminal (or the Python binary that spawned).

Linux: "missing: scrot, xclip". aximo device doctor flags this when the tools aren't on PATH. Install via your package manager (apt install scrot xclip on Debian/Ubuntu).

Windows: coordinates off / scrolling too fast or too slow. The agent disables DPI-awareness and uses a calibrated scroll amount — if you still see mismatches, run aximo device doctor and share the output.

Environment & file layout

| Path | Mode | Purpose | | --------------------------------- | ---- | -------------------------------------------------------- | | $AXIMO_HOME/config.json | 0600 | CLI credentials (from aximo configure) | | $AXIMO_HOME/device.json | 0600 | BYOD registration + device token | | $AXIMO_HOME/agent/remote.py | 0644 | Python agent (server-synced) | | $AXIMO_HOME/agent/manifest.json | 0644 | Version + sha256 of cached agent files | | $AXIMO_HOME/python/ | — | Embedded CPython runtime | | $AXIMO_HOME/remote.log | — | Agent log (rotate/clear via aximo device logs --clear) |

Default $AXIMO_HOME is ~/.aximo on macOS/Linux, %USERPROFILE%\.aximo on Windows. Override via the AXIMO_HOME env var.

Devices are registered per-environment (see Configuration) — a device registered against sandbox can't connect to production and vice versa.

Mobile (local Android phone or iPhone)

The mobile commands let you register a physically-connected Android phone or iPhone as an Aximo device and drive it locally, over the same gateway tunnel as desktop BYOD. Aximo's agent controls the phone through a CLI-managed Appium server — UiAutomator2 for Android, XCUITest for iOS — useful for running mobile tests against your own handset instead of a Device Farm device.

iOS is macOS-only and needs Xcode + an Apple Developer account. Driving a physical iPhone goes through Appium's XCUITest driver, which builds and code-signs a WebDriverAgent (WDA) runner onto the device. That requires macOS, Xcode, an Apple Developer Team ID, and a WDA bundle id backed by a valid provisioning profile — set via the AXIMO_IOS_* env vars below. Android has no such requirement, so iOS setup is heavier; everything after setup (register → connect → run) works the same on both platforms.

Terminology note: aximo mobile list shows phones plugged into this machine; aximo device list (under Device / BYOD) returns mobile devices from AWS Device Farm. Don't confuse the two.

Prerequisites

• Node.js 20+, plus aximo-cli installed globally (see Install).
• An Aximo API key, configured via aximo configure or env vars.
• A USB-connected phone:
  • Android — USB debugging enabled and authorized — see Enable USB debugging on the phone.
  • iOS — Developer Mode enabled (Settings → Privacy & Security) and the computer trusted.
• On the machine that runs aximo mobile connect:
  • Android — adb and the Android SDK, with ANDROID_HOME set — see Set up your computer (Android).
  • iOS — macOS with Xcode + command line tools, idb, and the AXIMO_IOS_* signing env vars — see Set up your computer (iOS).

The Appium server is bundled with the CLI; aximo mobile setup installs the UiAutomator2 (Android) and/or XCUITest (iOS) driver — you don't install or manage Appium yourself.

Set up your computer (Android)

You only need adb and the Android SDK on the machine running aximo mobile connect. Appium delegates to adb, and its UiAutomator2 driver needs the SDK (even though adb is already on PATH).

macOS

# Option A — standalone platform-tools (just adb):
brew install --cask android-platform-tools
# Option B — full Android Studio (also installs the SDK):
brew install --cask android-studio

# Point ANDROID_HOME at the SDK (Android Studio's default location shown):
echo 'export ANDROID_HOME="$HOME/Library/Android/sdk"' >> ~/.zshrc
echo 'export PATH="$PATH:$ANDROID_HOME/platform-tools"'  >> ~/.zshrc
source ~/.zshrc

Linux

# Debian/Ubuntu — adb from the distro (or download platform-tools from Google):
sudo apt-get install -y android-tools-adb
# Install the SDK via Android Studio or sdkmanager, then export its path:
echo 'export ANDROID_HOME="$HOME/Android/Sdk"' >> ~/.bashrc
echo 'export PATH="$PATH:$ANDROID_HOME/platform-tools"' >> ~/.bashrc
source ~/.bashrc

Windows

• Install Android Studio (bundles the SDK + platform-tools), or download the standalone SDK Platform-Tools zip from Google.
• Set ANDROID_HOME to the SDK path (e.g. %LOCALAPPDATA%\Android\Sdk) and add %ANDROID_HOME%\platform-tools to PATH via System Properties → Environment Variables.

aximo mobile doctor auto-detects the SDK at the standard locations above, so ANDROID_HOME is optional when you use the defaults — but setting it explicitly is the most reliable. Confirm adb works with adb version.

Set up your computer (iOS)

iOS local devices are macOS-only (Appium's XCUITest driver delegates to Xcode). You need Xcode, idb, and the signing env vars.

# 1. Xcode + command line tools (XCUITest builds WebDriverAgent with them):
xcode-select --install          # or install Xcode from the App Store, then: sudo xcodebuild -license accept

# 2. idb — discovers connected iPhones and installs .ipa builds:
brew tap facebook/fb && brew install idb-companion
pipx install fb-idb             # or: pip install fb-idb

# 3. Signing config for WebDriverAgent (required for a physical iPhone):
export AXIMO_IOS_TEAM_ID="ABCDE12345"     # your Apple Developer Team ID (developer.apple.com/account → Membership)
# Optional overrides (sensible defaults shown):
export AXIMO_IOS_SIGNING_ID="Apple Development"
export AXIMO_IOS_WDA_BUNDLE_ID="com.facebook.WebDriverAgentRunner"
# Optional: reuse a prebuilt WDA to skip per-session rebuilds:
# export AXIMO_IOS_DERIVED_DATA_PATH="$HOME/Library/Developer/Xcode/DerivedData/WebDriverAgent-xxxx"

AXIMO_IOS_TEAM_ID is the load-bearing setting: the XCUITest driver uses it (with the signing id and WDA bundle id) to build and sign WebDriverAgent so it can run on the device. The WDA bundle id must be associated with a valid provisioning profile under that team. Run aximo mobile doctor --platform ios to confirm Xcode, idb, and the signing config are all present.

Already set up Autify's MobileLink? The CLI also reads MobileLink's names as fallbacks — XCODE_TEAM_ID, XCODE_SIGN_ID, WDA_BUNDLE_ID — so an existing host needs no reconfiguration. AXIMO_IOS_* takes precedence when both are set.

First connect to a physical iPhone is slow: Xcode builds and installs WebDriverAgent (a minute or two). If the build fails on signing, open WebDriverAgent.xcodeproj in Xcode once, pick your team, and let it auto-manage signing — or set AXIMO_IOS_DERIVED_DATA_PATH to a prebuilt WDA.

Enable USB debugging on the phone

Exact labels vary by manufacturer and Android version, but the flow is:

1. Unlock Developer options — open Settings → About phone and tap Build number seven times until you see "You are now a developer".
2. Turn on USB debugging — open Settings → System → Developer options and enable USB debugging.
3. Connect and authorize — plug the phone into your computer with a data-capable USB cable, then tap Allow on the "Allow USB debugging?" prompt on the phone (tick "Always allow from this computer" to skip it next time).
4. Verify the computer sees it:

   adb devices        # or: aximo mobile list

   The phone should appear in state device. unauthorized → re-accept the prompt on the phone; offline → re-plug the cable and unlock the screen. Emulators are not supported — connect a physical phone.

Keep the phone unlocked the first time you run a session: the initial command installs Appium's UiAutomator2 helper and creates the automation session on the device.

First-time setup

aximo mobile setup                          # installs the Appium driver(s) for your platform(s)
aximo mobile doctor                         # checks tooling / drivers / bundled server
# Limit to one platform if you only test on one:
aximo mobile setup  --platform ios          # installs only the XCUITest driver
aximo mobile doctor --platform ios          # checks Xcode / idb / signing config

setup installs the Appium driver(s) — UiAutomator2 for Android, XCUITest for iOS — then prints what (if anything) is still missing. doctor is the first thing to run when anything's off: for Android it reports adb and the Android SDK; for iOS it reports xcrun/Xcode, idb, and your AXIMO_IOS_TEAM_ID signing config — alongside the bundled Appium server and driver — and exits non-zero if a required check fails.

Registering and connecting

aximo mobile list                                            # see connected phones (adb serials / iOS udids)

# Android:
aximo mobile register --name "My Pixel" --platform android   # --platform defaults to android
# iOS:
aximo mobile register --name "My iPhone" --platform ios      # targets the single connected iPhone

aximo mobile connect                                         # starts managed Appium + opens the tunnel
# Ctrl+C to disconnect

register writes credentials to $AXIMO_HOME/mobile-devices/<deviceId>.json (mode 0600). It targets the single connected phone by default — pass --serial (Android) or --udid (iOS) to pick a specific one when several are attached. connect re-checks prerequisites, starts the managed Appium server, and opens the tunnel; it runs until Ctrl+C. If you have more than one registered phone, pass --device-id to choose which to connect.

Once connected, create a mobile session in Aximo targeting this local device — the agent routes its actions through the tunnel to the phone over Appium.

Testing your own app

Unlike Device Farm, a local phone runs the apps already installed on it. To test your own build, install it first:

aximo mobile install --app ./app-debug.apk    # Android: adb install -r
aximo mobile install --app ./MyApp.ipa         # iOS: idb install (the .ipa must be signed for the device)

Then create the session with the app's bundle id / package name as --bundle-id — the agent launches it on startup before the test begins:

# Android:
aximo session create --platform ANDROID --user-device-id DEVICE_ID --bundle-id com.example.app \
  --project-id PROJECT_ID --title "Smoke" --prompt "Sign in and open settings"
# iOS:
aximo session create --platform IOS --user-device-id DEVICE_ID --bundle-id com.example.MyApp \
  --project-id PROJECT_ID --title "Smoke" --prompt "Sign in and open settings"

Managing devices

aximo mobile unregister                       # remove the locally registered device (server-side + local creds)
aximo mobile unregister --device-id DEVICE_ID # target a specific device when several are registered

Flags reference

| Command | Flags | | ------------------------- | ---------------------------------------------------------------------------------------------------- | | aximo mobile list | (none) | | aximo mobile setup | --platform android \| ios (optional; installs both drivers by default) | | aximo mobile doctor | --platform android \| ios (optional; checks both by default) | | aximo mobile register | --name <name> (required), --platform android \| ios (default android), --serial/--udid | | aximo mobile install | --app <path-to-.apk\|.ipa> (required), --platform android \| ios (inferred), --serial/--udid | | aximo mobile connect | --device-id <id> (required only if multiple devices are registered) | | aximo mobile unregister | --device-id <id> (defaults to the locally registered device) |

MCP server

aximo mcp runs a Model Context Protocol server over stdio, exposing your recorded sessions, screenshots, and test cases to MCP-capable agents (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, …). The motivating use: let an agent read a finished session and generate a Playwright spec without you piping JSON between commands.

It reuses the same credentials as every other command, so run aximo configure (or set AXIMO_API_KEY) first.

Claude Code — one command:

claude mcp add aximo -- aximo mcp

Other clients — point them at the aximo mcp stdio command. Claude Desktop, Cursor, and Windsurf use the mcpServers key:

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

VS Code (Copilot agent mode) uses the same entry under a servers key in .vscode/mcp.json.

The server exposes 16 tools: 10 read-only ones for inspecting sessions and cases (aximo_get_session_timeline is the load-bearing one for Playwright export) plus 6 that author content (create and delete cases, create plans, save a session as a case). See the MCP reference for per-client config paths, the full tool table, the Playwright export prompt, and a no-client smoke test.

Agent Skills

Ships with an agent skill. Once installed, the agent discovers commands via aximo schema and follows workflows in skills/aximo-cli/.

npx skills add autifyhq/aximo-cli

See commands reference and workflows for the agent-oriented docs.

Contributing

Requirements

• mise

Preparation

pnpm install
pnpm run cli -- health check

Release Process

Automated via release-please:

1. Merge commits to main with Conventional Commit messages
2. release-please creates/updates a Release PR with CHANGELOG.md
3. Merge the Release PR to publish a GitHub Release and npm package