CLI

Direct terminal access to every XcodeBuildMCP tool. Use it from scripts, CI, manual checks, or from coding agents that have shell access and want to compose, pipe, or script tool calls. Long-running operations stream live progress to stdout so callers get immediate feedback instead of blocking until the whole operation finishes.

Synopsis#

xcodebuildmcp <workflow> <tool> [options]

Each tool takes --help for flag details:

xcodebuildmcp simulator build --help

Top-level commands#

Run xcodebuildmcp --help for the full list.

Passing arguments#

# As flags
xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj

# As JSON (useful for complex nested options)
xcodebuildmcp simulator build --json '{"scheme":"MyApp","projectPath":"./MyApp.xcodeproj"}'

# Output format
xcodebuildmcp simulator list --output json

Session defaults auto-fill#

If your project has .xcodebuildmcp/config.yaml with sessionDefaults set, the CLI fills matching flags automatically:

# .xcodebuildmcp/config.yaml
schemaVersion: 1
sessionDefaults:
  scheme: MyApp
  projectPath: ./MyApp.xcodeproj
  simulatorName: iPhone 17 Pro

# Before: flags on every invocation
xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj

# Now: flags come from session defaults
xcodebuildmcp simulator build

This also works with named profiles for monorepos. Use --profile <name> to override the active profile for a single call. See Session Defaults → Named profiles.

Common recipes#

Build for an iOS simulator#

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

Build and run in one step#

xcodebuildmcp simulator build-and-run \
  --scheme MyApp \
  --project-path ./MyApp.xcodeproj

Run XCTests with pre-resolved test cases and live progress#

xcodebuildmcp simulator test --json '{
  "workspacePath": "./MyApp.xcworkspace",
  "scheme": "MyApp",
  "simulatorName": "iPhone 17 Pro",
  "progress": true,
  "extraArgs": ["-only-testing:MyAppTests"]
}'

Record a simulator video#

Useful for bug reports, demos, and agent-run UI flows. Video capture runs through the daemon as a stateful session.

xcodebuildmcp simulator record-video \
  --simulator-id <UDID> \
  --output-path ./session.mp4

Streaming output and live progress#

Long-running tool calls (builds, tests, video recording, debugging sessions) emit progress in real time. The calling shell, script, or agent sees continuous activity instead of waiting for the whole operation to finish. Even between semantic milestones, raw subprocess stdout and stderr stream as the underlying tool emits them, which acts as a continuous liveness signal during long operations.

What you get depends on --output:

• text (default): human-readable progress lines stream to stdout as they happen. Build phases, test pass / fail, raw subprocess output, and runtime status messages all appear live.
• jsonl: one NDJSON event per fragment. Same content as text mode in a structured shape that agents and scripts can parse line by line. Each event has a kind (for example build, test, transcript, infrastructure) and a fragment field describing what happened.
• json: does not stream. The CLI waits for the tool to reach its terminal state, then emits a single structured final result.

For agents driving long operations through the shell, jsonl is usually the right choice: the calling agent can react to events as they arrive (surface a test failure the moment it appears, abort a build that has gone past a budget, forward live progress to the user). text is best for humans and for agents that only need to confirm the call is alive while it runs.

See Output Formats for the envelope and event shapes.

Per-workspace daemon#

Some XcodeBuildMCP tools need to keep state between commands (for example log capture, video recording, LLDB debugging, and background Swift Package runs). To do that, XcodeBuildMCP uses a background process.

XcodeBuildMCP auto-starts a small scoped background process (a daemon) the first time one of those tools runs. That daemon survives between CLI invocations, so follow-up commands can continue the same stateful session.

Lifecycle and scope:

• Auto-start: starts on the first stateful tool call. No manual setup required.
• Auto-shutdown: stops after 10 minutes of idle time.
• Workspace scoping: each daemon is scoped per workspace. If .xcodebuildmcp/config.yaml exists, XcodeBuildMCP uses that file's project location to identify the workspace. If not, it uses your current directory.

Daemon commands#

xcodebuildmcp daemon status
xcodebuildmcp daemon start
xcodebuildmcp daemon stop
xcodebuildmcp daemon restart
xcodebuildmcp daemon list
xcodebuildmcp daemon list --json
xcodebuildmcp daemon logs

Reference details:

• Socket path: ~/.xcodebuildmcp/daemons/<workspace-key>/daemon.sock
• Workspace identity key: <workspace-key> is derived from the workspace root path.

Troubleshooting the daemon#

# See logs in the foreground
xcodebuildmcp daemon start --foreground

# Extend startup timeout
export XCODEBUILDMCP_STARTUP_TIMEOUT_MS=10000

# Socket permission issues
chmod 700 ~/.xcodebuildmcp
chmod -R 700 ~/.xcodebuildmcp/daemons

CLI vs MCP mode#

Both share the same tool implementations.