| name | xcode-cli |
| description | Xcode IDE interaction skill. Uses the xcode-cli CLI to build, diagnose, test, preview, and edit Xcode projects via MCP. Use when the user asks to build an Xcode project, view build errors, run diagnostics, run tests, render SwiftUI previews, search Apple documentation, or manage project files. |
xcode-cli Skill
Interact with Xcode through the xcode-cli CLI backed by the Xcode MCP bridge.
Prerequisites
- Xcode 26.3 or later is installed and open with the target project
xcode-cli is installed: npm install -g xcode-cli- Bridge running:
xcode-cli-ctl install (background) or xcode-cli-ctl run (foreground)
Commands
All commands: xcode-cli <cmd> [args]. When run from a project directory the matching Xcode tab is auto-selected. Use --tab <tabIdentifier> to override, or run xcode-cli windows to list available tabs. Add --json for JSON output.
| Command | Usage | Notes |
|---|
windows | windows | List tabs/workspaces; get tabIdentifier |
status | status | Quick project status (windows + issues) |
build | build | Build project |
build-log | build-log --severity error | View build errors |
run | run | Build first, then run if build succeeds; returns JSON with build errors on failure |
run-without-build | run-without-build | Run without building (like Ctrl+Cmd+R) |
issues | issues --severity error | Navigator issues |
file-issues | file-issues "MyApp/Sources/MyFile.swift" | Single-file diagnostics, no full build |
test | test all / test list [--json] / test some "Target::Class/method()" | Run/list tests |
preview | preview "MyApp/Sources/MyView.swift" --out ./out | SwiftUI preview (requires #Preview macro) |
snippet | snippet "MyApp/Sources/File.swift" "print(expr)" --purpose "Inspect value" | Execute code snippet in file context; --purpose describes why |
doc | doc "SwiftUI NavigationStack" --frameworks SwiftUI | Search Apple documentation |
read | read "path/to/file" | Read file |
ls | ls [-r] / | List directory |
grep | grep "TODO|FIXME" | Search files |
glob | glob "**/*.swift" | Find files by pattern |
write | write "path/to/file" "content" | Write file |
update | update "path/to/file" "old" "new" [--replace-all] | Edit file |
mv | mv "Old.swift" "New.swift" | Move/rename file |
mkdir | mkdir "MyApp/Sources/Feature" | Create directory |
rm | rm "MyApp/Sources/Unused.swift" | Delete file |
Notes
- File paths are relative to the Xcode project structure, not absolute filesystem paths.
- If the bridge is not responding:
xcode-cli-ctl status then xcode-cli-ctl uninstall && xcode-cli-ctl install.
- Use
xcode-cli call <toolName> --args '{"key":"value"}' to invoke any MCP tool directly.
run builds via MCP first; if the build fails, it returns the build error JSON and exits with code 1. On success it triggers run-without-build via AppleScript and returns { buildResult, runTriggered }.run-without-build uses AppleScript to send a keyboard shortcut to Xcode; ensure Accessibility access is granted to Terminal/iTerm in System Settings → Privacy & Security → Accessibility.- Testing: use
targetName + identifier from test list --json for exact test targeting. test some only runs tests from the active scheme's active test plan — switch scheme in Xcode if a target is missing.
