CLI Toolchain (emx)
The Emuluxe CLI (emx) is a professional terminal interface designed to bridge your local development environment with our high-fidelity cloud hardware foundry. It automates local tunneling, hardware fingerprinting, and session management with zero configuration.
Installation
Option 1: Zero-Install (Recommended)
Run it directly without installing anything permanently:
npx @emuluxe/cli start https://your-site.com
Option 2: Global Install
Access Emuluxe anywhere with the emx command:
npm install -g @emuluxe/cli
Authentication
Option 1: One-Click Command (Recommended)
- Navigate to your Integrations Settings in the Emuluxe dashboard.
- Scroll to the CLI Authentication section.
- Click Generate Auth Command to get a pre-configured command.
- Copy and run the command in your terminal.
Option 2: Manual Setup
-
Obtain Token: You can find your secure API token in the Settings -> Integrations section of your Emuluxe dashboard.
-
Authenticate: Set your CLI authentication token:
emx auth your_secure_token -
Login: Alternatively, run the login command to open the dashboard:
emx login
Core Commands
emx devices
List all available device profiles with their hardware IDs and plan restrictions.
Example:
emx devices
emx network-profiles
List all available network profiles with bandwidth, latency, and plan restrictions.
Example:
emx network-profiles
emx init
Initialize Emuluxe in the current project with default settings.
--device, -d <id>: Default device ID (Default:iphone-15-pro-max)--network, -n <id>: Default network profile ID (Default:no-throttle)
Example:
emx init -d pixel-8-pro -n 4g
emx start [url]
Launch a high-fidelity simulation session.
url: The target URL (Default: auto-detected from package.json orhttp://localhost:3000).--device, -d <id>: Override the default hardware profile for this session.--network, -n <id>: Network profile ID (e.g.,no-throttle,3g,4g,5g). Default:no-throttle.--landscape, -L: Start in landscape mode instead of portrait.
Example: Starting a session with specific device and network
emx start http://localhost:8080 -d iphone-15-pro-max -n 4g -L
[!NOTE]
emxautomatically initializes an encrypted Local Tunnel relative to your target URL, allowing our cloud devices to securely access your local server. It also performs intelligent port discovery by reading yourpackage.jsonscripts to guess the correct port.
emx set-device <id>
Sets your preferred default hardware profile.
emx set-network <id>
Sets your preferred default network profile.
emx rotate
Rotate the device orientation in the IDE (toggles between Portrait and Landscape).
emx screenshot
Capture a screenshot of the current simulation in the IDE.
--type, -t <type>: Screenshot type (Default:SITE). Options:SITE,DEVICE,FULL,TAB. Note: Pro plan required for types other thanSITE.
Continuous Integration (emx ci)
emx ci is the only CLI command that can fail a build. It reads
.emuluxerc.json, captures every check on every configured device, and asks
Emuluxe to compare each capture against its stored baseline. It exits 1 only
when the rendering actually changed.
emx ci
Run the checks described by .emuluxerc.json in the repository root.
--update-baseline: Record this run's captures as the new baseline.--dry-run: List the checks that would run, without capturing.--json: Print the verdict and results as JSON.--repo <owner/name>: Override the repository (default:$GITHUB_REPOSITORY).--branch <name>: Override the branch (default:$GITHUB_HEAD_REF).
Repository, branch, commit and pull-request number are read from the GitHub environment when they are not passed explicitly.
.emuluxerc.json
{
"version": 1,
"checks": [
{
"name": "home",
"url": "${EMULUXE_TARGET_URL}/",
"devices": ["iphone-15", "pixel-8"],
"failOn": "regression",
"maxDiffPercent": 0.5
}
]
}
version: Must be1.checks[]: 1 to 50 entries.name: The baseline is keyed by it, so renaming a check re-baselines it.url: May contain${ENV_VAR}references, which is how a preview URL is passed without committing it.devices[]: 1 to 20 device ids per check.failOn:regression(default) fails the build on a visual change;noneonly reports it.maxDiffPercent: Share of differing pixels tolerated before a capture counts as changed. Default0.5.
Both .emuluxerc.json and emuluxe.ci.json are recognised.
Baselines
emx ci --update-baseline
Until a baseline exists for a check, that check reports no baseline and
cannot fail the build - a missing reference is reported in the pull request
rather than silently passing. A baseline is keyed by repository, branch, check
name and device, and follows the account's team when it has one, so one member's
--update-baseline updates the reference everyone is judged against.
Exit codes
| Code | Meaning |
|---|---|
0 | Passed - a verdict was formed, and it was clean |
1 | Regression - a verdict was formed, and the rendering changed |
2 | Configuration - bad invocation or an invalid .emuluxerc.json |
3 | Access or quota - fix the account, not the code |
4 | Environment - no browser, no network, platform unreachable |
An unreachable platform, a missing Chrome and an exhausted allowance never exit
1, because a check that goes red for reasons unrelated to your code gets
switched off.
GitHub
Copy docs/github-action/emuluxe-ci-gate.yml from the CLI repository to
.github/workflows/. The captures run on your own runner - the only machine that
can reach a preview deployment or localhost - while the comparison is central,
so two branches cannot disagree about what "unchanged" means.
Installing the Emuluxe GitHub App additionally reports the verdict as a check run named Emuluxe CI and keeps a single comment on the pull request, edited on each push rather than repeated. The comment lists every check and links to the report where each capture sits beside its baseline.
If you sign in to Emuluxe with GitHub and the App is already installed on an account or organisation you can reach, the connection is picked up automatically - including an install that was made before your Emuluxe account existed. Otherwise the install is linked when GitHub redirects you back to Settings → Integrations → GitHub & CI.
- A capture that could not be compared closes the check as neutral, which
never blocks a merge; the step still exits
4so the reason is in the log. - Re-run on the check re-compares the captures already stored for that commit against the current baselines. It does not re-capture.
- If nothing reports within 30 minutes the check is closed as neutral with an explanation, so a repository that installed the App without adding a workflow cannot deadlock its pull requests.
Allowance
Checks are counted individually: one check is one page on one device. Pro includes 500 CI checks per billing cycle, Enterprise is unlimited, and Free plans do not include CI checks at all. The allowance resets with the billing cycle, every run prints how much is left, and a run that would exceed it is refused before anything is captured rather than being judged in part.
App Mode Commands (emx app)
These commands drive a real native app rather than a URL. The agent runs on your machine and communicates with a simulator, emulator, or connected phone; your app binary is never uploaded. See the App Mode Setup Guide for prerequisites.
emx app doctor
Check every prerequisite - Node, full Xcode and licence, iOS simulator runtime,
simctl, Android platform-tools, Java, the automation driver, and free disk -
printing an exact fix for each failure.
--json: Machine-readable output. Exit code is0only when all checks pass, so it is safe to gate CI on it.
emx app devices
List the device profiles you can launch an App Mode session on.
--platform <ios|android>: Restrict to one platform.--json: Machine-readable output.
emx app build
Register an app binary with Emuluxe and receive a build id.
--android --apk <path>: Use an.apkyou already built.--ios --simulator: Print thexcodebuildinvocation to run for a simulator build. Device builds require code signing and are out of scope for App Mode.
emx app run
Start a session and stream the device into the Emuluxe frame.
--build, -b <build-id>: The build to launch (required).--device, -d <device-id>: The device profile to use.--driver <maestro|appium|xcuitest|espresso|manual>: Automation driver. Defaults tomaestro.--flow <path>: A Maestro flow (or equivalent) to drive the app.--manual: Explore interactively. Mutually exclusive with--flow.--json: Machine-readable output, including the newsessionId.
emx app logs
Show recent device and application log lines.
--session, -s <session-id>: Session to read (required).--follow, -f: Keep tailing as new lines arrive.
emx app status
Report the current session state, frame count, step count, and provenance.
emx app end
Close a session and produce a report.
--session, -s <session-id>: Session to close (required).--verdict <passed|failed>: Record the outcome so an abandoned run can never be mistaken for a green one.
Plan Awareness
Plan Awareness
The CLI is plan-aware and enforces restrictions based on your Emuluxe plan:
- Free Plan: Limited to Free-tier devices and
SITE(viewport) screenshots only - Pro Plan: Access to all devices and all screenshot types (TAB, DEVICE, SITE, FULL)
When using emx devices or emx network-profiles, the CLI will indicate which items are available on your current plan and which require Pro.
Instant Auto-Launch
The Emuluxe CLI features a robust IDE detection engine. When you run emx start, it automatically identifies your active coding environment and triggers the Simulation Panel instantly.
Supported IDEs:
- Antigravity: Native detection via
APP_NAME. - Cursor: Native detection via
VSCODE_ICON_KEYand bundle IDs. - Windsurf: Native detection via bundle ID
com.exafunction.windsurf. - VS Code: Native detection via
TERM_PROGRAM.
Configuration
Emuluxe stores global configuration in ~/.emuluxe-cli-nodejs/config.json.
| Key | Description | Default |
|---|---|---|
token | Encrypted API License Token | null |
defaultDevice | Fallback hardware profile | iphone-15-pro-max |
defaultNetwork | Default network profile | no-throttle |
Full Example Workflow
Follow this sequence to launch your first high-fidelity simulation:
-
Authenticate:
emx auth your_token_here -
Bridge to the Foundry:
emx start http://localhost:3000 -
Result:
- The CLI opens a public HTTPS tunnel for your local server so the foundry can reach it, and prints the URL.
- Instant Trigger: The session automatically opens in your active IDE (Antigravity, Cursor, Windsurf, or VS Code).
- Physical Rendering: The mobile frame is instantly rendered, pointing to your local code.
Next, explore the REST API Reference.