Skip to content
Luotsi Luotsi

CLI Command Groups

Luotsi exposes a broad CLI surface, but most workflows still collapse into a handful of command families. Start with the family that matches the question you are trying to answer: which device, which transport, which workflow, or which artifact root.

Device and adb

Section titled “Device and adb”

Use these commands to discover devices, validate readiness, and inspect the host adb environment.

Terminal window
luotsi devices
luotsi doctor
luotsi device-status --device <serial>
luotsi lab inventory list
luotsi adb version
luotsi doctor --device <serial>

Without a selected device, doctor lists adb-visible devices and returns exact next commands. With --device or --device-query, it returns a readiness_plan with status, blockers, next_command, and recommended_commands, so the first-run report doubles as an operator/agent handoff. When a package-aware report is ready, next_command routes to discover first, followed by package preflight, inspect, screen-state, persisted quickstart handoff, scenario validation, run, and live view commands.

Also in this family:

  • lab status, lab doctor, lab plan, lab claim, lab leases, lab queue, lab release, lab extend, lab quarantine, lab quarantines, lab unquarantine, lab inventory list, lab inventory set, lab inventory clear
  • adb server-status, adb features, adb mdns check, adb reconnect offline, adb wait-for-device
  • wait-for-device, device-wait, preflight, screen-state

When the lab uses durable inventory, add --device-pool <pool> and --require-capabilities <csv> to lab status, lab plan, lab claim, or run so allocation cannot drift onto the wrong hardware class.

View and profiles

Section titled “View and profiles”

Use these when you want a live mirrored device session.

Terminal window
luotsi view --device <serial>
luotsi view setup --device <serial>
luotsi view-doctor --device <serial>
luotsi view --last
luotsi view --device <serial> --share-bind 0.0.0.0:9000
luotsi profile-list

Also in this family:

  • reconnect and reconnect --profile <name>
  • view --join-share <host:port> for observer sessions
  • --stats-interval-ms for JSONL cadence and --renderer-stats-interval-ms for renderer/title cadence
  • profile-delete --name <name> for saved view profiles

Wireless and port forwarding

Section titled “Wireless and port forwarding”

Use these when the transport itself is the problem or when the app under test needs a host or device socket.

Terminal window
luotsi wireless-scan
luotsi wireless-pair --endpoint <host:port> --code <code>
luotsi wireless-connect --service <name> --save-profile desk-wifi
luotsi forward --local tcp:8080 --remote tcp:8080
luotsi reverse --remote tcp:7000 --local tcp:7000

Use wireless for legacy Android TCP/IP mode over USB, and forward-list or reverse-list when you need to inspect existing adb plumbing.

App lifecycle

Section titled “App lifecycle”

Use these when you need to prepare the target app before a view session, scenario run, or manual diagnostic command.

Terminal window
luotsi start-app --device <serial> --package <app.id> --activity .MainActivity --wait
luotsi wait-for-activity --device <serial> --activity <pattern>
luotsi force-stop --device <serial> --package <app.id>
luotsi clear --device <serial> --package <app.id>

Also in this family:

  • start-uri for deep links and explicit intents
  • wait-for-not-activity when you need to prove the app left the foreground
  • grant-permission, revoke-permission, is-app-installed, list-installed-packages

Interaction, logs, and capture

Section titled “Interaction, logs, and capture”

Use direct commands when you need a one-shot action outside a scenario file.

Terminal window
luotsi wait-visible --device <serial> --text "Sign in"
luotsi tap --device <serial> --x 640 --y 360
luotsi logcat --device <serial> --tail 200
luotsi record --device <serial> --output capture.mp4

Direct commands are best when you need a single action, a host-side capture, or a quick sanity check before you codify the behavior into a scenario.

Telemetry and semantic waits

Section titled “Telemetry and semantic waits”

These commands rely on structured LUOTSI_DEVICE_TELEMETRY events from the app under test.

Terminal window
luotsi telemetry-tail --device <serial> --tail 200
luotsi telemetry-watch --device <serial> --timeout-sec 30
luotsi wait-step --device <serial> --step printing-succeeded
luotsi wait-action-ready --device <serial> --action sign-in

This family is strongest when the app under test emits structured LUOTSI_DEVICE_TELEMETRY lines and you need waits that survive UI churn.

Scenarios and replay

Section titled “Scenarios and replay”

Use scenario files when you want a repeatable run, and replay commands when you need to triage artifacts after the fact.

