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

Es gibt zwei Möglichkeiten, xcodex zu installieren:

• Git-Repository — vollständiger Quellcode, Updates einfach per git pull
• Installationspaket — notarisierte xcodex.pkg direkt herunterladen und per Installer einrichten

1) Git-Repository

1.1) Repository klonen

Dieser Befehl lädt den gesamten Quellcode von xcodex auf deinen Mac herunter. Git erstellt dabei das Verzeichnis ~/Developer/xcodex mit allen Dateien. Du benötigst Git, um Updates später einfach per git pull einzuspielen, ohne das Tool erneut manuell herunterzuladen.

git clone https://github.com/drapatzc/xcodex.git ~/Developer/xcodex

1.2) Ausführungsrechte setzen

macOS erlaubt standardmäßig nicht das direkte Ausführen von heruntergeladenen Dateien. Mit chmod +x gibst du dem Betriebssystem die Erlaubnis, die Datei xcodex als Programm zu starten. Dieser Schritt muss nur einmalig nach dem Klonen durchgeführt werden.

chmod +x ~/Developer/xcodex/xcodex

1.3) Shell-Alias einrichten (empfohlen)

Ein Shell-Alias sorgt dafür, dass du xcodex aus jedem beliebigen Verzeichnis starten kannst — ohne den vollständigen Pfad eintippen zu müssen. Der Alias wird dauerhaft in der Konfigurationsdatei deiner Shell gespeichert und ist ab dem nächsten Terminal-Start automatisch verfügbar.

echo 'alias xcodex="$HOME/Developer/xcodex/xcodex"' >> ~/.zshrc
source ~/.zshrc

echo 'alias xcodex="$HOME/Developer/xcodex/xcodex"' >> ~/.bash_profile
source ~/.bash_profile

alias xcodex="$HOME/Developer/xcodex/xcodex"
funcsave xcodex

1.4) Ausführen

Wechsle in das Wurzelverzeichnis deines Xcode-Projekts und starte xcodex. Beim ersten Start musst du dein Projekt oder Workspace manuell auswählen, damit das Tool alle nötigen Informationen erhält — Schema, Gerät und Konfiguration. Nur so kann xcodex deine App korrekt bauen und testen.

cd YourXcodeProject
xcodex

1.5) Aktualisieren

Mit git pull lädt Git die neuesten Änderungen aus dem Repository herunter und wendet sie auf deine lokale Kopie an. So bleibst du immer auf dem aktuellen Stand, ohne xcodex erneut klonen zu müssen.

cd ~/Developer/xcodex
git pull

2) Installationspaket

Das notarisierte xcodex.pkg Installationspaket kannst du direkt herunterladen. Apple hat die Datei geprüft und freigegeben, sodass sie den Sicherheitsanforderungen von macOS entspricht und ohne Warnmeldungen öffnet. Öffne das Paket und führe die Installation durch — xcodex wird automatisch nach /usr/local/bin/xcodex kopiert. Setz danach einen Shell-Alias und starte xcodex sofort. Updates spielst du ein, indem du die neue Version herunterlädst und das Installationspaket erneut ausführst.

4. Die Menü-Oberfläche

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

Am unteren Rand befindet sich eine Hotkey-Leiste mit 9 Schnellzugriffsbefehlen. Die zugehörigen Einträge in der Befehlsliste sind mit 1 bis 9 gekennzeichnet und lassen sich direkt über die entsprechende Zifferntaste aufrufen — ohne erst zur Gruppe navigieren zu müssen.

xcodex

Split-Pane-Interface: Befehlsgruppen links, Aktionen rechts

Alle Einstellungen bleiben automatisch zwischen den Sitzungen erhalten.

5. Erste Schritte — Projekt einrichten

Bevor du deine App auf einem Simulator oder echten Gerät bauen oder testen kannst, musst du xcodex einmal konfigurieren.

xcodex

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

Schritt 1 — Arbeitsverzeichnis auswählen

Im Hauptmenü drückst du A. Es öffnet sich der Datei-Browser, in dem du dein Xcode-Projekt (.xcodeproj) oder Workspace (.xcworkspace) auswählst.

Mit S bestätigst du die Auswahl. Anschließend wirst du gefragt, ob der Xcode-Cache (DerivedData) gelöscht werden soll. Optional werden danach auch die Abhängigkeiten neu aufgelöst.

Schritt 2 — App-Schema festlegen

Jetzt wählst du das App-Schema aus. Das Schema bestimmt, was gebaut wird und wie die App gestartet wird.

