CLI Commands

Complete reference for all sensorchaos commands and their options.

sensorchaos auth

Activate a license key and store it locally.

sensorchaos auth <key>

The key is validated against the SensorChaos license API. On success, it is written to ~/.sensorchaos/config.json and cached for 24 hours. Subsequent CLI invocations use the cached validation result and only re-check the API when the cache expires.

Arguments:

Argument	Description
<key>	Your SensorChaos license key (e.g. sc_live_... or sc_trial_...)

---

sensorchaos run

Run a single scenario against a connected device.

sensorchaos run <scenario> [options]

Arguments:

Argument	Description
<scenario>	Scenario identifier or path to a custom JSON file. Built-in scenarios use the form gnss/<name> or multi/<name> (e.g. gnss/gulf-spoofing-2026).

Options:

Option	Default	Description
-d, --device <id>	first detected	Device ID to target. For Android: ADB serial (from adb devices). For iOS: simulator UDID (from sensorchaos devices).
--agent	off	Connect to the in-process agent running inside the app on port 19847. Enables full sensor injection (GPS, IMU, barometer). On Android the port is forwarded via ADB automatically. On iOS simulator the port is accessible directly. On a real iOS device the port is forwarded via idb automatically — idb must be installed.
--report <path>	—	Write a JSON resilience report to the specified file path.
--assert-no-crash	off	Exit with code 1 if any critical findings are recorded during the scenario.
--assert-max-position-error-km <km>	—	Exit with code 1 if the maximum position error exceeds this threshold (in kilometres). Useful in CI.
--exit-code-on-fail	off	Exit with code 1 if any assertions fail.
--no-progress	off	Disable the progress bar (useful when capturing output in CI).

Examples:

# Run on the first available device
sensorchaos run gnss/urban-canyon

# Run with full sensor injection via the in-process agent
sensorchaos run gnss/gulf-spoofing-2026 --agent

# Target a specific Android emulator
sensorchaos run gnss/gulf-spoofing-2026 --device emulator-5554

# Target a specific iOS simulator
sensorchaos run gnss/gulf-spoofing-2026 --agent --device <simulator-udid>

# Fail if position error exceeds 5 km, write JSON report
sensorchaos run gnss/gulf-spoofing-2026 \
  --assert-max-position-error-km 5 \
  --report report.json \
  --exit-code-on-fail

# Run a custom scenario file
sensorchaos run ./my-scenarios/custom-spoof.json

Tip

Without --agent, the CLI injects GPS-only via platform fallbacks: Android emulators use ADB geo fix; iOS simulators use xcrun simctl location; real Android devices use the ADB helper APK via am broadcast. Multi-sensor scenarios always require --agent.

---

sensorchaos suite

Run multiple scenarios in sequence against a connected device.

sensorchaos suite --scenarios <ids> [options]

Options:

Option	Default	Description
--scenarios <ids>	required	Comma-separated list of scenario IDs or file paths.
-d, --device <id>	first detected	Device ID to target (same format as run).
--agent	off	Use the in-process agent for all scenarios in the suite.
--report <path>	—	Write a combined JSON report to the specified file path.
--assert-max-position-error-km <km>	—	Fail if any scenario’s position error exceeds this threshold.
--exit-code-on-fail	off	Exit with code 1 if any scenario has critical findings.

Examples:

# Run two GNSS scenarios back to back
sensorchaos suite --scenarios gnss/gulf-spoofing-2026,gnss/tunnel-transit

# Full suite with agent and CI assertions
sensorchaos suite \
  --scenarios gnss/gulf-spoofing-2026,multi/conflict-zone \
  --agent \
  --assert-max-position-error-km 10 \
  --exit-code-on-fail

---

sensorchaos record

Capture live agent injection in real time and emit a replayable scenario JSON file.

sensorchaos record [options]

record polls the agent’s status command at a configurable interval, collecting snapshots of every injected value (GPS fix, IMU, barometer). When stopped it writes a scenario JSON that, when replayed with sensorchaos run, reproduces the exact same injection sequence.

Options:

Option	Default	Description
-d, --device <id>	first detected	Device ID to target (same format as run).
--output <path>	recording-<timestamp>.json	Output file path.
--duration <s>	unlimited	Stop automatically after this many seconds.
--interval <ms>	1000	Polling interval. Must be ≥ 100 ms.
--name <name>	Recording <timestamp>	Scenario name written into the output file.

The command requires the agent to be running and reachable on port 19847. Only snapshots where at least one value changed are written as timeline keyframes, so the output file stays compact even for long recordings.

Examples:

