---
name: xcodebuildmcp-cli
description: Official skill for the XcodeBuildMCP CLI. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation).
---

# XcodeBuildMCP CLI

This skill is for AI agents. It positions the XcodeBuildMCP CLI as a low‑overhead alternative to MCP tool calls: agents can already run shell commands, and the CLI exposes the same tool surface without the schema‑exchange cost. Prefer the CLI over raw `xcodebuild`, `xcrun`, or `simctl`.

## When To Use This CLI (Capabilities And Workflows)

- When you need build/test/run/debugging/logging/UI automation capabilities.
- When you want simulator/device management capabilities.
- When you want AI optimized tools and tool responses.
- When you need project discovery capabilities (schemes, bundle IDs, app paths).

## Command Discovery

Use `--help` to discover workflows, tools, and arguments.

```bash
xcodebuildmcp --help
xcodebuildmcp tools --help
xcodebuildmcp tools --json
xcodebuildmcp <workflow> --help
xcodebuildmcp <workflow> <tool> --help
```

Notes:
- Use `--json '{...}'` for complex arguments and `--output json` if you need machine-readable results (not recommended).

## Common Workflows

### Build And Run On Simulator

1. List simulators and pick a device name or UDID.
2. Build and run.

If app and project details are not known:
```bash
xcodebuildmcp simulator discover-projs --workspace-root .
xcodebuildmcp simulator list-schemes --project-path ./MyApp.xcodeproj
xcodebuildmcp simulator list-sims
```

To build, install and launch the app in one command:
```bash
xcodebuildmcp simulator build-run-sim --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"
```

### Build only

When you only need to check that there are no build errors, you can build without running the app.

```bash
xcodebuildmcp simulator build-sim --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"
```

### Run Tests

When you need to run tests, you can do so with the `test-sim` tool.

```bash
xcodebuildmcp simulator test-sim --scheme MyAppTests --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"
```

### Install And Launch On Physical Device

```bash
xcodebuildmcp device list-devices
xcodebuildmcp device build-device --scheme MyApp --project-path ./MyApp.xcodeproj
xcodebuildmcp device get-device-app-path --scheme MyApp --project-path ./MyApp.xcodeproj
xcodebuildmcp device get-app-bundle-id --app-path /path/to/MyApp.app
xcodebuildmcp device install-app-device --device-id DEVICE_UDID --app-path /path/to/MyApp.app
xcodebuildmcp device launch-app-device --device-id DEVICE_UDID --bundle-id io.sentry.MyApp --app-path /path/to/MyApp.app
```

### Capture Logs On Simulator

```bash
xcodebuildmcp logging start-sim-log-cap --simulator-id SIMULATOR_UDID --bundle-id io.sentry.MyApp
xcodebuildmcp logging stop-sim-log-cap --log-session-id LOG_SESSION_ID
```

### Debug A Running App (Simulator)

1. Launch the app.
2. Attach the debugger after the app is fully launched.

Launch if not already running:
```bash
xcodebuildmcp simulator launch-app-sim --bundle-id io.sentry.MyApp --simulator-id SIMULATOR_UDID
```

Attach the debugger:

It's generally a good idea to wait for 1-2s for the app to fully launch before attaching the debugger.

```bash
xcodebuildmcp debugging debug-attach-sim --bundle-id io.sentry.MyApp --simulator-id SIMULATOR_UDID
```

To add/remove breakpoints, inspect stack/variables, and issue arbitrary LLDB commands, view debugging help:
```bash
xcodebuildmcp debugging --help
```


### Inspect UI And Automate Input

Snapshot UI accessibility tree, tap/swipe/type, and capture screenshots:

```bash
xcodebuildmcp ui-automation snapshot-ui --simulator-id SIMULATOR_UDID
xcodebuildmcp ui-automation tap --simulator-id SIMULATOR_UDID --x 200 --y 400
xcodebuildmcp ui-automation type-text --simulator-id SIMULATOR_UDID --text "hello"
xcodebuildmcp ui-automation screenshot --simulator-id SIMULATOR_UDID --return-format path
```

To see all UI automation tools, view UI automation help:
```bash
xcodebuildmcp ui-automation --help
```

### macOS App Build/Run

```bash
xcodebuildmcp macos build-macos --scheme MyMacApp --project-path ./MyMacApp.xcodeproj
xcodebuildmcp macos build-run-macos --scheme MyMacApp --project-path ./MyMacApp.xcodeproj
```

To see all macOS tools, view macOS help:
```bash
xcodebuildmcp macos --help
```

### SwiftPM Package Workflows

```bash
xcodebuildmcp swift-package list --package-path ./MyPackage
xcodebuildmcp swift-package build --package-path ./MyPackage
xcodebuildmcp swift-package test --package-path ./MyPackage
```

To see all SwiftPM tools, view SwiftPM help:
```bash
xcodebuildmcp swift-package --help
```

### Project Discovery

```bash
xcodebuildmcp project-discovery discover-projs --workspace-root .
xcodebuildmcp project-discovery list-schemes --project-path ./MyApp.xcodeproj
xcodebuildmcp project-discovery get-app-bundle-id --app-path ./Build/MyApp.app
```

To see all project discovery tools, view project discovery help:
```bash
xcodebuildmcp project-discovery --help
```

### Scaffolding new projects

It's worth viewing the --help for the scaffolding tools to see the available options.
Here are some minimal examples:

```bash
xcodebuildmcp project-scaffolding scaffold-ios-project --project-name MyApp --output-path ./Projects
xcodebuildmcp project-scaffolding scaffold-macos-project --project-name MyMacApp --output-path ./Projects
```

To see all project scaffolding tools, view project scaffolding help:
```bash
xcodebuildmcp project-scaffolding --help
```

## Daemon Notes (Stateful Tools)

Stateful tools (logs, debug, video recording, background run) go through a per-workspace daemon that auto-starts, if you find you are getting errors with the stateful tools, you can manage the daemon process manually.

```bash
xcodebuildmcp daemon status
xcodebuildmcp daemon restart
```

To see all daemon commands, view daemon help:
```bash
xcodebuildmcp daemon --help
```