@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

The CLI resolves each credential independently in this order:

1. Value in $AXIMO_HOME/config.json (written by aximo configure)
2. Environment variable
3. Default (for base URL only: https://aximo.autify.com)

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

Using aximo configure

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

The interactive flow prompts first for the base URL (empty → keep existing, else falls back to the Aximo default), then for the API key (empty → keep existing; errors if nothing is saved). Config is written to $AXIMO_HOME/config.json with mode 0600. To change sandbox/prod, re-run aximo configure and enter a new URL.

Using environment variables

If you'd rather keep credentials out of a file (CI, ephemeral shells), set env vars:

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

# Windows (PowerShell, persistent)
[Environment]::SetEnvironmentVariable("AXIMO_API_KEY", "your-api-key", "User")
[Environment]::SetEnvironmentVariable("AXIMO_BASE_URL", "https://aximo-sbx.autify.dev", "User")

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 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 schema | Show CLI surface as JSON |

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.

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 dashboard-created test cases or plans. API access must be enabled in the Aximo dashboard settings. trigger case run returns a sessionId you can poll; trigger plan run returns 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.

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; packages come from PyPI. Behind a proxy:

# macOS / Linux
~/.aximo/python/bin/python3 -m pip config set global.proxy http://your-proxy:port

# Windows
%USERPROFILE%\.aximo\python\python.exe -m pip config set global.proxy http://your-proxy:port

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.

Sandbox vs production

# Sandbox
aximo configure --base-url https://aximo-sbx.autify.dev --api-key <sbx-key>

# Production (default)
aximo configure --base-url https://aximo.autify.com --api-key <prod-key>

Registrations are per-environment — a device registered against sandbox can't connect to production and vice versa.

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