1. Was ist xcodex?

xcodex ist ein terminalbasiertes CLI-Tool für Apple-Entwickler. Es fasst die wichtigsten Xcode-Workflows in einer einzigen, tastaturgesteuerten Oberfläche zusammen — ohne Flags auswendig zu lernen, ohne Kontextwechsel, ohne Xcode öffnen zu müssen.

Das Tool unterstützt iOS-, iPadOS- und macOS-Projekte und deckt den gesamten Entwicklungsalltag ab: Build, Tests, Simulatorsteuerung, Geräteverwaltung, Archive, TestFlight/App-Store-Auslieferung, Lokalisierung, Code Coverage, Crash-Analyse und Projektpflege.

2. Voraussetzungen

3. Installation

Repository klonen

git clone https://github.com/drapatzc/xcodex.git
cd xcodex

Ausführungsrechte setzen

chmod +x xcodex

Shell-Alias einrichten (empfohlen)

Damit xcodex aus jedem Verzeichnis erreichbar ist, einen Alias in der Shell-Konfiguration eintragen:

echo 'alias xcodex="/absoluter/pfad/zu/xcodex/xcodex"' >> ~/.zshrc
source ~/.zshrc

Aktualisieren

cd /pfad/zu/xcodex
git pull

4. Erste Schritte — Projekt einrichten

Beim ersten Start aus einem Projektverzeichnis muss xcodex einmalig konfiguriert werden. xcodex erkennt .xcworkspace- und .xcodeproj-Dateien automatisch im aktuellen Verzeichnis:

cd ~/Projects/MeineApp
xcodex

xcodex

Schritt-für-Schritt: Projekt auswählen, Schema, Gerät und Konfiguration festlegen

Schritt 1 — Arbeitsverzeichnis auswählen

xcodex sucht automatisch nach Xcode-Dateien im aktuellen Verzeichnis. Wird keine gefunden, öffnet sich ein Dateibrowser zur manuellen Auswahl.

Schritt 2 — App-Schema festlegen

Das Schema steuert, was gebaut und wie es gestartet wird. Optional kann ein separates Test-Schema oder Testplan gewählt werden — sinnvoll bei Tests in einem eigenen Target.

Schritt 3 — Zielgerät auswählen

Verfügbare Simulatoren und verbundene physische Geräte werden automatisch aus der aktuellen Xcode-Installation ermittelt.

Schritt 4 — Build-Konfiguration wählen

• Debug — tägliche Entwicklung, mit Symbolen und Logs
• Release — App-Store-Builds, mit allen Optimierungen

5. Die Menü-Oberfläche

Die Oberfläche ist zweigeteilt: links die Befehlsgruppen, rechts die zugehörigen Aktionen. Navigation erfolgt ausschließlich per Tastatur.

xcodex

Split-Pane-Interface: Befehlsgruppen links, Aktionen rechts

Alle Einstellungen bleiben automatisch zwischen den Sitzungen erhalten.

6. Clean & Cache

Xcode speichert alle Build-Artefakte in einem gemeinsamen DerivedData-Ordner. Wenn Builds ohne erkennbaren Grund fehlschlagen, die App sich seltsam verhält oder nach einem Refactoring Fehler erscheinen, die im Code nicht existieren — dann hilft ein gezieltes Bereinigen.

xcodex

Clean & Cache: verschiedene Bereinigungs-Optionen auf einen Blick

7. Build & Run

xcodex bietet mehrere vorkonfigurierte Build-Modi, die für häufige Entwicklungsszenarien optimiert sind.

xcodex

Build & Run: verschiedene Modi für unterschiedliche Situationen

Build-Ausgabe verstehen

Während des Builds zeigt xcodex jeden Schritt mit seiner Laufzeit an. Bei einem Fehler wird die Fehlermeldung rot hervorgehoben und mit der betroffenen Datei und Zeile angezeigt.

xcodex

