Dry-Run Previews

Use --dry-run to validate a supported mutating command and inspect the operation FlowDeck would perform without executing it.

flowdeck build --dry-run
flowdeck project packages add https://github.com/apple/swift-collections --dry-run
flowdeck simulator erase SIMULATOR-UDID --dry-run

Read-only commands do not accept --dry-run. For example, flowdeck project packages list already has no side effects, so run it directly.

Dry-run availability is command-specific. Check flowdeck <command> --help before relying on it in automation.

Human-readable output

Without --json, FlowDeck prints the command or commands it would execute:

🔍 Dry Run - Command that would be executed:

xcrun simctl boot SIMULATOR-UDID

JSON contract

Combine --dry-run with --json for a normalized machine-readable preview:

flowdeck simulator boot SIMULATOR-UDID --dry-run --json

{
  "success": true,
  "type": "dry_run",
  "command": "xcrun simctl boot SIMULATOR-UDID",
  "argv": ["xcrun", "simctl", "boot", "SIMULATOR-UDID"],
  "schema": "flowdeck.simulator",
  "schemaVersion": "1.0.0"
}

The stable fields are:

Field	Type	Description
`success`	boolean	Always `true` when the preview was produced successfully
`type`	string	Always `dry_run`
`command`	string	Human-readable command preview
`argv`	string array	Argument-safe representation of the first command
`schema`	string	Command-family schema identifier, when that command has one
`schemaVersion`	string	Version of the emitted JSON contract
`note`	string	Optional context for a preview step

Commands that require multiple operations also include a commands array. Each entry contains its own command, argv, and optional note:

{
  "success": true,
  "type": "dry_run",
  "command": "first command\nsecond command",
  "argv": ["first", "command"],
  "commands": [
    {
      "command": "first command",
      "argv": ["first", "command"]
    },
    {
      "command": "second command",
      "argv": ["second", "command"],
      "note": "Follow-up operation"
    }
  ],
  "schemaVersion": "1.0.0"
}

Use argv rather than splitting command when feeding a preview into other tooling.

Validation behavior

A dry run still validates required arguments and command-specific input. It can also resolve saved project settings needed to construct the preview. It does not boot, erase, install, launch, record, write project files, or perform the requested mutation. See Automation & Scripting for JSON-stream processing and configuration examples.

Overview

FlowDeck for AI

Interactive Mode (TUI)

Core Features

Command Reference

Advanced

Support

Human-readable output

JSON contract

Validation behavior

​Human-readable output

​JSON contract

​Validation behavior

Human-readable output

JSON contract

Validation behavior