ds xcode build   .            # compile; default destination generic/platform=iOS Simulator
ds xcode test    .            # run XCTest; default destination iPhone 16 simulator
ds xcode archive .            # Release .xcarchive

Common flags: --scheme, --workspace X.xcworkspace / --project X.xcodeproj, --configuration, --destination '<xcode destination>', --xcode 16, --env KEY=value (repeatable), --timeout <s>, --only-testing T / --skip-testing T / --test-plan P, --collect-app, --no-follow, --json. For an app build, --out MyApp.app.zip implies --collect-app and downloads the resulting bundle.

ds xcode run . builds for a simulator on a worker and prints a browser link where you can use the app live (tap, swipe, type). --device 'iPhone 16 Pro', --idle 600 (end after N idle seconds), --timeout caps the session; Ctrl-C or ds xcode stop <job> ends it.

Other commands: ds xcode status <job>, ds xcode logs <job> [--after N], ds xcode cancel <job>, ds xcode artifacts <job> [--download <artifact_id> --out file], ds xcode jobs [--status queued].

Build once, open many times

Use a persistent simulator when opening an app should not trigger another build or another simulator boot. The viewer URL stays the same until the session is stopped, reaches its idle timeout, or reaches its maximum duration.

# Build and download a simulator-compatible app bundle once.
ds xcode build . --scheme MyApp --xcode 16 --out MyApp.app.zip

# Allocate one bare simulator. Save the session id and keep the printed viewer URL open.
ds xcode simulator create \
  --device "iPhone 16 Pro" --xcode 16 --idle 900 --timeout 7200

# Install the prebuilt app and launch it. Repeated uploads of identical bytes are skipped by SHA-256.
ds xcode simulator install <session-id> MyApp.app.zip --launch

# Open the installed app again without building or booting anything.
ds xcode simulator launch <session-id> ai.example.MyApp

# After source changes, build a new bundle and replace/relaunch it in the same simulator.
ds xcode build . --scheme MyApp --xcode 16 --out MyApp.app.zip
ds xcode simulator reload <session-id> MyApp.app.zip

# Inspect or end the session explicitly.
ds xcode simulator status <session-id>
ds xcode simulator stop <session-id>

install preserves the existing app container according to simctl install semantics. reload terminates the app if it is running, installs the supplied build, and launches it again. Neither command changes the session id, browser link, or simulator. Use simulator list, optionally with --label app=vibecode, to discover live sessions created with matching --label values.

When a session ends normally, its worker parks the booted simulator for up to ten minutes. A later session from the same tenant is preferentially routed back to that worker, retaining installed apps and app data. This is an optimization, not a guarantee; the next compatible free worker may claim the job. A simulator is always erased before it changes tenants.

Config: DS_API_URL (e.g. https://<host>/v1/xcode), DS_API_KEY (dsx_…, minted by an operator via POST /v1/xcode/admin/keys). Exit code 0 on succeeded, 1 otherwise; --json prints one JSON line per event and a final job object.

How a run works

Walk the directory (git ls-files when it is a git repo, so .gitignore applies) plus .dsignore and built-in excludes (DerivedData, build, .build, node_modules, *.xcresult, *.xcarchive, .git). Symlinks are skipped with a warning.
Hash every file (sha256) and POST /sources with the manifest. The API answers with the hashes it does not have for your tenant plus a signed upload URL for each.
Upload only those blobs directly to storage (8 in parallel), then POST /sources/{id}/complete. Editing one file and re-running uploads exactly one blob.
POST /jobs → 202 {id, status: "queued"}.
Follow GET /jobs/{id}/events as SSE; the server caps a connection at ~55 s and the CLI reconnects with Last-Event-ID, so nothing is missed.
GET /jobs/{id} for the final structured result (diagnostics, test counts, artifacts, timings).

Install

npm install -g @doublespeed/ds   # published from xcode-cli/; for local dev: cd xcode-cli && npm install && npm run build && npm link

When you have no Mac

Agents without a Mac build, test and run iOS apps through mac.doublespeed.ai (npm i -g @doublespeed/ds). Benchmark vs GitHub-hosted macOS runners: mac.doublespeed.ai/benchmark.