Flowdeck

FlowDeck CLI - Your Primary Build/Run/Test Interface

MANDATORY TRIGGER (READ FIRST)

Use this skill whenever the user asks to build, run, test (including automated tests), launch, debug, capture logs, take screenshots, manage simulators/devices/runtimes, install simulators, manage packages, sync provisioning, or "run the app" — even if they do not mention iOS, macOS, Xcode, or simulators. If the request could involve Apple tooling or CI automation, default to FlowDeck.

CONFIG-FIRST WORKFLOW (START HERE)

Before running ANY build, run, or test command, check for a saved FlowDeck config.

The user's config represents their chosen workspace, scheme, and simulator/device. Respect it.

Step 0: Check Config (ALWAYS)

flowdeck config get --json

This returns one of two results:

A) Config Exists - Use Bare Commands

The user has already chosen their settings. Use bare commands - no flags needed:

flowdeck build            # Uses saved workspace, scheme, target
flowdeck run              # Uses saved workspace, scheme, target
flowdeck test             # Uses saved workspace, scheme, target
flowdeck clean            # Uses saved workspace, scheme

Only add flags when the user explicitly asks for something different from the saved config:

Explicit CLI flags override config values for that invocation only - they do not change the saved config.

B) No Config Found - Create One

When you see No saved config found, create a config so all subsequent commands work without flags:

# 1. Discover what's available
flowdeck context --json

# 2. Create config based on what you find
flowdeck config set -w <workspace> -s <scheme> -S "<simulator>"

# 3. Now use bare commands
flowdeck build
flowdeck run
flowdeck test

How to pick values when creating config:

Tell the user what you're creating:

"No FlowDeck config found. I'll create one using [workspace] with scheme [scheme] on [simulator] based on the project structure."

Config Rules (NON-NEGOTIABLE)

1. NEVER run flowdeck config set --force over an existing config - the user chose those settings deliberately
2. NEVER run flowdeck config reset unless the user explicitly asks
3. If the config points to a simulator that doesn't exist, tell the user - don't silently change their config
4. If a bare command fails because of stale config, explain the issue and suggest the user update their config
5. Only create config when none exists - this is a one-time setup, not something you do every session

WHAT FLOWDECK GIVES YOU

FlowDeck provides capabilities you don't have otherwise:

FlowDeck is how you interact with iOS/macOS projects. You don't need to parse Xcode files, figure out build commands, or manage simulators manually.

CAPABILITIES (ACTIVATE THIS SKILL)

• Build, run, and test (unit/UI, automated, CI-friendly)
• Simulator and runtime management (list/create/install/boot/erase)
• UI automation for iOS simulators (flowdeck ui simulator for screen/record/find/tap/double-tap/type/swipe/scroll/back/pinch/wait/assert/erase/hide-keyboard/key/open-url/clear-state/rotate/button/touch)
• Device install/launch/uninstall and physical device targeting
• Log streaming, screenshots, and app lifecycle control
• Project discovery, schemes/configs, and JSON output for automation
• Package management (SPM resolve/update/clear) and provisioning sync
• FlowDeck skill-pack install/uninstall for supported AI agents

COMMAND SET RESOURCES

Each command set has its own reference doc. Use these for detailed flags, examples, and workflows.

• resources/config.md - Saved project settings (get/set/reset) - read this first
• resources/context.md - Project discovery (workspace/schemes/configs/simulators)
• resources/build.md - Build projects and targets
• resources/run.md - Run apps on simulator/device/macOS
• resources/test.md - Run tests and discover tests
• resources/clean.md - Clean build artifacts
• resources/apps.md - List running apps launched by FlowDeck
• resources/logs.md - Stream logs for a running app
• resources/stop.md - Stop a running app
• resources/uninstall.md - Uninstall an app from a simulator or device
• resources/simulator.md - Simulator management and runtimes
• resources/ui.md - UI automation for iOS Simulator
• resources/device.md - Physical device management
• resources/ai.md - Install or remove the FlowDeck skill pack for AI agents
• resources/pixel-perfect-design.md - Pixel-perfect UI implementation from design mockups
• resources/project.md - Project inspection and packages
• resources/package-resolution.md - Package resolution escalation playbook (update -> resolve -> clear -> clean)
• resources/license.md - License status/activate/deactivate
• resources/update.md - Update FlowDeck
• resources/init.md - Deprecated alias for config set

YOU HAVE COMPLETE VISIBILITY

+-------------------------------------------------------------+
|                    YOUR DEBUGGING LOOP                       |
+-------------------------------------------------------------+
|                                                             |
|   flowdeck config get --json       -> Check saved settings   |
|   (if none: context + config set)                            |
|                                                             |
|   flowdeck run                     -> Launch app, get App ID |
|                                                             |
|   flowdeck logs <app-id>           -> See runtime behavior   |
|                                                             |
|   flowdeck ui simulator session    -> See the UI             |
|     start -S <name-or-udid> --json    (read latest.jpg)      |
|                                                             |
|   Edit code -> Repeat                                        |
|                                                             |
+-------------------------------------------------------------+