# Record until Ctrl+C
sensorchaos record

# Record for 120 s, write to a specific file
sensorchaos record --duration 120 --output field-bug-repro.json

# Replay the recording
sensorchaos run ./field-bug-repro.json --agent

Tip

The typical workflow for reproducing a field bug: run the scenario that surfaced the bug with sensorchaos run ... --agent, then immediately run sensorchaos record alongside it in a second terminal. The recording captures exactly what was injected, giving you a minimal, shareable scenario file that reproduces the issue.

---

sensorchaos debug

Open a live browser-based visual debugger showing the injected GPS track and sensor values in real time.

sensorchaos debug [options]

debug connects to the running agent, starts a local HTTP + WebSocket server, and opens http://localhost:19848 in your default browser. The UI updates at 500 ms intervals.

Options:

Option	Default	Description
-d, --device <id>	first detected	Device ID to target (same format as run).
--port <port>	19848	Local port for the debugger UI.

UI features:

• Map — OpenStreetMap tiles at street level. When tiles are unavailable (offline or network blocked), falls back to a coordinate grid with lat/lng labels and a scale bar. Drag to pan, scroll to zoom.
• GPS track — injected positions drawn as a polyline with the oldest points faded. Current position shown as a pulsing dot with an accuracy circle sized to the actual reported accuracy.
• Sensor sidebar — live numeric readout for each active sensor (accelerometer, gyroscope, magnetometer, barometer) with per-axis colour coding and a scrolling sparkline.
• Status bar — connection state, current injected coordinates, satellite count, and elapsed time.

Examples:

# Open debugger for the first available device
sensorchaos debug

# Use a specific port
sensorchaos debug --port 8080

Tip

Run sensorchaos debug in one terminal and sensorchaos run ... --agent in another. The debugger reflects whatever the agent is currently injecting, so you can watch the GPS track move and sensor values change as the scenario progresses.

---

sensorchaos check

Run pre-flight checks on a connected device before running a scenario.

sensorchaos check [options]

Options:

Option	Default	Description
-d, --device <id>	first detected	Device ID to check.
--agent	off	Also verify the agent TCP port (19847) is reachable.

Checks performed on real Android devices:

1. Developer options enabled
2. ADB helper (dev.sensorchaos.adb) installed
3. Mock location permission granted to the ADB helper
4. (with --agent) Agent port reachable on 19847
5. (with --agent) Per-injector capability report from the agent:
   • Location injection (mock location permission confirmed from inside the app)
   • Sensor injection (hidden SensorManager API available on this Android version)

On iOS with --agent, checks 1–3 are skipped. The CLI connects to the agent directly (simulator) or via idb forward (real device) and reports the same capability breakdown, including barometer availability.

Each failing check prints a one-line fix instruction. Exits with code 1 if any check fails.

sensorchaos run calls this automatically on real Android devices (CLI-only mode) and bails early if setup is incomplete.

Tip

Run sensorchaos check --agent after installing the agent in your app to confirm the full injection chain is working before your first scenario. The capability report tells you exactly which sensor types will work on the target device.

---

sensorchaos devices

List all connected Android and iOS devices and simulators.

sensorchaos devices

Output shows each device ID, platform, model name, and online/offline state. Use the IDs shown here with the --device flag in run and suite.

---

sensorchaos list

List all built-in scenarios with their CLI paths and descriptions.

sensorchaos list [options]

Options:

Option	Description
--tag <tag>	Filter by tag (e.g. spoofing, jamming, logistics, defense, navigation, automotive, maritime, aviation)
--tier <tier>	Filter by license tier (indie, team, enterprise)
--json	Output as JSON (useful for scripting)

Examples:

# All logistics-relevant scenarios
sensorchaos list --tag logistics

# All defense scenarios as JSON
sensorchaos list --tag defense --json

# Only scenarios included in the Indie tier
sensorchaos list --tier indie

---

sensorchaos validate

Validate a scenario JSON file against the SensorChaos schema without running it.

sensorchaos validate <file>

Arguments:

Argument	Description
<file>	Path to the scenario JSON file to validate

Exits with code 0 on a valid scenario, 1 with detailed error messages on failure.

---

sensorchaos demo

Download the SensorChaos demo APK, install it on a connected Android device, and run the gnss/gulf-spoofing-2026 scenario against it.

sensorchaos demo [--device <serial>]

This is the fastest way to see SensorChaos in action without integrating the agent into your own app. The demo APK is a simple map app that displays injected positions in real time.

Note

The demo APK is for Android only. For iOS, use the sample app in agents/ios/SampleApp/.