https://github.com/agisilaos/xctide
Human-first CLI wrapper for xcodebuild with clean build/run UX and machine-readable output.
https://github.com/agisilaos/xctide
automation cli developer-tools golang ios simulator swift xcodebuild
Last synced: about 2 months ago
JSON representation
Human-first CLI wrapper for xcodebuild with clean build/run UX and machine-readable output.
- Host: GitHub
- URL: https://github.com/agisilaos/xctide
- Owner: agisilaos
- License: mit
- Created: 2026-02-20T16:01:46.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-02-21T20:54:43.000Z (3 months ago)
- Last Synced: 2026-02-22T01:17:14.992Z (3 months ago)
- Topics: automation, cli, developer-tools, golang, ios, simulator, swift, xcodebuild
- Language: Go
- Homepage:
- Size: 260 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# xctide
A small TUI wrapper around `xcodebuild` for a cleaner, local build experience.
## Install
### Homebrew
```bash
brew tap agisilaos/tap
brew install xctide
```
Upgrade:
```bash
brew update
brew upgrade xctide
```
### Local build
```bash
go build -o xctide
```
### Shell completion
```bash
# bash
xctide completion bash > /usr/local/etc/bash_completion.d/xctide
# zsh
mkdir -p ~/.zsh/completions
xctide completion zsh > ~/.zsh/completions/_xctide
# fish
xctide completion fish > ~/.config/fish/completions/xctide.fish
```
## Usage
```bash
xctide
xctide build
xctide run --destination "platform=iOS Simulator,id="
xctide diagnose build --scheme Subsmind
xctide plan --scheme Subsmind -- test
xctide doctor
xctide destinations --scheme Subsmind
xctide destinations --scheme Subsmind --platform "iOS Simulator" --name "iPhone 17" --latest --limit 10
xctide xcrun simctl list devices available
xctide xcrun xctrace list templates
xctide xctest -h
xctide completion zsh > ~/.zsh/completions/_xctide
xctide --scheme "Subsmind" --destination "platform=iOS Simulator,name=iPhone 16"
xctide --plain -- -showBuildSettings
xctide --progress plain -- test
xctide --progress json -- test
xctide --progress ndjson -- test
xctide --json -- test
```
## Flags
- `--scheme` (auto-detected if omitted)
- `--workspace` / `--project` (auto-detected if omitted)
- `--configuration` (default: `Debug`)
- `--destination` (optional)
- `--platform` (destination filter for `xctide destinations`)
- `--name` (destination name contains filter for `xctide destinations`)
- `--os` (destination OS contains filter for `xctide destinations`)
- `--limit` (max destination rows to return for `xctide destinations`)
- `--latest` (keep latest OS per destination name for `xctide destinations`)
- `--simulator-only` / `--device-only` (destination filters for `xctide destinations`)
- `--progress` (`auto|tui|plain|json|ndjson`; default `auto`)
- `--result-bundle` (optional)
- `--details` (expanded plain output sections)
- `--quiet` (passes `-quiet` to `xcodebuild`)
- `--verbose` (wrapper diagnostics to stderr)
- `--plain` (disable TUI, stream raw output)
- `--json` (print structured summary to stdout)
- `--no-input` (disable interactive selection prompts)
- `--no-color` (disable color output)
- `--version`
## Subcommands
- `build`: default behavior, runs `xcodebuild` with resolved config.
- `run`: build then launch app on simulator (requires simulator `id=` destination).
- `diagnose build`: run doctor + config resolution + command preview to check build readiness.
- `plan`: resolve config and print exact `xcodebuild` command without executing.
- `doctor`: validate local build prerequisites (`xcodebuild`, `xcrun`, simulators, project context).
- `destinations`: list valid `xcodebuild` destinations for the resolved scheme.
- `xcrun`: explicit passthrough to `xcrun` for simulator/runtime tooling flows, including `xctrace`.
- `xctest`: explicit passthrough to `xcrun xctest` for direct test runner use.
## Exit codes
- `0`: success
- `1`: runtime/internal failure
- `2`: invalid usage
- `3`: config resolution failure (project/workspace/scheme)
- `4`: build/test failure from `xcodebuild`
- `130`: interrupted
## Environment variables
- `XCTIDE_SCHEME`
- `XCTIDE_WORKSPACE`
- `XCTIDE_PROJECT`
- `XCTIDE_CONFIGURATION`
- `XCTIDE_DESTINATION`
- `XCTIDE_PROGRESS`
- `NO_COLOR`
Precedence: flags > env > auto-detect/defaults.
## Notes
- Pass additional `xcodebuild` args after `--`.
- When stdout/stderr is not a TTY, `xctide` automatically falls back to plain output.
- Plain progress mode starts with an `Invocation` block that shows the resolved `xcodebuild` command.
- Plain progress mode defaults to compact summaries; pass `--details` for expanded `Completed`/`Dependencies`/`Executed` sections.
- Compact plain summaries include a short preview of slow dependency targets when available.
- `xctide run` performs build + simulator launch + install + app launch (requires simulator destination with `id=`).
- Preflight docs for `doctor` and `plan`: `docs/doctor-and-plan.md`.
- Build readiness preflight docs: `docs/diagnose.md`.
- Tool passthrough docs for `xcrun`/`xctest` and `xctrace` usage: `docs/tooling-passthrough.md`.
- Destination discovery docs: `docs/destinations.md`.
- Real-machine validation matrix notes: `docs/validation-matrix.md`.
- Release check and dry-run results: `docs/release-validation.md`.
## Progress Event Model (v1)
`xctide` emits one internal event stream used by all progress renderers (`tui`, `plain`, `json`):
- `run_started`
- `step_started`
- `step_finished` (`done`, `failed`, `skipped`)
- `diagnostic` (`warning`, `error`)
- `completed_item`
- `diagnostic_summary`
- `action_finished` / `action_failed`
- `run_finished`
In `--progress json`, events are returned in `events[]`, phase order in `phase_timeline`, completion rows in `completed[]`, execution rows in `executed[]`, and summary errors in `top_errors`.
In `--progress ndjson`, each event is emitted as one JSON object per line in real time (including `completed_item` and `diagnostic_summary`), with `run_finished` emitted last.
Machine payloads include `schema_version` and per-event `seq` for stable consumer parsing/replay.
Formal contract: `docs/machine-contract.md`.
When available, plain output includes a `Dependencies` section with slow non-primary build targets (typically SPM/package targets), and JSON includes `dependency_targets[]`.
## Release
1. `make release-check VERSION=vX.Y.Z`
2. `make release-dry-run VERSION=vX.Y.Z`
3. `make release VERSION=vX.Y.Z`
Release scripts:
- `scripts/release-check.sh`
- `scripts/release.sh`
Release readiness checklist: `docs/release-readiness.md`
## Docs
- `docs/doctor-and-plan.md`
- `docs/diagnose.md`
- `docs/tooling-passthrough.md`
- `docs/destinations.md`
- `docs/validation-matrix.md`
- `docs/release-validation.md`
- `docs/release-readiness.md`
- `docs/architecture.md`