CLI Reference

Device Finder (df) provides a comprehensive command-line interface for device discovery and management.

Entry point

df [COMMAND] [OPTIONS]

Run without a command to launch interactive TUI mode:

df                  # Interactive device browser

Commands

list

Display all detected devices in a formatted table.

df list [OPTIONS]

Options:

Option	Description
`--platform <ios\|android\|web>`	Filter by platform
`--verbose`	Show detailed device information
`--json`	Output as JSON array

Examples:

# List all devices
df list

# List only iOS simulators
df list --platform ios

# List Android with verbose details
df list --platform android --verbose

# JSON output for scripting
df list --json

Terminal output:

PLATFORM NAME                 TYPE            STATUS       ID
-------------------------------------------------------------
iOS      iPhone 17 Pro        Simulator       Shutdown     7754174C-C8D6-4248-BB30-A6EE9539C63E
iOS      iPhone 17 Pro Max    Simulator       Shutdown     EE230FBC-8126-41C2-8526-7E4F615EB6A6
iOS      iPhone 16 Pro        Simulator       Shutdown     589413D1-CCAC-4950-A968-83348F5BCF05
iOS      iPhone 16            Simulator       Shutdown     B52873B1-6C52-41C9-8941-5E81CDC00DA4

JSON output shape:

[
  {
    "id": "589413D1-CCAC-4950-A968-83348F5BCF05",
    "name": "iPhone 16 Pro",
    "platform": "ios",
    "type": "Simulator",
    "status": "Shutdown",
    "os_version": "18.2",
    "model": null,
    "udid": "589413D1-CCAC-4950-A968-83348F5BCF05"
  }
]

find

Search devices by name, ID, or model.

df find <QUERY> [OPTIONS]

Options:

Option	Description
`--json`	Output as JSON object

Examples:

# Find all iPhones
df find "iPhone"

# Find specific emulator
df find "emulator-5554"

# JSON output
df find "Pixel" --json

Exit codes:

0: Device(s) found
3: No matching device

JSON output shape:

{
  "query": "iPhone",
  "found": true,
  "devices": [ { ...device objects... } ]
}

info

Show detailed information for a specific device.

df info <DEVICE_ID> [OPTIONS]

Options:

Option	Description
`--json`	Output as JSON object

Examples:

# Show device details
df info "7754174C-C8D6-4248-BB30-A6EE9539C63E"

# JSON output
df info "7754174C-C8D6-4248-BB30-A6EE9539C63E" --json

Terminal output:

Device Details
========================================
ID: 7754174C-C8D6-4248-BB30-A6EE9539C63E
Name: iPhone 17 Pro
Platform: iOS
Type: Simulator
Status: Shutdown
OS Version: 26.2
UDID: 7754174C-C8D6-4248-BB30-A6EE9539C63E

Exit codes:

0: Device found
3: Device not found

launch

Boot or launch a device.

df launch <DEVICE_ID> [OPTIONS]

Options:

Option	Description
`--json`	Output as JSON object

Examples:

# Launch iOS simulator
df launch "ABC123DEF456"

# Launch Android emulator
df launch "emulator-5554"

# JSON output for automation
df launch "device-id" --json

Exit codes:

0: Launch initiated
1: Launch failed

JSON output shape:

{
  "action": "launch",
  "device_id": "device-id",
  "status": "initiated",
  "message": "Device launch initiated"
}

install

Install an app or bundle on a device.

df install <DEVICE_ID> <BUNDLE_PATH> [OPTIONS]

Options:

Option	Description
`--json`	Output as JSON object

Examples:

# Install app on device
df install "device-id" "/path/to/app.ipa"

# Install on Android
df install "emulator-5554" "/path/to/app.apk"

# JSON output
df install "device-id" "/path/to/app" --json

Exit codes:

0: Installation initiated
1: Installation failed

JSON output shape:

{
  "action": "install",
  "device_id": "device-id",
  "bundle": "/path/to/bundle",
  "status": "initiated",
  "message": "App installation initiated"
}

connect

Establish connection to a device.

df connect <DEVICE_ID> [OPTIONS]

Options:

Option	Description
`--json`	Output as JSON object

Examples:

# Connect to wireless device
df connect "192.168.1.100:5555"

# Connect to USB device
df connect "device-serial"

# JSON output
df connect "device-id" --json

Exit codes:

0: Connection initiated
1: Connection failed

Exit Codes

Device Finder uses standardized exit codes for automation:

Code	Meaning
`0`	Success (device found, action executed, etc.)
`1`	Error (invalid input, tool not available, etc.)
`3`	Not found (for `find` and `info` commands)

JSON Output

All commands support --json for machine-readable output:

# List devices as JSON
df list --json

# Find with JSON
df find "query" --json

# Get device details as JSON
df info "device-id" --json

# Action commands return JSON status
df launch "device-id" --json

JSON output can be piped to tools like jq:

# Get device IDs
df list --json | jq -r '.[].id'

# Get connected devices only
df list --json | jq '.[] | select(.status == "Connected")'

# Count devices by platform
df list --json | jq 'group_by(.platform) | map({platform: .[0].platform, count: length})'

Configuration

Device Finder reads optional config from ~/.config/itamiforge/device-finder/config.toml:

[platforms]
# Filter devices by platform on startup
default_filter = ["ios", "android"]

# Exclude specific devices from listings
exclude_devices = ["old-simulator"]

[tools]
# Override tool paths if they're not in PATH
adb_path = "/usr/local/bin/adb"
xcrun_path = "/Applications/Xcode.app/Contents/Developer/usr/bin/xcrun"
emulator_path = "/Users/varunv/Library/Android/sdk/emulator/emulator"

Create the config directory:

mkdir -p ~/.config/itamiforge/device-finder

Scripting Examples

Get all device IDs

df list --json | jq -r '.[].id'

Boot all shutdown iOS simulators

df list --platform ios --json | \
  jq -r '.[] | select(.status == "Shutdown") | .id' | \
  while read -r id; do xcrun simctl boot "$id"; done

Check if a specific device exists

df find "iPhone 17 Pro" --json | jq -e '.found'
# true → exit 0, false → exit 3

Monitor device count changes

#!/bin/bash
prev=0
while true; do
  count=$(df list --json | jq 'length')
  [ "$count" -ne "$prev" ] && echo "$(date): $prev → $count devices" && prev=$count
  sleep 5
done

CLI Reference

CLI Reference

Entry point

Commands

list

find

info

launch

install

connect

Exit Codes

JSON Output

Configuration

Scripting Examples

Get all device IDs

Boot all shutdown iOS simulators

Check if a specific device exists

Monitor device count changes

See Also

On this page