Build-Ausgabe: strukturiert, komprimiert, mit Zeitangaben pro Schritt

Isoliertes DerivedData

xcodex baut in ein eigenes DerivedData-Verzeichnis, das vollständig von Xcode getrennt ist. Beide können gleichzeitig laufen, ohne sich gegenseitig zu beeinflussen.

8. Abhängigkeiten

Wer CocoaPods, SPM oder Carthage nutzt, kann Abhängigkeiten direkt aus xcodex heraus verwalten — ohne Terminal-Kenntnisse.

xcodex

Dependencies: SPM, CocoaPods und Carthage in einem Menü

9. Simulator steuern

Simulatoren können in einen inkonsistenten Zustand geraten — besonders nach iOS-Updates oder langen Laufzeiten. Diese Gruppe gibt die Kontrolle zurück.

xcodex

Simulator: App neu installieren, zurücksetzen, alle Instanzen schließen

Simulator fernsteuern

Nach dem App-Start lassen sich Simulator-Einstellungen direkt aus xcodex heraus ändern — ohne den Simulator-Menübaum zu durchsuchen.

xcodex

Controls: Dark Mode, Berechtigungen, Statusleiste, Push Notifications

10. Tests

xcodex trennt Unit-Tests und UI-Tests, damit der jeweils passende Durchlauf gestartet werden kann — schnelle Unit-Tests im Entwicklungsloop, UI-Tests vor Commits oder Releases.

xcodex

Tests: Unit-Tests, UI-Tests und alle Tests auf einen Klick

Ergebnis-Zustände: ✅ Bestanden · ⚠️ Übersprungen · ❌ Fehlgeschlagen

Fehlgeschlagene Tests einzeln wiederholen

xcodex

Fehlgeschlagene Tests werden rot markiert und können einzeln neu gestartet werden

Nach einem Durchlauf listet xcodex alle Ergebnisse auf. Fehlgeschlagene Tests können einzeln neu gestartet werden — ohne die gesamte Test-Suite zu wiederholen. Typischer Workflow:

1. Alle Tests starten
2. Fehlgeschlagene Tests identifizieren
3. Fix implementieren
4. Nur die betroffenen Tests erneut ausführen
5. Bei Erfolg: vollständigen Durchlauf zur Bestätigung starten

Code Coverage

xcodex

Code Coverage auf Dateiebene: schnell identifizieren, wo Tests fehlen

Automatisierte Tests

xcodex

Automatisierte Tests laufen vollständig unabhängig von Xcode

Die automatisierten Tests laufen vollständig unabhängig von Xcode — Xcode kann gleichzeitig geöffnet sein, ohne Auswirkungen auf den Test-Durchlauf. Ideal für:

• Parallel zur Entwicklung — Tests für Feature A, während man an Feature B arbeitet
• QA ohne Xcode-Kenntnisse — Tester können eigenständig Test-Durchläufe starten
• Zweiter Clone — letzten Commit testen, ohne die eigene Entwicklungsumgebung zu berühren

11. Xcode-Integration

Diese Gruppe enthält Schnellzugriff-Befehle für Xcode selbst — für den Wechsel zwischen Terminal und IDE.

xcodex

Xcode öffnen und schließen direkt aus xcodex

• Projekt in Xcode öffnen — öffnet das aktuell konfigurierte .xcworkspace oder .xcodeproj direkt in Xcode. Spart das manuelle Suchen der Datei im Finder
• Xcode schließen — schließt alle Xcode-Fenster. Nützlich, bevor ein Clean Build gestartet wird — Xcode hält manchmal Build-Artefakte offen

12. App Store & Distribution

xcodex deckt den gesamten Distributionsprozess ab — vom Archivieren bis zum Upload. Das spart die manuelle Arbeit im Xcode Organizer und ermöglicht Uploads direkt aus dem Terminal.

xcodex

App Store: Archivieren, Validieren und Hochladen in einem strukturierten Workflow