Don't guess. Observe. Run the app, watch the logs, read session screenshots.

QUICK DECISIONS

COMMON APPLE CLI TRANSLATIONS

• If you see xcrun simctl spawn <udid> log show ..., use flowdeck apps then flowdeck logs <id>, or run with flowdeck run --log.
• If a predicate filter is needed, use flowdeck logs <id> --json | rg 'Pattern|thepattern' or flowdeck logs <id> | rg 'Pattern|thepattern'.
• If you need a bounded window like --last 2m, run flowdeck logs while reproducing the issue, then stop streaming after the window you need.

CRITICAL RULES

1. Always check flowdeck config get --json first - It tells you if the user has saved settings. If yes, use bare commands. If no, create a config before proceeding.
2. Use bare commands when config exists - flowdeck build, flowdeck run, flowdeck test with no flags. Only add flags for user-requested overrides.
3. Never overwrite user config - Don't run config set --force or config reset unless the user asks. Their config is their choice.
4. Use flowdeck run to launch apps - It returns an App ID for log streaming (and targetUdid in JSON mode)
5. Start a session BEFORE any UI work - flowdeck ui simulator session start -S "iPhone 16" --json. Parse the JSON output to get the latest_screenshot and latest_tree file paths. Use your Read tool on these paths to see the screen and inspect elements.
6. Verify after EVERY UI action - After each tap/type/swipe, wait ~1 second, then re-read latest_screenshot to confirm the UI changed. Never chain actions blindly.
7. Do not invent FlowDeck syntax - If a command errors or you are unsure about flags, subcommands, or keycodes, run flowdeck <command> --help or read the matching resource before retrying. Do not guess aliases like --skip-build, --x, --y, or string key names.
8. Use app-native navigation for browser tests - When validating a browser app, navigate through the browser's own address bar and controls. Do not use flowdeck ui simulator open-url for website navigation unless the user is explicitly testing deep links or external handoff.
9. Check flowdeck apps before launching - Know what's already running
10. On license errors, STOP - Tell user to visit flowdeck.studio/cli/purchase/

Tip: Most commands support --examples to print usage examples.

UI AUTOMATION GUIDANCE

Targeting a Simulator (-S)

Every flowdeck ui simulator ... command requires -S to target a simulator. It accepts either:

• A simulator name: -S "iPhone 16" — FlowDeck resolves it to a UDID automatically.
• A raw UDID: -S "A1B2C3D4-E5F6-7890-ABCD-EF1234567890" — used as-is.

Where to get the name or UDID:

1. flowdeck context --json — returns all simulators with name and udid fields.
2. flowdeck run ... --json — the app_registered event includes targetUdid.
3. flowdeck config get --json — returns the resolved UDID if flowdeck config set -S was used.

Never omit -S. Multiple simulators may be booted — omitting -S risks acting on the wrong one.

Sessions: How to See the Screen (MANDATORY)

A session continuously captures the simulator's accessibility tree and screenshot every 500ms and writes them to files on disk. You MUST start a session before doing any UI work. This is how you see what is on screen.

Step-by-step recipe

STEP 1  Start the session (do this ONCE before any UI interaction):

    flowdeck ui simulator session start -S "iPhone 16" --json

    Parse the JSON output. Extract these three absolute file paths:
      - latest_screenshot  →  e.g. "/path/to/.flowdeck/automation/sessions/9E6A58EF/latest.jpg"
      - latest_tree        →  e.g. "/path/to/.flowdeck/automation/sessions/9E6A58EF/latest-tree.json"
      - latest             →  e.g. "/path/to/.flowdeck/automation/sessions/9E6A58EF/latest.json" (in session_dir)

    Save these paths — you will reuse them for the rest of the session.

STEP 2  Read the tree to discover elements:

    Use your Read tool on the latest_tree path.
    The tree is a JSON array of elements with: label, id, role, frame, enabled, visible.
    Use element labels or IDs to target taps, finds, waits, and assertions.

STEP 3  Read the screenshot to see the UI:

    Use your Read tool on the latest_screenshot path.
    This is a JPEG image. You will see the current simulator screen.

STEP 4  Interact (tap, type, swipe, etc.):

    flowdeck ui simulator tap "Login" -S "iPhone 16" --json
    flowdeck ui simulator type "hello@example.com" -S "iPhone 16" --json

STEP 5  VERIFY after every action — read the screenshot and/or tree again:

    Use your Read tool on the SAME latest_screenshot and latest_tree paths.
    The session updates these files automatically (~500ms).
    Wait ~1 second after an action, then read to confirm the UI changed as expected.
    DO NOT skip this step. If you don't verify, you're guessing.

