# Xcode Projects for the Command Line and Coding Agents > Source: > Published: 2026-10-15 00:00:00+00:00 # Xcode Projects for the Command Line and Coding Agents From the author ### iOS Daily One essential iOS development article a day, with a short summary. Free on Telegram. [Learn More →](https://t.me/+ltQId2u7xvQxYWYy) Xcode 27.2 beta 2 introduced a new project format. Instead of the old `project.pbxproj` property list, a project can store its configuration in `project.xcproj`, a JSON file with readable keys and no object IDs for every build file. To switch, select the project in the Project navigator (1), open the File inspector (2), and choose **JSON** in the **Project Format** pop-up under **Project Document** (3): Xcode also ships two command-line tools for the new format: - `xcprojformatter` came with the format in beta 2. It's a formatter for project files, like`swift-format` for code: it checks that a`project.xcproj` file is valid and rewrites it with sorted keys and consistent layout. - `xcodeproj` arrived in beta 3. It reads and edits projects from the terminal: targets, build phases, groups, build settings, xcconfig files, and Swift packages. Neither is on your `PATH`, so run them with `xcrun`. If you use CocoaPods, a plain `xcodeproj` in the terminal may run the `xcodeproj` Ruby gem instead. Check with `which xcodeproj` and always call Apple's tool as `xcrun xcodeproj`. Apple's [article](https://developer.apple.com/documentation/xcode/updating-your-xcode-project-configuration-file-format) covers the format itself, and the tools come with detailed `--help`. This post covers what each tool does and where it helps in practice. ## [Creating a project from scratch](#creating-a-project-from-scratch) `xcodeproj init` creates an empty project in the JSON format: The trailing commas aren't a typo. The file is [JSON5](https://json5.org), a superset of JSON that also allows comments, unquoted keys, and single-quoted strings. Xcode writes only the trailing commas. The formatter turns everything else back into plain JSON and drops comments. There's no template option, so everything Xcode's New Project sheet does takes a separate command. Here's the minimum for an iOS app with a single source file, `Weather/WeatherApp.swift`: What each step does: 1. **Build phases.** A new target has none, and nothing compiles without a Sources phase. The Frameworks phase is where package products get linked, and`pkg add` fails without it. Add a Resources phase too if the app has asset catalogs or other resources. 2. **Synchronized group.** Xcode picks up new files in the`Weather` folder automatically, so you never register them one by one.`/Weather` is a group path in the Project navigator, not a filesystem path, and every`group` and`target` command addresses groups this way. 3. **Platform and Swift version.**`init` doesn't add any defaults from Xcode's templates. Without`SWIFT_VERSION` , the build fails. Without a deployment target, it defaults to the SDK version, so the app runs only on the latest OS. Set it to the oldest version you want to support. 4. **Bundle ID and launch screen.** Without a bundle ID, the app builds but`simctl install` rejects it. The launch screen key is what Xcode's app template sets. `target add` already sets `PRODUCT_NAME` and `GENERATE_INFOPLIST_FILE`, so the app doesn't need an `Info.plist` file. ## [Changing build settings](#changing-build-settings) `setting set` writes to the project by default and to a target with `--target`. `--config` scopes a value to one configuration. Values that start with a dash need a bare `--` before them, and `--` ends option parsing, so put `--config` first: In the JSON file, both values end up in the same dictionary, with the configuration written as a suffix: `get` and `list` print raw values. They don't evaluate macros or read the contents of xcconfig files. For resolved values, use `xcodebuild -showBuildSettings`. The tool knows which settings are lists. `OTHER_LDFLAGS` or `GCC_PREPROCESSOR_DEFINITIONS` go through `setting set-multi`, and `setting set` rejects them. The opposite also holds: `OTHER_SWIFT_FLAGS` is single-valued here, so `set-multi` rejects it. ### [Moving settings to an xcconfig file](#moving-settings-to-an-xcconfig-file) `setting set` takes one key and one value per call, so every setting is a separate command. To set several at once, put them in an xcconfig file: Then add it to the project and link it to every configuration: The project file only gets a reference, and the values stay in a file that's easy to read and review: A project-level xcconfig applies to every target, including test bundles you add later, so keep target-specific values like the bundle ID on the target itself. `setting get` doesn't read xcconfig files, so keys set there show up as unset: ## [Adding Swift packages](#adding-swift-packages) `pkg add` adds a remote package and, with `--product` and `--target`, links a product in the same step: `--from` means "up to next major version". The other requirement kinds from Xcode's UI have their own flags: | Requirement | Flag | |---|---| | Up to next minor version | `--up-to-next-minor 1.2.0` | | Exact version | `--exact 1.2.0` | | Range | `--range-min 1.0.0 --range-max 2.0.0` | | Branch | `--branch main` | | Commit | `--revision ` | The rest of the `pkg` commands cover what's left in the Package Dependencies tab: - `pkg add-local` adds a local package. - `pkg link --embed` links a product and embeds a dynamic framework. - `pkg link-plugin` runs a build-tool plugin. - `pkg unlink` ,`pkg unlink-plugin` , and`pkg remove` undo them. ## [Checking the result](#checking-the-result) A few read-only commands show what the project contains: Phases are addressed by their index from `target info`, not by kind, because a target can have several phases of the same kind. The whole project file is now about 60 lines, and `xcodebuild` builds it as is. `xcodeproj` never creates schemes or workspaces, but `xcodebuild` generates a scheme automatically: ## [Old projects and smaller diffs](#old-projects-and-smaller-diffs) `xcodeproj` isn't limited to the new format. It edits `project.pbxproj` files too, and the changes are minimal: `xcodeproj` can't convert a project to JSON, but `xcodebuild` can. It's the same switch as the File inspector, without opening Xcode: The new file replaces the old one, so commit before converting. Projects in the JSON format also open in Xcode 27.0 and 27.1, so the whole team doesn't have to be on the beta. The command-line tools ship only with 27.2. The new format pays off in diffs. Here's the same `pkg add` of `swift-collections` in both formats. The property list gets 24 new lines in five places, three generated IDs, and three new sections: The JSON file gets 12 lines in two places, and a reviewer can read them: ## [Catching broken files with xcprojformatter](#catching-broken-files-with-xcprojformatter) `xcprojformatter` parses a project file and prints it back in canonical form: keys sorted, defaults omitted, comments removed. It doesn't support `project.pbxproj`. An invalid file makes it exit with an error. Here's what it prints for a few broken edits: | Edit | Error | |---|---| | Remove a target's `id` | Missing required value for key “id” at “/targets[0]” | | Misspell the `compile-sources` phase | Unexpected value “compile-source” | | Set a target's `name` to a number | Expected an instance of string but an instance integer was specified | Only the first error includes a path to the problem. The other two don't say where it is. Unknown keys don't cause an error. The formatter silently drops them. A typo like `build-setings` produces a valid project that ignores your settings. The formatter shows it as a removed line: So the useful check is whether the formatter changes anything. That makes a good CI step: It exits with an error when someone edits the file by hand without formatting it, and the diff shows exactly which lines the formatter would drop. ## [Resolving merge conflicts in JSON](#resolving-merge-conflicts-in-json) The JSON format doesn't make conflicts disappear. I added a package and a build setting on one branch, and a different package, a different setting, and a widget target on another. The new target merged cleanly, but both package additions and both settings conflicted, since sorted entries land next to each other: These conflicts are readable, but don't just keep both sides. Here it creates an object with two `repository` keys. The formatter accepts it and silently drops one, so the merged project loses a package without an error: Array entries have to become separate objects again: Dictionary entries like build settings are fine to keep side by side as long as the keys differ. After resolving, the formatter diff may move lines into sorted order, but it shouldn't drop any. Run `xcrun xcprojformatter --update`, then check that `xcrun xcodeproj pkg list` and `xcrun xcodeproj target list` show both branches' changes. Or skip the manual merge: take one side of the file and replay the other branch's changes with `xcodeproj`. Changes that merged cleanly, like the widget target here, need replaying too. ## [Handing the CLI to agents](#handing-the-cli-to-agents) You'll rarely type the commands above yourself. Adding a target in Xcode is still faster than five commands and a few build settings. The CLI is for coding agents: Apple pitches the JSON format as easier for them to edit, and `xcodeproj` looks designed for them too. Its help pages are long, explain each edge case, and point to the next command. Errors list what's available or say which command to use instead: Agents can edit the JSON file directly, but the tool is safer. It generates unique IDs for new targets and products, keeps the format canonical, and checks things like dependency cycles before it writes anything. An agent won't reach for the tool on its own, though. It's new, it's not on the `PATH`, and models haven't seen it in training data. Everything this post covers, from the order of commands to the gotchas below, is context the agent needs. A few lines in `CLAUDE.md` or `AGENTS.md` pass it along: There's no project name in it, so you can paste it into any project. With one `.xcodeproj` in the folder, `xcodeproj` finds it automatically. With several, the agent passes `--project`, or you set `XCODEPROJ_PROJECT` to the project's path. ### [What about Xcode's MCP server?](#what-about-xcodes-mcp-server) Xcode also gives agents an MCP server through `xcrun mcpbridge`, and some of its tools overlap with `xcodeproj`. `XcodeNewProject` and `XcodeNewTarget` create projects and targets from Xcode's templates, `XcodeMakeDir` creates synchronized folders, and `GetTargetBuildSettings` and `UpdateTargetBuildSetting` read and change target build settings. The MCP tools go through a running Xcode with the project open, or through headless Xcode, which you turn on with `sudo xcrun mcp-server enable`. I covered that setup in [Headless Xcode: From Prompt to Simulator with MCP](https://artemnovichkov.com/blog/headless-xcode-from-prompt-to-simulator-with-mcp). The MCP tools can't add Swift packages, link xcconfig files, or edit build phases, and they change build settings only per target, without project-level or per-configuration values. If you already use the MCP server, it covers templates, previews, and running the app on a simulator. `xcodeproj` handles the project file edits the MCP tools can't do, and it's a plain command with no server or permissions to set up. ## [Gotchas](#gotchas) A few things I ran into while testing. ### [Add build phases before synchronized groups](#add-build-phases-before-synchronized-groups) If you include a filesystem-synchronized group before the target has a Sources phase, `xcodeproj` puts every file in the folder into the target's exclusions: Nothing compiles, and the build fails at linking with no hint about why. Including the group again doesn't help, since it's already included. Include each excluded file instead: Or add the phases first. ### [Test targets need manual wiring](#test-targets-need-manual-wiring) Xcode's New Target sheet does more than `target add` does. A unit test target created from the CLI has no host app, so `@testable import` fails. Here's the full setup, assuming a `WeatherTests` folder with the tests: The last line is needed for projects created with `init`. Projects from Xcode's templates already have it. `xcodeproj` also never touches schemes. If your project has a shared scheme, its Test action won't include the new target, and `xcodebuild test -scheme Weather` won't run the new tests. `xcodebuild` generates a separate `WeatherTests` scheme, so either test with that scheme or add the target to the shared one in Xcode. `xcodebuild -list` doesn't show the `WeatherTests` scheme, but `-scheme WeatherTests` still works. ### [Keep xcconfig files out of synchronized groups](#keep-xcconfig-files-out-of-synchronized-groups) Putting `Project.xcconfig` next to the sources in `Weather/` seems natural, but `config set` refuses to link it: The error is longer than that and suggests the fix: keep xcconfig files in a regular group, like `Config` above, outside any synchronized folder. ## [Going further with the Swift package](#going-further-with-the-swift-package) Apple also open-sourced the format as [xcode-project-format](https://github.com/apple/xcode-project-format), a Swift package that models `project.xcproj` as value types under the `XCSchema` namespace. `xcprojformatter` is built on it. If the CLI doesn't cover your case, for example a custom linter that checks every target's deployment target, you can read and write the project with typed models instead of parsing JSON: The format and both tools are still in beta and have rough edges, as the gotchas above show. [Tuist](https://tuist.dev) and [XcodeGen](https://github.com/yonaskolb/XcodeGen) remain an option, but for many projects a readable project file and a CLI from Apple may be enough.