Voraussetzung: App-spezifisches Passwort

Für den Upload zu TestFlight oder App Store Connect benötigt xcodex ein App-spezifisches Passwort:

1. Öffne appleid.apple.com
2. Gehe zu Sicherheit → App-spezifische Passwörter
3. Erstelle ein neues Passwort (z. B. „xcodex Upload")
4. Das Passwort wird einmalig in den xcodex-Einstellungen hinterlegt

Typischer Release-Workflow

xcodex

Release-Workflow: Validieren vor dem Upload schützt vor häufigen Einreichungsfehlern

1. Full Reset & Build mit Release-Konfiguration
2. Archivieren
3. Validieren — Fehler korrigieren, falls vorhanden
4. Zu TestFlight hochladen — für Beta-Tests
5. Nach Freigabe: In den App Store einreichen

13. Verzeichnisse

Xcode verteilt seine Daten über mehrere verschachtelte Library-Pfade. xcodex öffnet die wichtigsten Ordner mit einem Tastendruck direkt im Finder.

xcodex

Verzeichnisse: DerivedData, Archive, Simulatoren und Provisioning Profiles auf einen Klick

14. Entwicklungsumgebungen isolieren

Diese Funktion klont einen definierten Branch in ein separates Verzeichnis. Bei jeder Aktualisierung wird der geklonte Stand auf den neuesten Commit zurückgesetzt — die eigene Entwicklungsumgebung bleibt unberührt.

xcodex

Isolierte Entwicklungsumgebungen: QA und Tester können eigenständig bauen und testen

Typische Anwendungsfälle

• QA und Tester — eigenständig den aktuellen develop-Branch bauen und testen, ohne Xcode-Kenntnisse
• Android-Entwickler — iOS-App in einem definierten Stand ausprobieren
• UX-Designer — Feature-Branch schnell auf dem Simulator starten
• Code-Reviews — zweiter Clone zum Testen des Review-Branches, ohne die eigene Umgebung zu berühren

Konfigurationsdatei

{
  "description": "RefenzApps",
  "base": "/Users/drapatz/Downloads/tempApps/",
  "repositories": [
    {
      "name": "RefenzApps-Repository",
      "url": "git@github.com:beispiel/repo.git",
      "destination": "refApps"
    }
  ]
}

15. Lokalisierung

Fehler in der Lokalisierung fallen oft erst zur Laufzeit auf. xcodex prüft die .xcstrings-Datei statisch, bevor es zu Laufzeit-Problemen kommt.

xcodex

Lokalisierung: fehlende Keys, doppelte Keys und Konsistenz-Prüfung

16. Verschiedenes

Unter Verschiedenes sind Funktionen gebündelt, die seltener benötigt werden, aber im richtigen Moment entscheidend sind.

xcodex

Crash Reports, Instruments und Provisioning Profiles

• Crash Reports analysieren — symbolisiert .crash-Dateien und zeigt lesbare Stack Traces. Erfordert das passende .dSYM-Archiv
• Instruments (Beta) — startet Profiling-Sessions direkt aus xcodex heraus
• Provisioning Profiles verwalten — listet alle lokalen Profile auf und erlaubt die Bereinigung abgelaufener Profile

Provisioning Profiles im Überblick

xcodex

Alle lokalen Provisioning Profiles auf einen Blick — abgelaufene direkt entfernen

17. Developer-Ressourcen

In der letzten Befehlsgruppe sind die am häufigsten benötigten Dokumentations- und Verwaltungsseiten für Apple-Entwickler verlinkt.

xcodex

Direktzugriff auf Apple-Dokumentation, App Store Connect und Swift Package Index

• Apple Developer Documentation
• Swift Documentation & Evolution Proposals
• Human Interface Guidelines
• App Store Connect
• Apple Developer Portal
• Swift Package Index

Diese Links öffnen direkt im Standard-Browser.

18. Häufige Probleme

Kein Schema gefunden

Das Arbeitsverzeichnis ist nicht korrekt gesetzt oder die .xcworkspace/.xcodeproj-Datei liegt nicht im aktuellen Verzeichnis. xcodex aus dem Projekt-Root starten.

Simulator nicht verfügbar

Xcode neu öffnen und die gewünschten Simulator-Plattformen installieren. Anschließend xcodex neu starten — die Geräteliste wird automatisch aktualisiert.

Build schlägt fehl

Fehlermeldung und betroffene Datei aus der roten Ausgabe entnehmen. Bei unerklärlichen Fehlern zuerst DerivedData löschen (Clean & Cache) und dann erneut bauen.

Xcode Command Line Tools fehlen

xcode-select --install

Nach der Installation Terminal neu starten.

Push Notification funktioniert nicht

Die App muss Push Notifications im entitlements-File aktiviert haben und korrekt im Apple Developer Portal registriert sein. Im Simulator werden Notifications auch ohne APNs-Zertifikat unterstützt.

Rechteproblem beim Starten

xcodex ist nicht ausführbar. Lösung:

chmod +x /pfad/zu/xcodex

„missing module"-Fehler nach Branch-Wechsel

Abhängigkeiten nach dem Branch-Wechsel neu auflösen: Build & Run → Alle Dependencies auflösen.

19. Tipps für den Alltag

• Alias verwenden — xcodex in ~/.zshrc einrichten, damit der Befehl aus jedem Verzeichnis funktioniert
• Tool aus dem Projektverzeichnis starten — xcodex erkennt die Projektdatei automatisch, wenn es im Root-Verzeichnis des Projekts gestartet wird
• Vor Pull Requests — lokale Builds und Tests ausführen, bevor ein PR erstellt wird. Das vermeidet fehlschlagende CI-Pipelines
• Eigene DerivedData-Pfade nutzen — xcodex baut in ein isoliertes Verzeichnis, sodass Xcode-Builds nicht beeinflusst werden
• Nach git pull — zuerst Dependencies auflösen, dann bauen
• Vor einem Release-Build — Provisioning Profiles prüfen und Simulator-Cache leeren
• Regelmäßig aktualisieren — git pull im xcodex-Verzeichnis hält das Tool aktuell

20. Haftungsausschluss

xcodex ist ein unabhängiges Open-Source-Werkzeug und steht in keiner Verbindung zu Apple Inc. „Xcode" und „TestFlight" sind eingetragene Marken von Apple Inc. Die Nutzung des Tools erfolgt auf eigene Verantwortung. Für Schäden, die aus der Nutzung entstehen, wird keine Haftung übernommen.

1. What is xcodex?

xcodex is a terminal-based CLI tool for Apple developers. It consolidates the most important Xcode workflows into a single, keyboard-driven interface — without memorizing flags, without context switching, without opening Xcode.

The tool supports iOS, iPadOS and macOS projects and covers the entire development workflow: build, tests, simulator control, device management, archives, TestFlight/App Store delivery, localization, code coverage, crash analysis and project maintenance.

2. Requirements

3. Installation

Clone the repository

git clone https://github.com/drapatzc/xcodex.git
cd xcodex

Set executable permission

chmod +x xcodex

Set up shell alias (recommended)

To run xcodex from any directory, add an alias to your shell configuration:

echo 'alias xcodex="/absolute/path/to/xcodex/xcodex"' >> ~/.zshrc
source ~/.zshrc

Update

cd /path/to/xcodex
git pull

4. Getting Started — Project Setup

On first launch from a project directory, xcodex needs to be configured once. xcodex automatically detects .xcworkspace and .xcodeproj files in the current directory:

cd ~/Projects/MyApp
xcodex

xcodex

Step by step: select project, scheme, device and build configuration

Step 1 — Select working directory

xcodex automatically searches for Xcode files in the current directory. If none is found, a file browser opens for manual selection.

Step 2 — Select app scheme

The scheme controls what gets built and how it is launched. Optionally select a separate test scheme or test plan — useful when tests are organized in their own target.

Step 3 — Select target device

Available simulators and connected physical devices are automatically detected from the current Xcode installation.

Step 4 — Choose build configuration

• Debug — daily development, with symbols and logs
• Release — App Store builds, with all optimizations enabled

5. The Menu Interface

The interface is split into two panes: command groups on the left, actions on the right. Navigation is entirely keyboard-driven.

xcodex

Split-pane interface: command groups on the left, actions on the right

All settings persist automatically between sessions.

6. Clean & Cache

Xcode stores all build artifacts in a shared DerivedData folder. When builds fail for no apparent reason, the app behaves strangely, or errors appear after a refactoring that don't exist in the code — a targeted cleanup helps.

xcodex

Clean & Cache: various cleanup options at a glance

7. Build & Run

xcodex offers several preconfigured build modes optimized for common development scenarios.

xcodex

Build & Run: different modes for different situations

Understanding build output

During the build, xcodex shows each step with its duration. Errors are highlighted in red with the affected file and line number.

xcodex

Build output: structured, compact, with timing per step

Isolated DerivedData

xcodex builds into its own DerivedData directory, completely separate from Xcode. Both can run simultaneously without interfering with each other.

8. Dependencies

CocoaPods, SPM or Carthage dependencies can be managed directly from xcodex — no terminal experience required.

xcodex

Dependencies: SPM, CocoaPods and Carthage in one menu

9. Simulator Control

Simulators can fall into an inconsistent state — especially after iOS updates or extended uptime. This group restores control.

xcodex

Simulator: reinstall app, reset, close all instances

Remote control the simulator

After the app launches, simulator settings can be changed directly from xcodex — no need to dig through the simulator's own menus.

xcodex

Controls: Dark Mode, permissions, status bar, push notifications

10. Tests

xcodex separates unit tests and UI tests so the right run can be started for each situation — fast unit tests in the development loop, UI tests before commits or releases.

xcodex

Tests: unit tests, UI tests and all tests with one action

Result states: ✅ Passed · ⚠️ Skipped · ❌ Failed

Re-run failed tests individually

xcodex

Failed tests are highlighted in red and can be re-run individually

After a run, xcodex lists all results. Failed tests can be re-run individually — without repeating the entire test suite. Typical workflow:

1. Run all tests
2. Identify failed tests
3. Implement fix
4. Re-run only the affected tests
5. On success: run full suite to confirm

Code Coverage

xcodex

Code coverage per file: quickly identify where tests are missing

Automated Tests

xcodex

Automated tests run completely independently of Xcode

Automated tests run fully independently of Xcode — Xcode can be open simultaneously without affecting the test run. Ideal for:

• In parallel with development — tests for feature A while working on feature B
• QA without Xcode knowledge — testers can run test suites independently
• Second clone — test the last commit without touching your own development environment

11. Xcode Integration

This group contains quick-access commands for Xcode itself — for switching between the terminal and the IDE.

xcodex

Open and close Xcode directly from xcodex

• Open project in Xcode — opens the currently configured .xcworkspace or .xcodeproj directly in Xcode. Saves manually searching for the file in Finder
• Close Xcode — closes all Xcode windows. Useful before starting a clean build — Xcode sometimes holds build artifacts open

12. App Store & Distribution

xcodex covers the entire distribution process — from archiving to upload. This saves the manual work in Xcode Organizer and enables uploads directly from the terminal.

xcodex

App Store: archive, validate and upload in a structured workflow

Prerequisite: App-specific password

For uploads to TestFlight or App Store Connect, xcodex requires an app-specific password:

1. Open appleid.apple.com
2. Go to Security → App-Specific Passwords
3. Create a new password (e.g. "xcodex Upload")
4. Enter the password once in xcodex settings

Typical release workflow

xcodex

Release workflow: validating before upload prevents common submission errors

1. Full Reset & Build with Release configuration
2. Archive
3. Validate — fix errors if any
4. Upload to TestFlight — for beta testing
5. After approval: submit to App Store

13. Directories

Xcode distributes its data across several nested Library paths. xcodex opens the most important folders with a single keystroke directly in Finder.

xcodex

Directories: DerivedData, archives, simulators and provisioning profiles in one click

14. Isolated Development Environments

This feature clones a defined branch into a separate directory. On each update, the cloned state is reset to the latest commit — your own development environment remains untouched.

xcodex

Isolated environments: QA and testers can build and test independently

Typical use cases

• QA and testers — independently build and test the current develop branch without Xcode knowledge
• Android developers — try out the iOS app in a defined state
• UX designers — quickly launch a feature branch on the simulator
• Code reviews — second clone for testing the review branch without touching your own environment

Configuration file

{
  "description": "ReferenceApps",
  "base": "/Users/username/Downloads/tempApps/",
  "repositories": [
    {
      "name": "ReferenceApps-Repository",
      "url": "git@github.com:example/repo.git",
      "destination": "refApps"
    }
  ]
}

15. Localization

Localization errors often only appear at runtime. xcodex checks the .xcstrings file statically, before runtime issues occur.

xcodex

Localization: missing keys, duplicate keys and consistency check

16. Miscellaneous

Miscellaneous bundles functions that are needed less frequently but are critical in the right moment.

xcodex

Crash reports, Instruments and provisioning profile management

• Analyze Crash Reports — symbolizes .crash files and shows readable stack traces. Requires the matching .dSYM archive
• Instruments (Beta) — starts profiling sessions directly from xcodex
• Manage Provisioning Profiles — lists all local profiles and allows removal of expired ones

Provisioning profiles at a glance

xcodex

All local provisioning profiles at a glance — remove expired ones directly

17. Developer Resources

The last command group links to the most frequently needed documentation and management pages for Apple developers.

xcodex

Direct access to Apple documentation, App Store Connect and Swift Package Index

• Apple Developer Documentation
• Swift Documentation & Evolution Proposals
• Human Interface Guidelines
• App Store Connect
• Apple Developer Portal
• Swift Package Index

These links open directly in the default browser.

18. Common Issues

No scheme found

The working directory is not set correctly or the .xcworkspace/.xcodeproj file is not in the current directory. Launch xcodex from the project root.

Simulator not available

Open Xcode and install the desired simulator platforms. Then restart xcodex — the device list is updated automatically.

Build fails

Take the error message and affected file from the red output. For unexplained errors, delete DerivedData first (Clean & Cache) and then build again.

Xcode Command Line Tools missing

xcode-select --install

Restart the terminal after installation.

Push notification not working

The app must have Push Notifications enabled in the entitlements file and be correctly registered in the Apple Developer Portal. In the simulator, notifications are supported without an APNs certificate.

Permission error on launch

xcodex is not executable. Solution:

chmod +x /path/to/xcodex

"missing module" error after branch switch

Resolve dependencies after the branch switch: Build & Run → Resolve All Dependencies.

19. Everyday Tips

• Use an alias — add xcodex to ~/.zshrc so the command works from any directory
• Launch from the project directory — xcodex detects the project file automatically when started in the root directory of the project
• Before pull requests — run local builds and tests before creating a PR. This avoids failing CI pipelines
• Use isolated DerivedData — xcodex builds into an isolated directory, so Xcode builds are not affected
• After git pull — resolve dependencies first, then build
• Before a release build — check provisioning profiles and clear simulator cache
• Update regularly — git pull in the xcodex directory keeps the tool current

20. Disclaimer

xcodex is an independent open-source tool and is not affiliated with Apple Inc. "Xcode" and "TestFlight" are registered trademarks of Apple Inc. Use of this tool is at your own risk. No liability is accepted for damages arising from its use.