# Iosctl

> Use this skill when building, launching, testing, inspecting, or proving native iOS Simulator apps with the agent-first `iosctl` CLI. Triggers include iOS Simulator proof runs, Xcode build/test loops, screenshot receipts, semantic UI tapping, accessibility-tree inspection, and replacing brittle MCP-only iOS workflows with CLI-first workflows.

- Skill: `danielgwilson/iosctl` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add danielgwilson/iosctl`
- Raw SKILL.md: https://api.skillmd.com/api/skills/danielgwilson/iosctl/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: danielgwilson (https://skillmd.com/u/danielgwilson)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/danielgwilson/iosctl

---


# iosctl

Use `iosctl` for native iOS Simulator build/run/proof loops.

Default stance:

- Prefer the `iosctl` CLI over MCP-only iOS helper servers.
- Prefer `--json` for agent work.
- Treat MCP as optional transport, not source of truth.
- Prefer first-party Apple tools through `iosctl` before third-party abstractions.
- Prefer accessibility trees and identifiers before screenshot vision.
- Do not claim the app works unless there is a receipt, screenshot path, or result artifact.
- Do not pass secrets as command-line arguments.

## skills.sh Package Shape

This skill is published from the nested path `skills/iosctl/SKILL.md`. Do not depend on a root
`SKILL.md`; Vercel's `skills` CLI lets a shallower `SKILL.md` shadow nested skills.

Install the skill with:

```bash
npx -y skills add -g danielgwilson/iosctl --skill iosctl
```

Use it without installing with:

```bash
npx -y skills use danielgwilson/iosctl@iosctl
```

## Command Resolution

Use `iosctl` when it is already available on `PATH`. If it is missing and Node.js is available,
prefer the published package for one-off agent runs:

```bash
npx -y iosctl@latest doctor --json
```

Only ask the user to install globally when repeated local use is expected:

```bash
npm i -g iosctl
```

## Sanity Checks

Start with:

```bash
iosctl doctor --json
iosctl devices --json
```

If `iosctl` is missing from `PATH`, use the published package for the same checks:

```bash
npx -y iosctl@latest doctor --json
npx -y iosctl@latest devices --json
```

For local development, use the repository checkout:

```bash
npm install
npm run build
npm link
```

## Proof Loop

Use:

```bash
iosctl proof-run \
  --project App.xcodeproj \
  --scheme App \
  --bundle com.example.app \
  --device "iPhone 17 Pro" \
  --json
```

Expected artifacts:

- `.iosctl/runs/<run-id>/receipt.json`
- `.iosctl/runs/<run-id>/summary.md`
- build log or result path
- app log path
- screenshot path
- optional UI tree path

If proof-run fails, inspect the returned `error.artifact` first. It should point at either `receipt.json` or the failing command log.

Fallback manually in this order only when the CLI cannot complete:

1. `iosctl doctor --json`
2. `iosctl devices --json`
3. direct `xcodebuild` build with explicit DerivedData and result paths
4. direct `xcrun simctl boot/install/launch`
5. direct `xcrun simctl io ... screenshot`
6. store commands and artifacts in a run directory

## Semantic UI

Use semantic UI commands for app navigation:

```bash
iosctl ui snapshot --device <UDID> --json
iosctl ui find --text "Book appointment" --json
iosctl ui tap --text "Book appointment" --json
iosctl ui type --text-field "Ask anything..." --value "Can you help with scheduling?" --json
iosctl ui swipe --direction up --json
```

`ui snapshot` stores the full raw accessibility tree and normalized element list under `.iosctl/ui/<snapshot-id>/`. Use those artifacts when stdout is capped.

If the CLI cannot read the accessibility tree, use direct `idb ui describe-all --nested --json` before screenshot vision.

## Contract Essentials

- With `--json`, stdout must be exactly one JSON object.
- Progress belongs on stderr.
- Exit codes:
  - `0` success
  - `1` operation failed
  - `2` invalid input, missing capability, or user action required
  - `3` safety refusal
- Common error codes:
  - `MISSING_TOOL`
  - `COMMAND_FAILED`
  - `INVALID_INPUT`
  - `SAFETY_REFUSAL`
  - `NOT_IMPLEMENTED`
  - `XCODE_UNAVAILABLE`
  - `SIMULATOR_UNAVAILABLE`
  - `DESTINATION_UNAVAILABLE`
  - `APP_NOT_FOUND`
  - `BUNDLE_LAUNCH_FAILED`
  - `UI_TREE_UNAVAILABLE`
  - `UI_ELEMENT_NOT_FOUND`
  - `TIMEOUT`

## Safety

- Never commit `.iosctl/` run artifacts unless explicitly sanitized.
- Never paste full app logs, screenshots, or UI trees into public docs without review.
- Never pass API keys or auth tokens as CLI arguments.
- Treat screenshots and app logs as local private artifacts by default.
- Use synthetic examples in docs and tests.