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 → 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, likeswift-format for code: it checks that aproject.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 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 #

xcodeproj init creates an empty project in the JSON format:

The trailing commas aren't a typo. The file is JSON5, 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, andpkg 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 theWeather folder automatically, so you never register them one by one./Weather is a group path in the Project navigator, not a filesystem path, and everygroup andtarget command addresses groups this way.
3. Platform and Swift version.init doesn't add any defaults from Xcode's templates. WithoutSWIFT_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 butsimctl 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 #

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

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 <sha>` | 

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 , andpkg remove undo them.

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 #

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 #

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:

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 #

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 #

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?

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. 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 #

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

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

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 #

Apple also open-sourced the format as 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.