Schritt 3 — Test-Schema oder Testplan festlegen

Falls vorhanden, kannst du ein separates Test-Schema oder einen Testplan auswählen. Das ist sinnvoll, wenn deine Tests in einem eigenen Target oder über Testpläne organisiert sind.

Schritt 4 — Zielgerät auswählen

Als Nächstes wählst du das Gerät aus, auf dem gebaut oder getestet werden soll. Verfügbare Simulatoren sowie angeschlossene physische Geräte werden automatisch aus deiner Xcode-Installation erkannt.

Schritt 5 — Build-Konfiguration wählen

• Debug — für die tägliche Entwicklung mit Logs und Debug-Informationen
• Release — für optimierte Builds, z. B. für den App Store

Danach ist alles eingerichtet und du kannst direkt mit Build, Tests und weiteren Funktionen in xcodex starten.

Schnell-Shortcuts im Header

Im Hauptmenü sind im Header zusätzliche Einzel-Tastenkürzel aktiv, die den Konfigurationsfluss beschleunigen:

6. XCode-Ansicht vs. Browser-Ansicht

xcodex hat zwei Hauptansichten: die XCode-Ansicht mit allen Entwickler-Werkzeugen und die Browser-Ansicht — ein tastaturgesteuerter Datei-Browser. Kein Kontextwechsel, keine Maus, kein Fensterwechsel.

xcodex — Ansicht wechseln

Mit der Leertaste zwischen XCode-Ansicht und Browser-Ansicht wechseln

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

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

Mit der Taste + lassen sich weitere Zielgeräte hinzufügen, sodass die App parallel auf mehreren Betriebssystemen läuft. So können etwa Unterschiede zwischen iPhone und iPad oder verschiedenen iOS-Versionen direkt im Vergleich erkannt werden.

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.

9. 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ü

10. Simulator & Physische Geräte

Je nach ausgewähltem Zielgerät zeigt xcodex entweder die Simulator-Gruppe oder die Physische-Geräte-Gruppe an — nie beide gleichzeitig. Die verfügbaren Aktionen passen sich automatisch an das aktive Gerät an.

Simulator

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

1. Interaktion

2. Erscheinungsbild

3. Berechtigungen

4. Sprache & Region

5. Laufzeit

6. Gerät & System

7. Daten

8. Logs & Diagnose

9. Live Activities

10. WidgetKit

11. App Clips

Physische Geräte

Die Gruppe steuert direkt angeschlossene iOS-Geräte über USB oder WLAN. Sie ist nur sichtbar, wenn ein physisches Gerät als Ziel ausgewählt ist.

xcodex

Vollständige Geräteverwaltung für physische iOS-Geräte direkt im Terminal

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

Testergebnisse & Auswertung

Die Testergebnisse werden klar und direkt dargestellt:

• ✅ Bestanden – Test erfolgreich ausgeführt
• ⚠️ Übersprungen – Test wurde nicht ausgeführt
• ❌ Fehlgeschlagen – Test ist fehlgeschlagen

Tests erweitern

Mit der Taste + kannst du Tests auf weitere Geräte ausweiten. So lässt sich das Verhalten deiner App parallel auf unterschiedlichen Simulatoren oder Geräten prüfen.

Code Coverage

Mit der Taste C öffnest du die Code-Coverage. Diese wird übersichtlich als Baumstruktur dargestellt und zeigt dir direkt, welche Dateien und Klassen durch Tests abgedeckt sind – und wo noch Lücken bestehen.

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

Mit der Code-Coverage-Ansicht siehst du direkt, wie gut dein Projekt durch Tests abgedeckt ist. xcodex kann Testläufe mit aktivierter Coverage starten, Ergebnisse auswerten und dir zeigen, welche Bereiche bereits gut getestet sind und wo noch Lücken bestehen. Das hilft dir, Schwachstellen früh zu erkennen, bevor sie im Review, in der CI/CD-Pipeline oder später im Release auffallen.

xcodex

Code Coverage auf Dateiebene: schnell identifizieren, wo Tests fehlen

Automatisierte Tests

Die Ansicht für automatisierte Tests bündelt wiederkehrende Testläufe in einem klaren Terminal-Workflow. Du kannst Unit-Tests gezielt ausführen und verschiedene Kombinationen aus Schema, Device und Konfiguration testen. Damit lassen sich typische Prüfungen vor einem Pull Request oder Release schneller wiederholen, ohne jedes Mal lange xcodebuild-Befehle zusammenzubauen.

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

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

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

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

15. Lokalisierung

