Before you start
This guide assumes:
FlowDeck is installed and your license or trial is active. If not, follow the getting-started guide first.
You have an Xcode project to drive. Anything with an
.xcodeprojor.xcworkspaceworks.A terminal you're comfortable with. The CLI is also happy inside
tmux, CI runners, or whatever shell you script in.
By the end you'll know how to configure a project, build, run, stream logs, run tests, manage simulators and devices, clean caches, and emit structured JSON from every command.
Discover and configure your project
Switch into your Xcode project's directory. FlowDeck reads the project from disk; no installation step inside Xcode, no fastlane init-style setup.
The context command parses the workspace and prints what it found: workspaces, schemes, build configurations, available simulators, and connected devices. It's the equivalent of xcodebuild -list, but it parses the project natively instead of compiling anything, so it returns instantly.
If you'd rather consume the result as data, ask for JSON:
Pick a scheme to work with and save it so you don't have to repeat it on every command:
To inspect the saved config, or to read individual values:
The config lives in .flowdeck/config.json alongside your project. Safe to check into version control (no secrets) or to .gitignore, whichever your team prefers. If you ever want to start fresh, flowdeck config reset wipes it.
Build, run, and stop
With the config saved, every subsequent command picks up the workspace, scheme, and simulator automatically. Run a build:
FlowDeck shells out to xcodebuild under the hood; the build itself is identical to what Xcode runs, but the output is summarized into the lines that matter: compile errors, warnings, and the success/failure status. Pass --verbose for the raw xcodebuild output, or --json for a structured stream of build events.
To build, install, and launch in one command:
FlowDeck boots the simulator named in your config (override with -S "iPhone 16 Pro" for a one-off, or -D "Daniel's iPhone" for a physical device). The output ends with the app's short ID, which addresses the running app from other commands:
List every app FlowDeck has running, and stop one (or all) cleanly:
FlowDeck refuses to silently replace a running app, so if flowdeck run blocks on "already running," flowdeck stop first.
Stream the app's logs
In a second terminal (so the first one stays free), find your running app and stream its output:
You'll see your print() calls, your OSLog messages, and any runtime errors the app emits, and only those. No SpringBoard, no nsurlsessiond, no other process bleeding into the stream.
Pass --json if you want each log line as a structured event (useful for CI artifacts or piping into jq):
A shorthand for launching and streaming in one command:
Discover and run tests
FlowDeck discovers tests by parsing your Swift source files directly. No build required. List what's available:
Want it as data? Same flag pattern:
Run a specific test, class, or whole target:
Skip slow tests instead of selecting fast ones:
Output is the same shape every time: a stream of pass/fail/skip events, plus a final summary. Add --json for a structured stream you can pipe into jq or a CI reporter.
Manage simulators and devices
List every simulator on the machine, in any state, with their runtime:
Boot a specific simulator by name (FlowDeck handles UDID lookup for you):
Create a new simulator from a device type and runtime:
Install a missing iOS runtime from Apple's catalog (handy in CI when a fresh image is missing a runtime your project needs):
For physical devices, list what FlowDeck can see:
Pairing a device for the first time still happens through Xcode (plug in over USB, trust the prompt on the device). After that, FlowDeck sees the device for the rest of its life. The physical devices guide covers the one-time setup.
To target a device for a single build or run, swap the saved simulator for a device with the -D flag:
Clean, reset, and recover
Two levels of clean, depending on how stuck things are:
When Swift Package Manager state is corrupt, force a re-resolve:
When code-signing fails (expired provisioning profile, new device, fresh CI runner), sync provisioning profiles from your Apple Developer account:
To start a brand-new project from the CLI (the same wizard the TUI uses, but scriptable, so it works in CI or a non-interactive shell):
If you'd rather drive the same flow interactively, run flowdeck -i from an empty folder and the TUI's new-project wizard runs automatically. See the getting-started guide for the wizard walkthrough.
Speak JSON to scripts, CI, and agents
Every command accepts --json and emits versioned NDJSON: one event per line, schema documented and stable across minor releases. The same shape applies to build events, test events, log lines, simulator state, and UI automation results.
For a quick taste, watch a build's events as they happen:
The output is one event per line: build_started, compile, warning, error, build_completed. Filter, reformat, or hand it to an agent.
The same flag works on every command that produces output, useful when you want one consistent contract across your CI scripts:
Common patterns from here
Once the basic build-run-test loop feels natural, the patterns that come up most often:
Switch simulators or devices on the fly.
Any command accepts -S "iPhone 16 Pro" (simulator) or -D "Daniel's iPhone" (device) to override the saved config for a single call. To change the default, use flowdeck config set -S "iPhone 16 Pro".
Run on a physical device.
Pair and trust once in Xcode, then flowdeck run -D "Daniel's iPhone". After that, every command works the same as on a simulator. Logs, tests, UI automation, all of it.
Mix CLI and TUI in the same project.
The TUI (flowdeck -i) and the CLI share .flowdeck/config.json. Drive a build in the TUI, run a one-off scripted test from the CLI, then go back to the TUI. State stays consistent.
Wire FlowDeck into CI.
The same commands work in GitHub Actions, Bitrise, or any runner with macOS and Xcode. The CI automation guide walks through a working pipeline.
Use it from your editor.
The VS Code / Cursor extension surfaces the same commands as menu items and status-bar buttons. Install free from the marketplace.
How this compares to Apple's tools
For reference, the same five operations done with Apple's CLIs and with FlowDeck side by side.
What you're doing | Apple's tools | FlowDeck |
|---|---|---|
Discover schemes |
|
|
Build and run on a simulator |
|
|
Stream this app's logs |
|
|
Run one test |
|
|
Parse output | Regex over hundreds of lines of stdout |
|
Full side-by-side at FlowDeck vs xcodebuild.
When things go wrong
flowdeck context says “No workspace found”
“Simulator not found” when running
Build succeeds but launch is blocked
No logs streaming
Code signing fails on a fresh machine or runner
Swift Package state is wedged