Skip to content

Latest commit

 

History

History
268 lines (187 loc) · 6.71 KB

CLI.md

File metadata and controls

268 lines (187 loc) · 6.71 KB

XcodeBuildMCP CLI

xcodebuildmcp is a unified command-line interface that provides both an MCP server and direct tool access via a first-class CLI.

Use xcodebuildmcp CLI to invoke tools or start the MCP server by passing the mcp argument.

Installation

# Install globally
npm install -g xcodebuildmcp@beta

# Or run via npx
npx xcodebuildmcp@beta --help

Quick Start

# List available tools
xcodebuildmcp tools

# View CLI help
xcodebuildmcp --help

# View tool help
xcodebuildmcp <workflow> <tool> --help

# Run interactive setup for .xcodebuildmcp/config.yaml
xcodebuildmcp setup

Tool Options

Each tool supports --help for detailed options:

xcodebuildmcp simulator build --help

Common patterns:

# Pass options as flags
xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj

# Pass complex options as JSON
xcodebuildmcp simulator build --json '{"scheme": "MyApp", "projectPath": "./MyApp.xcodeproj"}'

# Control output format
xcodebuildmcp simulator list --output json

Examples

Build and Run Workflow

# Discover projects
xcodebuildmcp simulator discover-projects

# List schemes
xcodebuildmcp simulator list-schemes --project-path ./MyApp.xcodeproj

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

# Boot simulator
xcodebuildmcp simulator boot --simulator-name "iPhone 17 Pro"

# Install and launch
xcodebuildmcp simulator install --simulator-id <UDID> --app-path ./build/MyApp.app

xcodebuildmcp simulator launch-app --simulator-id <UDID> --bundle-id io.sentry.MyApp

# Or... build and run in a single command
xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj

Log Capture Workflow

# Start log capture
xcodebuildmcp logging start-simulator-log-capture --simulator-id <UDID> --bundle-id io.sentry.MyApp

> Log capture started successfully. Session ID: 51e2142a-1a99-442a-af01-0586540043df.

# Stop and retrieve logs
xcodebuildmcp logging stop-simulator-log-capture --session-id <SESSION_ID>

Testing

# Run all tests
xcodebuildmcp simulator test --scheme MyAppTests --project-path ./MyApp.xcodeproj

# Run with specific simulator
xcodebuildmcp simulator test --scheme MyAppTests --simulator-name "iPhone 17 Pro"

For a full list of workflows and tools, see TOOLS-CLI.md.

Configuration

The CLI respects the same configuration as the MCP server:

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

enabledWorkflows:
  - simulator
  - project-discovery

See CONFIGURATION.md for the full schema.

To create/update config interactively, run xcodebuildmcp setup.

Environment Variables

Variable Description
XCODEBUILDMCP_SOCKET Override socket path for all commands
XCODEBUILDMCP_DAEMON_IDLE_TIMEOUT_MS Daemon idle timeout in ms (default 600000, set 0 to disable)
XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS Disable session defaults

CLI vs MCP Mode

Feature CLI (xcodebuildmcp <tool>) MCP (xcodebuildmcp mcp)
Invocation Direct terminal MCP client (Claude, etc.)
Session state Stateless direct + daemon for stateful tools In-process
Use case Scripts, CI, manual AI-assisted development
Configuration Same config.yaml Same config.yaml

Both share the same underlying tool implementations.

Per-Workspace Daemon

The CLI uses a per-workspace daemon architecture only when needed:

  • Stateless tools run directly in the CLI process.
  • Stateful tools route through the daemon (auto-started as needed).
  • Dynamic xcode-ide bridge tools are a special-case daemon-backed path for persistent bridge sessions.

How It Works

  • Workspace identity: The workspace root is determined by the location of .xcodebuildmcp/config.yaml, or falls back to the current directory.
  • Socket location: Each daemon runs on a Unix socket at ~/.xcodebuildmcp/daemons/<workspace-key>/daemon.sock
  • Auto-start: The daemon starts automatically when you invoke a stateful tool - no manual setup required.
  • Auto-shutdown: The daemon exits after 10 minutes of inactivity, but only when there are no active stateful sessions (log capture, debugging, video capture, background swift-package processes).

Daemon Commands

# Check daemon status for current workspace
xcodebuildmcp daemon status

# Manually start the daemon
xcodebuildmcp daemon start

# Stop the daemon
xcodebuildmcp daemon stop

# Restart the daemon
xcodebuildmcp daemon restart

# List all daemons across workspaces
xcodebuildmcp daemon list

# List in JSON format
xcodebuildmcp daemon list --json

Daemon Status Output

Daemon Status: Running
  PID: 12345
  Workspace: /Users/you/Projects/MyApp
  Socket: /Users/you/.xcodebuildmcp/daemons/c5da0cbe19a7/daemon.sock
  Started: 2024-01-15T10:30:00.000Z
  Tools: 94
  Workflows: (default)

Daemon List Output

Daemons:

  [running] c5da0cbe19a7
    Workspace: /Users/you/Projects/MyApp
    PID: 12345
    Started: 2024-01-15T10:30:00.000Z
    Version: 1.15.0

  [stale] a1b2c3d4e5f6
    Workspace: /Users/you/Projects/OldProject
    PID: 99999
    Started: 2024-01-14T08:00:00.000Z
    Version: 1.14.0

Total: 2 (1 running, 1 stale)

Stateful vs Stateless Tools

Stateless Tools (run in-process)

Most tools run directly without the daemon:

  • build, test, clean
  • list, list-schemes, discover-projects
  • boot, install, launch-app etc.

Stateful Tools (require daemon)

Some tools maintain state and route through the daemon:

  • Log capture: start-simulator-log-capture, stop-simulator-log-capture
  • Video recording: record-video
  • Debugging: attach, continue, etc.
  • Background processes: run, stop

When you invoke a stateful tool, the daemon auto-starts if needed.

Global Options

Option Description
--socket <path> Override the daemon socket path (hidden)
-h, --help Show help
-v, --version Show version

Troubleshooting

Daemon won't start

# Check for stale sockets
xcodebuildmcp daemon list

# Force restart
xcodebuildmcp daemon restart

# Run in foreground to see logs
xcodebuildmcp daemon start --foreground

Tool timeout

Increase the daemon startup timeout:

# Default is 5 seconds
export XCODEBUILDMCP_STARTUP_TIMEOUT_MS=10000

Socket permission errors

The socket directory (~/.xcodebuildmcp/daemons/) should have mode 0700. If you encounter permission issues:

chmod 700 ~/.xcodebuildmcp
chmod -R 700 ~/.xcodebuildmcp/daemons