elstar command reference
v1.0.3 — generated from the shipped binary's help output. Every command supports --json, --device, --no-color, --quiet.
brew install elstar-dev/elstar/elstar
curl -fsSL https://elstar.dev/install.sh | bash
Touch
elstar tap
Tap an element by label, identifier, or coordinates.
OVERVIEW: Tap an element by label, identifier, or coordinates.
USAGE: elstar tap [--json] [--device <device>] [--no-color] [--quiet] [<query-or-x>] [<y>] [--exact] [--role <role>] [--index <index>] [--wait] [--timeout <seconds>] [--dry-run]
ARGUMENTS:
<query-or-x> Element label/identifier, or X coordinate.
<y> Y coordinate (when <query-or-x> is an X coordinate).
OPTIONS:
--json Emit output as JSON instead of human-readable text.
--device <device> Target simulator UDID (default: booted device).
--no-color Disable colored output.
-q, --quiet Suppress informational output.
--exact Require exact label match instead of substring.
--role <role> Filter by AX role (Button, TextField, ...).
--index <index> When multiple elements match, pick this index.
(default: 0)
--wait Poll for the element until it appears.
--timeout <seconds> Wait timeout in seconds (with --wait). (default: 30)
--dry-run Print target without actually tapping.
--version Show the version.
-h, --help Show help information.elstar swipe
Swipe from one screen coordinate to another.
OVERVIEW: Swipe from one screen coordinate to another. USAGE: elstar swipe [--json] [--device <device>] [--no-color] [--quiet] <from-x> <from-y> <to-x> <to-y> [<duration-ms>] ARGUMENTS: <from-x> Start X coordinate. <from-y> Start Y coordinate. <to-x> End X coordinate. <to-y> End Y coordinate. <duration-ms> Gesture duration in milliseconds. (default: 300) OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --version Show the version. -h, --help Show help information.
elstar drag
Drag from one coordinate to another with an optional press-hold.
OVERVIEW: Drag from one coordinate to another with an optional press-hold. USAGE: elstar drag [--json] [--device <device>] [--no-color] [--quiet] <from-x> <from-y> <to-x> <to-y> [<hold-ms>] [<duration-ms>] ARGUMENTS: <from-x> Start X coordinate. <from-y> Start Y coordinate. <to-x> End X coordinate. <to-y> End Y coordinate. <hold-ms> Press-hold before moving, in ms. (default: 500) <duration-ms> Move duration in ms. (default: 300) OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --version Show the version. -h, --help Show help information.
elstar key
Press a keyboard key by HID usage code.
OVERVIEW: Press a keyboard key by HID usage code. USAGE: elstar key [--json] [--device <device>] [--no-color] [--quiet] <code> [<direction>] ARGUMENTS: <code> HID usage code (integer). <direction> Press direction: down or up. Omit for tap. OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --version Show the version. -h, --help Show help information.
elstar type
Type text into the focused first responder of the foreground app.
OVERVIEW: Type text into the focused first responder of the foreground app. USAGE: elstar type [--json] [--device <device>] [--no-color] [--quiet] <words> ... ARGUMENTS: <words> Text to type. Multiple args are joined with spaces. OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --version Show the version. -h, --help Show help information.
Inspect
elstar elements
List tappable elements on the current screen.
OVERVIEW: List tappable elements on the current screen.
USAGE: elstar elements [--json] [--device <device>] [--no-color] [--quiet] [--compact] [--id] [--role <role>]
OPTIONS:
--json Emit output as JSON instead of human-readable text.
--device <device> Target simulator UDID (default: booted device).
--no-color Disable colored output.
-q, --quiet Suppress informational output.
-c, --compact Compact JSON output (role/id/x/y only).
--id Only list elements that have an accessibility
identifier.
--role <role> Filter by AX role.
--version Show the version.
-h, --help Show help information.elstar state
Snapshot app + screen + elements + screenshot in one JSON call.
OVERVIEW: Snapshot app + screen + elements + screenshot in one JSON call.
USAGE: elstar state [--json] [--device <device>] [--no-color] [--quiet] [--screenshot <screenshot>] [--no-screenshot]
OPTIONS:
--json Emit output as JSON instead of human-readable text.
--device <device> Target simulator UDID (default: booted device).
--no-color Disable colored output.
-q, --quiet Suppress informational output.
--screenshot <screenshot>
Path to write screenshot PNG. (default:
/tmp/elstar-state.png)
--no-screenshot Skip the screenshot capture.
--version Show the version.
-h, --help Show help information.elstar ax
Dump the accessibility tree (or hit-test a point).
OVERVIEW: Dump the accessibility tree (or hit-test a point). USAGE: elstar ax [--json] [--device <device>] [--no-color] [--quiet] [--depth <depth>] [--point <point> ...] OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --depth <depth> Maximum tree depth. (default: 5) --point <point> Hit-test point: --point X Y. --version Show the version. -h, --help Show help information.
elstar screenshot
Capture a PNG screenshot of the simulator.
OVERVIEW: Capture a PNG screenshot of the simulator.
USAGE: elstar screenshot [--json] [--device <device>] [--no-color] [--quiet] [<path>]
ARGUMENTS:
<path> Output path for the PNG. (default:
/tmp/sim_screenshot.png)
OPTIONS:
--json Emit output as JSON instead of human-readable text.
--device <device> Target simulator UDID (default: booted device).
--no-color Disable colored output.
-q, --quiet Suppress informational output.
--version Show the version.
-h, --help Show help information.elstar uitest
Generate XCUITest code from the live AX tree, or record a live
OVERVIEW: Generate XCUITest code from the live AX tree, or record a live
session.
USAGE: elstar uitest [--json] [--device <device>] [--no-color] [--quiet] [--gen] [--live] [--objc] [--class-name <class-name>] [--label <label>] [--duration <duration>] [--bundle-id <bundle-id>]
OPTIONS:
--json Emit output as JSON instead of human-readable text.
--device <device> Target simulator UDID (default: booted device).
--no-color Disable colored output.
-q, --quiet Suppress informational output.
--gen Generate a full XCTestCase scaffold.
--live Record live taps/swipes into XCUITest code.
--objc Emit Objective-C instead of Swift.
--class-name <class-name>
Class name for generated tests. (default: AppUITests)
--label <label> Filter query map by element label.
--duration <duration> Live recording duration in seconds (0 = until
SIGINT). (default: 0)
--bundle-id <bundle-id> Bundle ID for --live (default: foreground app).
--version Show the version.
-h, --help Show help information.Simulator
elstar boot
Boot a simulator by name or UDID.
OVERVIEW: Boot a simulator by name or UDID. USAGE: elstar boot [--json] [--device <device>] [--no-color] [--quiet] <name-parts> ... ARGUMENTS: <name-parts> Device name or UDID. OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --version Show the version. -h, --help Show help information.
elstar shutdown
Shutdown the booted simulator.
OVERVIEW: Shutdown the booted simulator. USAGE: elstar shutdown [--json] [--device <device>] [--no-color] [--quiet] OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --version Show the version. -h, --help Show help information.
elstar devices
List available simulators.
OVERVIEW: List available simulators. USAGE: elstar devices [--json] [--device <device>] [--no-color] [--quiet] OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --version Show the version. -h, --help Show help information.
Debug
elstar net
Capture HTTP traffic from an iOS app.
OVERVIEW: Capture HTTP traffic from an iOS app. USAGE: elstar net [--json] [--device <device>] [--no-color] [--quiet] [<bundle-id>] [--attach] [--har <path>] [--no-body] [--timeout <seconds>] [--filter <text>] ARGUMENTS: <bundle-id> Bundle ID (auto-detected if omitted). OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --attach Attach to a running process instead of relaunching. --har <path> Write HAR file on exit. --no-body Suppress request/response bodies. --timeout <seconds> Stop after N seconds. --filter <text> Filter URLs by substring. --version Show the version. -h, --help Show help information.
elstar mock
Inject HTTP mocks into a running iOS app.
OVERVIEW: Inject HTTP mocks into a running iOS app.
USAGE: elstar mock [--json] [--device <device>] [--no-color] [--quiet] <subcommand>
OPTIONS:
--json Emit output as JSON instead of human-readable text.
--device <device> Target simulator UDID (default: booted device).
--no-color Disable colored output.
-q, --quiet Suppress informational output.
--version Show the version.
-h, --help Show help information.
SUBCOMMANDS:
routes Mock traffic from (pattern, response.json) pairs.
file Mock traffic from a routes.json file.
record Record live traffic into a directory instead of
mocking.
See 'elstar help mock <subcommand>' for detailed help.elstar vh
Dump the UIKit view hierarchy of a running app.
OVERVIEW: Dump the UIKit view hierarchy of a running app.
USAGE: elstar vh [--json] [--device <device>] [--no-color] [--quiet] <bundle-id> [--swiftui]
ARGUMENTS:
<bundle-id> Bundle ID of the running app.
OPTIONS:
--json Emit output as JSON instead of human-readable text.
--device <device> Target simulator UDID (default: booted device).
--no-color Disable colored output.
-q, --quiet Suppress informational output.
--swiftui Use SwiftUI _elements dump instead of UIKit
recursiveDescription.
--version Show the version.
-h, --help Show help information.elstar eval
Evaluate a Swift or ObjC expression in a running app.
OVERVIEW: Evaluate a Swift or ObjC expression in a running app. USAGE: elstar eval [--json] [--device <device>] [--no-color] [--quiet] <bundle-id> <expression> ... [--swift] ARGUMENTS: <bundle-id> Bundle ID of the running app. <expression> Expression to evaluate. OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --swift Evaluate as Swift instead of ObjC. --version Show the version. -h, --help Show help information.
elstar hot
Hot-reload a Swift file into the running simulator app.
OVERVIEW: Hot-reload a Swift file into the running simulator app.
Four shapes:
elstar hot <file> [--once] auto-detect foreground app
elstar hot --watch [dir] auto-detect + watch directory
elstar hot <bundleID> <file> [--once] explicit app + reload one
file
elstar hot <bundleID> --watch [dir] explicit app + watch
directory
elstar hot run <scheme> build instrumented + launch
(state-preserving)
USAGE: elstar hot [--json] [--device <device>] [--no-color] [--quiet] [<arg1>] [<arg2>] [--watch] [--once] [--project <project>] [--configuration <configuration>] [--no-watch]
ARGUMENTS:
<arg1> File, bundle ID, or watch directory depending on
flags.
<arg2> File (when arg1 is a bundle ID) or watch directory.
OPTIONS:
--json Emit output as JSON instead of human-readable text.
--device <device> Target simulator UDID (default: booted device).
--no-color Disable colored output.
-q, --quiet Suppress informational output.
--watch Watch a directory for changes (auto-discover if no
dir given).
--once Reload once and exit instead of watching.
--project <project> run: .xcodeproj path (auto-detected in the working
dir if omitted).
--configuration <configuration>
run: build configuration. (default: Debug)
--no-watch run: build and launch but don't watch for edits.
--version Show the version.
-h, --help Show help information.Automation
elstar wait
Wait for an element to appear on screen.
OVERVIEW: Wait for an element to appear on screen. USAGE: elstar wait [--json] [--device <device>] [--no-color] [--quiet] <query> [--exact] [--role <role>] [--timeout <timeout>] ARGUMENTS: <query> Element label or identifier to wait for. OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --exact Require exact label match instead of substring. --role <role> Filter by AX role. --timeout <timeout> Wait timeout in seconds. (default: 30) --version Show the version. -h, --help Show help information.
elstar assert
Assert that an element is present (or absent).
OVERVIEW: Assert that an element is present (or absent). USAGE: elstar assert [--json] [--device <device>] [--no-color] [--quiet] <query> [--exact] [--role <role>] [--exists] [--not-exists] ARGUMENTS: <query> Element label or identifier to check. OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --exact Require exact label match instead of substring. --role <role> Filter by AX role. --exists Assert the element exists (default). --not-exists Assert the element does NOT exist. --version Show the version. -h, --help Show help information.
System
elstar mcp
MCP server (run, install, remove, status).
OVERVIEW: MCP server (run, install, remove, status). USAGE: elstar mcp [--json] [--device <device>] [--no-color] [--quiet] <subcommand> OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --version Show the version. -h, --help Show help information. SUBCOMMANDS: install Install elstar MCP server into .mcp.json. remove Remove elstar MCP server from .mcp.json. status Show elstar MCP server install status. See 'elstar help mcp <subcommand>' for detailed help.
elstar hook
Manage Claude Code hooks.
OVERVIEW: Manage Claude Code hooks. USAGE: elstar hook [--json] [--device <device>] [--no-color] [--quiet] <subcommand> OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --version Show the version. -h, --help Show help information. SUBCOMMANDS: install Install elstar hooks into .claude/settings.json. remove Remove elstar hooks from .claude/settings.json. See 'elstar help hook <subcommand>' for detailed help.
elstar skills
Manage bundled Claude skills.
OVERVIEW: Manage bundled Claude skills. USAGE: elstar skills [--json] [--device <device>] [--no-color] [--quiet] <subcommand> OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --version Show the version. -h, --help Show help information. SUBCOMMANDS: install Install elstar skills. remove Remove elstar skills. list List bundled elstar skills. See 'elstar help skills <subcommand>' for detailed help.
elstar diagnose
Dump environment + state for bug triage.
OVERVIEW: Dump environment + state for bug triage. USAGE: elstar diagnose [--json] [--device <device>] [--no-color] [--quiet] [--out <out>] OPTIONS: --json Emit output as JSON instead of human-readable text. --device <device> Target simulator UDID (default: booted device). --no-color Disable colored output. -q, --quiet Suppress informational output. --out <out> Write the bundle to this file instead of stdout. --version Show the version. -h, --help Show help information.
License
elstar license
Manage your license.
Manage your license. elstar license status show license/trial status elstar license activate <key> activate license key elstar license deactivate release this machine's activation
elstar update
Check for and install the latest elstar release.
Check for and install the latest elstar release. elstar update
Developer
elstar doctor
Environment check: Xcode, simulators, private frameworks, PATH.
Environment check: Xcode, simulators, private frameworks, PATH. elstar doctor
elstar completions
Generate shell completions.
Generate shell completions. elstar completions [zsh|bash|fish]