elstar command reference
v1.0.8 — generated from the shipped binary's help output. Every command supports --json, --device, --no-color, --quiet.
brew tap elstar-dev/elstar brew trust --cask elstar-dev/elstar/elstar 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>] [--edge <edge>]
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.
--edge <edge> Screen edge the gesture starts from
(top|left|bottom|right). Physical devices only: it is
what makes a drag a system gesture (Home, App
Switcher) instead of a scroll. Simulators ignore it.
(values: top, left, bottom, right; default: none)
--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>] [--edge <edge>]
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.
--edge <edge> Screen edge the gesture starts from
(top|left|bottom|right). Physical devices only: it is
what makes a drag a system gesture (Home, App
Switcher) instead of a scroll. Simulators ignore it.
(values: top, left, bottom, right; default: none)
--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> ... [--layout <layout>] [--paste]
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.
--layout <layout> Keyboard layout to resolve characters against, as a
Text Input Source id (com.apple.keylayout.Danish).
Defaults to the Mac's current layout. Physical
devices only — HID carries key positions, and the
device applies the layout.
--paste Deliver the text via the device pasteboard instead of
keystrokes. Exact for any character, but iOS raises a
paste-consent alert you must accept. Physical devices
only.
--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 screens
List the device's displays and show which one holds the app.
OVERVIEW: List the device's displays and show which one holds the app. USAGE: elstar screens [--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 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.
Apps
elstar install
Install an .app bundle on the simulator.
OVERVIEW: Install an .app bundle on the simulator. USAGE: elstar install [--json] [--device <device>] [--no-color] [--quiet] <path> ARGUMENTS: <path> Path to .app bundle. 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 launch
Launch an installed app by bundle ID.
OVERVIEW: Launch an installed app by bundle ID. USAGE: elstar launch [--json] [--device <device>] [--no-color] [--quiet] <bundle-id> [<extra-args> ...] ARGUMENTS: <bundle-id> Bundle identifier. <extra-args> Extra arguments forwarded to the 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. --version Show the version. -h, --help Show help information.
elstar terminate
Terminate a running app.
OVERVIEW: Terminate a running app. USAGE: elstar terminate [--json] [--device <device>] [--no-color] [--quiet] <bundle-id> ARGUMENTS: <bundle-id> Bundle identifier. 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 uninstall
Uninstall an app.
OVERVIEW: Uninstall an app. USAGE: elstar uninstall [--json] [--device <device>] [--no-color] [--quiet] <bundle-id> ARGUMENTS: <bundle-id> Bundle identifier. 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 apps
List installed apps.
OVERVIEW: List installed apps. USAGE: elstar apps [--json] [--device <device>] [--no-color] [--quiet] [--all] 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. --all Include system apps. --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 [<options>] [<bundle-id>]
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.
--body-output <body-output>
Export raw bodies into a new private directory;
requires --no-redact.
--curl-output <curl-output>
Write quoted cURL requests to a new local file
without executing them.
--no-body Suppress request/response bodies.
--timeout <seconds> Stop after N seconds.
--filter <text> Filter URLs by substring.
--no-redact Show credentials, cookies, API keys, card numbers and
e-mail addresses as sent. By default they are masked
in the output and in the HAR.
--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 Dump recorded SwiftUI view data (launch app with
SWIFTUI_VIEW_DEBUG=287).
--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.Notifications
elstar push
Manage push notification permissions.
OVERVIEW: Manage push notification permissions. USAGE: elstar push [--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: grant Grant push notification permission. revoke Revoke push notification permission. list List push registrations. send Deliver a notification (simctl push). See 'elstar help push <subcommand>' for detailed help.
elstar notifications
List the notifications currently posted, with their title and body.
OVERVIEW: List the notifications currently posted, with their title and body. USAGE: elstar notifications [--json] [--device <device>] [--no-color] [--quiet] [<bundle-id>] ARGUMENTS: <bundle-id> Only this app's notifications. 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.
Privacy
elstar privacy
Grant, revoke, or reset privacy permissions.
OVERVIEW: Grant, revoke, or reset privacy permissions. USAGE: elstar privacy [--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: grant Grant a privacy permission. revoke Revoke a privacy permission. reset Reset a privacy permission. See 'elstar help privacy <subcommand>' for detailed help.
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.
elstar location
Set or clear simulator location.
OVERVIEW: Set or clear simulator location. USAGE: elstar location [--json] [--device <device>] [--no-color] [--quiet] <lat> [<lon>] ARGUMENTS: <lat> Latitude, or 'clear' to reset. <lon> Longitude. 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.
License
elstar license
Manage your license.
Manage your license. elstar license status show license 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
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 native coding-agent hooks.
OVERVIEW: Manage native coding-agent 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 native post-edit hooks for a coding tool. remove Remove elstar hooks for a coding tool. 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.
elstar feedback
Send a bug report or idea to the elstar team.
OVERVIEW: Send a bug report or idea to the elstar team.
Bundles your message with the output of `elstar diagnose` (toolchain, simulator
state, recent crashes — your home directory is redacted) and, if you have a
license, the key so we can reply. Interactive runs show the report and ask
before
sending. Nothing is ever sent without this command.
USAGE: elstar feedback [--json] [--device <device>] [--no-color] [--quiet] <message> [--kind <kind>] [--expected <expected>] [--actual <actual>] [--command <command>] [--no-diagnose] [--dry-run] [--yes]
ARGUMENTS:
<message> What happened, or what you'd like to see.
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.
--kind <kind> bug | idea | praise | other (values: bug, idea,
praise, other; default: other)
--expected <expected> What you expected to happen.
--actual <actual> What happened instead.
--command <command> The elstar command this is about, e.g. "elstar tap
Save --wait".
--no-diagnose Send the message only, without the diagnose bundle.
--dry-run Print the report that would be sent and exit.
-y, --yes Send without asking (required when stdin is not a
terminal).
--version Show the version.
-h, --help Show help information.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]