> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowdeck.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Dry-Run Previews

> Preview mutating FlowDeck commands without changing local state

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

```bash theme={null}
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.

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

## Human-readable output

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

```text theme={null}
🔍 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:

```bash theme={null}
flowdeck simulator boot SIMULATOR-UDID --dry-run --json
```

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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](/cli/automation) for JSON-stream processing and configuration examples.