Fehler in der Lokalisierung fallen oft erst zur Laufzeit auf – dann, wenn die App bereits ausgeliefert ist. xcodex prüft die .xcstrings-Datei vollständig statisch, ohne Build-Prozess und ohne Xcode. Fehlende Keys, doppelte Einträge und Inkonsistenzen zwischen Sprachen werden sofort sichtbar gemacht. So lassen sich Lokalisierungsprobleme schon während der Entwicklung erkennen und beheben, bevor sie den Nutzer erreichen.

xcodex

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

16. Programme

Die Befehlsgruppe „Programme" ermöglicht es, häufig verwendete macOS-Apps direkt aus der Toolbox heraus zu öffnen — ohne Dock, Spotlight oder Finder. Nur tatsächlich installierte Apps erscheinen in der Liste. Apps werden über ihren vollständigen Pfad gestartet, was auf macOS 26+ zuverlässiger ist als der open -a-Befehl.

Programme

Häufig verwendete macOS-Apps direkt aus der Toolbox öffnen

17. Verschiedenes

Unter Verschiedenes sind Funktionen gebündelt, die seltener im täglichen Workflow vorkommen, aber im richtigen Moment entscheidend sein können. Dazu gehören die Analyse von Crash Reports, das Starten von Instruments-Sessions und die Verwaltung von Provisioning Profiles. Gerade bei schwer reproduzierbaren Abstürzen oder Build-Problemen kurz vor einem Release sind diese Werkzeuge unverzichtbar – und direkt aus xcodex heraus erreichbar.

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

Diese Ansicht zeigt dir alle lokal verfügbaren Provisioning Profiles auf einen Blick. Du erkennst sofort, welche gültig sind, zu welcher App sie gehören und wo es Probleme gibt. So findest du schnell die Ursache, wenn Builds lokal nicht laufen – ohne dich durch Xcode klicken zu müssen.

xcodex

Alle lokalen Provisioning Profiles auf einen Blick — abgelaufene direkt entfernen

18. Entwicklungsumgebungen isolieren

Diese Funktion klont ein Repository in ein separates Verzeichnis auf der Festplatte. Die eigene Entwicklungsumgebung bleibt dabei vollständig unberührt. Man kann so z. B. einen Feature-Branch parallel auschecken und mit xcodex testen — während Xcode weiterhin am eigenen Branch arbeitet.

xcodex

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

Workflow

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

Da xcodex nicht wissen kann, welches Repository geklont werden soll und wohin, muss man vorab eine JSON-Konfigurationsdatei erstellen und an einem beliebigen Ort auf der Festplatte ablegen. Diese Datei wird einmalig über Auswahl geladen und anschließend gespeichert — beim nächsten Start ist sie automatisch vorausgewählt.

Das vollständige Verzeichnis des geklonten Repositories ergibt sich aus: base + destination. Im Beispiel unten also: /Users/drapatz/Downloads/tempApps/refApps/

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

19. Developer-Ressourcen

In der letzten Befehlsgruppe sind die am häufigsten benötigten Dokumentations- und Verwaltungsseiten für Apple-Entwickler gebündelt – von der Apple Developer Documentation über App Store Connect bis zum Swift Package Index.

xcodex

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

20. Browser-Ansicht

Die Browser-Ansicht ist ein vollständig per Tastatur bedienbarer Datei-Browser direkt in xcodex. Du navigierst durch Verzeichnisse, öffnest Dateien, setzt Favoriten und führst Suchen oder Filter aus – alles ohne Maus und ohne Kontextwechsel.

Browser-Ansicht

Tastaturgesteuerter Datei-Browser direkt in xcodex

Hotkeys

xcodex ist vollständig auf schnelle Tastatursteuerung ausgelegt. Häufige Aktionen lassen sich direkt über Hotkeys starten, ohne durch lange Menüs zu springen.

Hilfe

In der Browser-Ansicht steht dir eine kontextsensitive Hilfe zur Verfügung. Drücke H, um das Hilfe-Overlay einzublenden. Es zeigt alle verfügbaren Tastenkürzel und Aktionen für die aktuelle Ansicht — übersichtlich und direkt aufrufbar, ohne die Browser-Ansicht zu verlassen.

Hilfe

Kontextsensitive Hilfe — alle Tastenkürzel auf einen Blick

Favoriten

Für häufig genutzte Verzeichnisse kannst du dir bis zu 10 Schnellzugriffe anlegen. Mit den Tasten 0–9 speicherst du deine Favoriten, mit Shift + 0–9 springst du direkt dorthin. Alternativ wechselst du mit W schnell zwischen Browser- und Favoriten-Ansicht.

Favoriten

Verzeichnisse als Favoriten speichern und direkt per Ziffer aufrufen

Suche

Die integrierte Suche durchsucht das aktuelle Verzeichnis inklusive aller Unterordner. Wildcards wie * werden unterstützt, sodass du flexibel nach Dateinamen filtern kannst. Die Treffer werden inklusive vollständigem Pfad angezeigt und lassen sich direkt öffnen.

Suche

Verzeichnissuche: Suchbegriff eingeben

Suchergebnisse

Suchergebnisse: direkte Navigation zu gefundenen Verzeichnissen

Filter

Mit Filtern kannst du gezielt bestimmte Dateitypen anzeigen, zum Beispiel Xcode-Projektdateien oder JSON-Dateien. Auch hier bekommst du eine übersichtliche Liste mit Pfadangaben und kannst die gewünschten Dateien sofort öffnen.

Filter

Filter: Dateiliste nach Begriff einschränken

Gefilterte Ansicht

Gefilterte Verzeichnisansicht — nur passende Einträge werden angezeigt

Schnellzugriff

• Pfad kopieren (Z) — Kopiert den absoluten Pfad in die Zwischenablage. Nützlich für externe Tools wie Claude Code.
• In Finder oder Terminal öffnen (W) — Öffnet das aktuelle Verzeichnis direkt. Ideal für die Weiterarbeit mit Claude Code.
• Datei öffnen (Return) — Öffnet Xcode-Projekte, Office-Dateien oder andere Formate sofort mit dem passenden Programm.

Diese kleinen Funktionen sparen Zeit und unterstützen dich im Alltag, ohne den Flow zu unterbrechen.

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

22. Tipps für den Alltag

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

The following requirements must be met before installation:

Clone the repository

This command downloads the complete xcodex source code to your Mac. Git creates the directory ~/Developer/xcodex containing all files. Having a Git clone lets you apply future updates with a single git pull — no need to re-download manually.

git clone https://github.com/drapatzc/xcodex.git ~/Developer/xcodex

Set executable permission

By default, macOS does not allow running downloaded files as programs. chmod +x grants the operating system permission to execute the xcodex file. This step only needs to be done once after cloning.

chmod +x ~/Developer/xcodex/xcodex

Set up shell alias (recommended)

A shell alias lets you run xcodex from any directory without typing the full path. The alias is saved permanently in your shell's configuration file and is available automatically from the next terminal session onward.

echo 'alias xcodex="$HOME/Developer/xcodex/xcodex"' >> ~/.zshrc
source ~/.zshrc

echo 'alias xcodex="$HOME/Developer/xcodex/xcodex"' >> ~/.bash_profile
source ~/.bash_profile

alias xcodex="$HOME/Developer/xcodex/xcodex"
funcsave xcodex

Run

Navigate to your Xcode project's root directory and launch xcodex. On first launch you need to manually select your project or workspace so xcodex has all the information it needs — scheme, device and build configuration. Only then can xcodex correctly build and test your app.

cd YourXcodeProject
xcodex

Update

git pull downloads the latest changes from the repository and applies them to your local copy. This keeps xcodex up to date without needing to clone it again.

cd ~/Developer/xcodex
git pull

Download xcodex directly

You can also download the notarized xcodex.zip directly — no Git clone required. Download the ZIP file, unzip it and place the binary in a fixed path (e.g. ~/Developer/xcodex/). Then only follow steps 2 to 4: set executable permission, configure the shell alias and run xcodex. Updates need to be applied manually by re-downloading.

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

5. Getting Started — Project Setup

On first launch from a project directory, xcodex needs to be configured once.

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

Quick shortcuts in the header

In the main menu, additional single-key shortcuts are active in the header to speed up the configuration flow:

6. XCode View vs. Browser View

xcodex offers two main views you can switch between at any time: the XCode view with all developer tools and the Browser view — a keyboard-driven file browser.

xcodex — Switch View

Switch between XCode view and Browser view using the Space key

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

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

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

10. Simulator & Physical Devices

Depending on the selected target device, xcodex shows either the Simulator group or the Physical Devices group — never both at the same time. The available actions automatically adapt to the active device.

Simulator

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

1. Interaction

2. Appearance

3. Permissions

4. Language & Region

5. Runtime

6. Device & System

7. Data

8. Logs & Diagnostics

9. Live Activities

10. WidgetKit

11. App Clips

Physical Devices

This group controls directly connected iOS devices via USB or Wi-Fi. It is only visible when a physical device is selected as the target.

xcodex

Full device management for physical iOS devices directly in the terminal

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

The code coverage view shows you directly how well your project is covered by tests. xcodex can run test suites with coverage enabled, evaluate the results and show you which areas are already well tested and where gaps remain. This helps you spot weaknesses early — before they surface in a review, a CI/CD pipeline or a release.

xcodex

Code coverage per file: quickly identify where tests are missing

Automated Tests

The automated tests view bundles recurring test runs into a clear terminal workflow. You can run unit tests selectively and test different combinations of scheme, device and configuration. This lets you repeat typical pre-pull-request or pre-release checks faster, without having to reassemble long xcodebuild commands each time.

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

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

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

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

15. Localization

Localization errors often only surface at runtime — when the app has already been shipped. xcodex checks the .xcstrings file fully statically, without a build process and without Xcode. Missing keys, duplicate entries and inconsistencies between languages are made immediately visible. This allows localization issues to be caught and fixed during development, before they reach the user.

xcodex

Localization: missing keys, duplicate keys and consistency check

16. Apps

The "Apps" command group lets you open frequently used macOS apps directly from the toolbox — no Dock, Spotlight or Finder required. Only apps that are actually installed appear in the list. Apps are launched via their full path, which is more reliable on macOS 26+ than the open -a command.

Apps

Open frequently used macOS apps directly from the toolbox

17. Miscellaneous

Miscellaneous bundles functions that appear less frequently in the daily workflow but can be critical at the right moment. This includes analyzing crash reports, launching Instruments sessions, and managing provisioning profiles. Especially with hard-to-reproduce crashes or build issues right before a release, these tools are invaluable — and accessible directly from xcodex.

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

This view shows you all locally available provisioning profiles at a glance. You can see immediately which ones are valid, which app they belong to and where problems exist. This quickly reveals the cause when builds fail locally — without having to click through Xcode.

xcodex

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

18. Isolated Development Environments

This feature clones a repository into a separate directory on disk. Your own development environment remains completely untouched. You can, for example, check out a feature branch in parallel and test it with xcodex — while Xcode continues working on your own branch.

xcodex

Isolated environments: QA and testers can build and test independently

Workflow

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

Since xcodex cannot know which repository to clone or where, you need to create a JSON configuration file in advance and place it anywhere on disk. This file is loaded once via Select and saved — on the next launch it is automatically pre-selected.

The full path of the cloned repository is: base + destination. In the example below: /Users/username/Downloads/tempApps/refApps/

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

19. Developer Resources

The last command group bundles the most frequently needed documentation and management pages for Apple developers — from Apple Developer Documentation to App Store Connect and the Swift Package Index.

xcodex

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

20. Browser View

The Browser view is a fully keyboard-driven file browser directly in xcodex. You navigate through directories, open files, set favorites and perform searches or filters — all without a mouse and without switching context.

Browser View

Keyboard-driven file browser directly in xcodex

Hotkeys

xcodex is built for fast keyboard control throughout. Common actions can be triggered directly via hotkeys, without navigating through long menus.

Help

The Browser view includes context-sensitive help. Press H to open the help overlay. It shows all available keyboard shortcuts and actions for the current view — clearly laid out and accessible without leaving the Browser view.

Help

Context-sensitive help — all keyboard shortcuts at a glance

Favorites

You can set up to 10 quick-access shortcuts for frequently used directories. Use keys 0–9 to save your favorites and Shift + 0–9 to jump directly to them. Alternatively, press W to switch quickly between the browser and favorites view.

Favorites

Save directories as favorites and access them directly with a number key

Search

The built-in search scans the current directory including all subdirectories. Wildcards such as * are supported, letting you filter flexibly by filename. Results are shown with the full path and can be opened directly.

Search

Directory search: enter search term

Search Results

Search results: direct navigation to found directories

Filter

With filters you can display specific file types, for example Xcode project files or JSON files. You get a clear list with path information and can open the desired files immediately.

Filter

Filter: narrow the file list by term

Filtered View

Filtered directory view — only matching entries are shown

Quick Access

• Copy path (Z) — Copies the absolute path to the clipboard. Useful for external tools such as Claude Code.
• Open in Finder or Terminal (W) — Opens the current directory directly. Ideal for continuing work with Claude Code.
• Open file (Return) — Opens Xcode projects, Office files or other formats immediately with the appropriate application.

These small features save time and support your daily workflow without interrupting your flow.

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

22. Everyday Tips

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