# 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
```bash
# Install globally
npm install -g xcodebuildmcp@beta
# Or run via npx
npx xcodebuildmcp@beta --help
```
## Quick Start
```bash
# List available tools
xcodebuildmcp tools
# View CLI help
xcodebuildmcp --help
# View tool help
xcodebuildmcp <workflow> <tool> --help
```
## Tool Options
Each tool supports `--help` for detailed options:
```bash
xcodebuildmcp simulator build --help
```
Common patterns:
```bash
# 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
```bash
# 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 com.example.MyApp
# Or... build and run in a single command
xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj
```
### Log Capture Workflow
```bash
# Start log capture
xcodebuildmcp logging start-simulator-log-capture --simulator-id <UDID> --bundle-id com.example.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
```bash
# 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](TOOLS-CLI.md).
## Configuration
The CLI respects the same configuration as the MCP server:
```yaml
# .xcodebuildmcp/config.yaml
sessionDefaults:
scheme: MyApp
projectPath: ./MyApp.xcodeproj
simulatorName: iPhone 17 Pro
enabledWorkflows:
- simulator
- project-discovery
```
See [CONFIGURATION.md](CONFIGURATION.md) for the full schema.
## 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
```bash
# 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
```bash
# 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:
```bash
# 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:
```bash
chmod 700 ~/.xcodebuildmcp
chmod -R 700 ~/.xcodebuildmcp/daemons
```