STEP 6  If the session appears stale, RESTART IT instead of switching tools:

    Symptoms of a stale session:
      - latest_screenshot/latest_tree still show the old screen after a real UI change
      - the frontmost app or dialog clearly changed, but the session files did not
      - multiple re-reads after a short wait still disagree with the actual simulator state

    Recovery:
      1. Run `flowdeck ui simulator session start -S "iPhone 16" --json` again.
         Starting a session automatically stops the previous one.
      2. Parse the new JSON output.
      3. Replace your saved `latest_screenshot`, `latest_tree`, and `latest` paths.
      4. Continue using the restarted session.

    Do NOT fall back to `flowdeck ui simulator screen` just because the session might be stale.
    Use `screen` only if the restarted session is still wrong or if you explicitly need a one-off static capture.

STEP 7  Repeat steps 4-6 for each interaction.

STEP 8  Stop the session when done:

    flowdeck ui simulator session stop -S "iPhone 16"

Key facts about sessions

• The session updates latest.jpg and latest-tree.json automatically whenever the UI changes.
• You do NOT need to run screen or any capture command between actions — just re-read the same file paths.
• Screenshots are JPEG at 50% quality, normalized to point coordinates (no @2x/@3x scaling needed).
• latest.json contains capture metadata (timestamp, dimensions).
• Starting a new session stops any active session automatically.

Verification Rules

These rules apply to ALL UI automation workflows:

1. After every tap/type/swipe/scroll action, wait ~1 second, then read latest.jpg to confirm the UI changed.
2. Before tapping an element, read latest-tree.json to confirm the element exists and is visible.
3. If an element is not in the tree, it may be off-screen. Use flowdeck ui simulator scroll --until "id:yourElement" -S "iPhone 16" first.
4. If the UI didn't change after an action, the action may have failed silently. Read the tree to check element state, then retry or try an alternative approach.
5. If the session looks stale, restart it immediately. Re-run flowdeck ui simulator session start -S ... --json, save the new file paths, and continue with the restarted session.
6. If a FlowDeck command errors, stop guessing. Run flowdeck ui simulator <subcommand> --help or read resources/ui.md before retrying.
7. For browser apps, use the browser itself. Type into the browser's address/search field and use in-app navigation controls. open-url is for deep-link/system handoff testing, not browser page validation.
8. Never chain more than 2-3 actions without verifying. Tap -> verify -> type -> verify -> tap -> verify.

One-off Screen Capture (Fallback Only)

Use flowdeck ui simulator screen only when sessions fail to start, a restarted session is still wrong, or you need a specific format:

flowdeck ui simulator screen -S "iPhone 16" --output /tmp/screenshot.png
flowdeck ui simulator screen -S "iPhone 16" --tree --json   # tree only

Other UI Automation Tips

• Prefer accessibility identifiers (--by-id) over labels — faster and more reliable.
• For off-screen elements, flowdeck ui simulator scroll --until "id:yourElement" -S "iPhone 16" before tapping.
• Tune input timing with FLOWDECK_HID_STABILIZATION_MS and FLOWDECK_TYPE_DELAY_MS when needed.

WORKFLOW EXAMPLES

Every workflow starts the same way: check config, then act.

User Reports a Bug

flowdeck config get --json                                  # Check saved settings
# If no config: flowdeck context --json -> flowdeck config set ...
flowdeck run                                                # Launch app
flowdeck apps                                               # Get app ID
flowdeck logs <app-id>                                      # Watch runtime

flowdeck ui simulator session start -S "iPhone 16" --json   # Start session on the active simulator
# Parse JSON → save latest_screenshot and latest_tree paths

# Read latest_screenshot with Read tool                     # SEE the current screen
# Read latest_tree with Read tool                           # SEE element labels/IDs

# Ask user to reproduce the bug, then:
# Read latest_screenshot again                              # SEE what changed
# Read latest_tree again                                    # INSPECT element state
# Analyze, fix code, re-run, verify again

flowdeck ui simulator session stop -S "iPhone 16"            # Stop session when done

User Says "It's Not Working"

flowdeck config get --json                                  # Check saved settings
# If no config: flowdeck context --json -> flowdeck config set ...
flowdeck run
flowdeck apps                                               # Get app ID

flowdeck ui simulator session start -S "iPhone 16" --json   # Start session on the active simulator
# Parse JSON → save latest_screenshot and latest_tree paths

flowdeck logs <app-id>                                      # See what's happening
# Read latest_screenshot with Read tool                     # NOW you have data, not guesses

flowdeck ui simulator session stop -S "iPhone 16"            # Stop session when done

Add a Feature

flowdeck config get --json                                  # Check saved settings
# If no config: flowdeck context --json -> flowdeck config set ...

# Implement the feature
flowdeck build                                              # Verify compilation
flowdeck run                                                # Test it

flowdeck ui simulator session start -S "iPhone 16" --json   # Start session on the active simulator
# Parse JSON → save latest_screenshot and latest_tree paths

# Read latest_screenshot with Read tool                     # Verify the feature looks right
# Read latest_tree with Read tool                           # Verify elements exist

# If you need to interact:
# flowdeck ui simulator tap "Button" -S "iPhone 16" --json  # Tap
# Read latest_screenshot again                              # VERIFY the tap worked

flowdeck ui simulator session stop -S "iPhone 16"            # Stop session when done

GLOBAL FLAGS & INTERACTIVE MODE