Terminal window
luotsi journey-intake init --output journey-intake.json --package <app.id> --device <serial> --write-markdown
luotsi journey-intake validate --file journey-intake.json
luotsi journey-intake draft-scenario --file journey-intake.json --output scenarios/from-journey.json
luotsi discover --device <serial> --package <app.id> --budget 5m
luotsi scenario-list --path scenarios
luotsi scenario-explain --file scenarios/smoke.json
luotsi run --path scenarios --output-dir ./artifacts/my-run --dry-run --include-tag smoke
luotsi run --path scenarios --device <serial> --report-junit junit.xml
luotsi artifacts list --artifacts ./artifacts
luotsi artifacts info ./artifacts/my-run
luotsi replay packet --artifacts ./artifacts/my-run
luotsi replay packet --artifacts ./artifacts/my-run --check
luotsi replay packet --last --artifacts ./artifacts
luotsi replay packet --last --artifacts ./artifacts --check
luotsi replay open --artifacts ./artifacts/my-run --dry-run
luotsi replay open --last --artifacts ./artifacts --dry-run
luotsi artifacts open ./artifacts/my-run
luotsi artifacts open --last --artifacts ./artifacts
luotsi artifacts pack ./artifacts/my-run --output my-run.zip --dry-run
luotsi artifacts pack ./artifacts/my-run --output my-run.zip
luotsi artifacts pack ./artifacts/my-run --output my-run-lab-safe.zip --redact lab-safe
luotsi artifacts verify my-run-lab-safe.zip --require-lab-safe --sha256 <digest>
luotsi artifacts info my-run-lab-safe.zip
luotsi artifacts intake my-run-lab-safe.zip --output ./artifacts/my-run --require-lab-safe --write-json --write-readme --sha256 <digest>
luotsi artifacts unpack my-run-lab-safe.zip --output ./artifacts/my-run --require-lab-safe --sha256 <digest>
luotsi replay summarize --artifacts ./artifacts/my-run
luotsi replay capsule --artifacts ./artifacts/my-run --write-readme --write-json
luotsi replay timeline --artifacts ./artifacts/my-run --failures
luotsi replay graph --artifacts ./artifacts/my-run --write-markdown
luotsi replay cluster --artifacts ./artifacts/ci-runs --write-markdown
luotsi replay search --artifacts ./artifacts/my-run --contains timeout
luotsi replay scenario-draft --artifacts ./artifacts/my-run --output scenarios/recovered.json --validate --write-markdown

Use journey-intake init when Android CLI Journey-style intent (a Journey objective; not an Android Intent object) needs a first-party Luotsi handoff file with review guardrails and next commands. Use journey-intake validate when that handoff needs a CI-friendly contract check before Luotsi scenario drafting. Use journey-intake draft-scenario when that valid intake should become a review-required evidence skeleton without touching a device.

Use discover when the app surface is not fully known yet and you want a real-device state map plus review-required JSON scenario candidates. Bound traversal with --budget, --max-actions, and --max-depth. Constrain tap selection with --allow-text, --deny-text, --deny-resource-id, and --deny-class. Discovery records the backtracks it uses to return through explored branches.

Use scenario-validate, scenario-explain, or run --dry-run before you execute device work.

Use artifacts list when you need to rediscover a recent run id. Use artifacts info when you want a non-mutating summary of one root or package zip; restored roots with an intake audit include compact status, share-safety, and SHA verification fields. Use replay packet or replay packet --last when you want the durable first-minute packet with run-summary.json, run-summary.md, and checkable triage commands. Use replay open or replay open --last after the packet when a human wants the replay-specific front door with next actions. Use artifacts open or artifacts open --last when you want the generic artifact browser. Use artifacts verify --require-lab-safe when you received a package and need a read-only manifest/SHA/redaction gate before unpacking. Use artifacts intake --require-lab-safe --write-json --write-readme --sha256 <digest> when you are ready to validate, restore, persist an intake audit, and get the exact packet-check command in one step.

Successful artifacts pack results recommend unpacking with --sha256. Lab-safe pack/info/verify handoffs preserve --require-lab-safe on unpack commands so CI or support can enforce the gate at extraction time. artifacts info <package.zip> validates the manifest, reports redaction metadata and SHA-256, and suggests checksum-verified unpack plus replay packet --check commands before broad replay without extracting files.

Reach for replay capsule when one artifact root failed. Use replay graph when you need selector/action/telemetry context. Use replay cluster when the same failure pattern is repeating across runs.

replay scenario-draft infers package and device provenance from trusted evidence when available. Adding --validate runs static validation and lets validated drafts surface concrete preflight and lab-claimed run handoff commands when the replay evidence names the target app and adb serial. Reopening the bundle with replay capsule promotes those ready handoff commands into recommended_next_steps.

Section titled “Related pages”

Pair this overview with the focused docs that explain the workflows behind each family: