Document CLI dry run

tools/cli.mdx

@@ -151,6 +151,31 @@ powersync pull instance --instance-id=<instance-id>
 
 Then edit `service.yaml` and `sync-config.yaml` as needed, run `powersync validate`, and `powersync deploy`. Run `powersync pull instance` again (no IDs if already linked) to refresh from the cloud.
 
+A repeat pull does not overwrite your local files by default. If `service.yaml` or `sync-config.yaml` already exists, the CLI warns you and writes that file's fetched version alongside it as `service-fetched.yaml` or `sync-fetched.yaml`, so your local edits survive and you can merge in the changes you want. Add `--overwrite` to replace the local files instead.
+
+### Preview a Deploy
+
+Every deploy command accepts `--dry-run`, which shows what the command would do without changing the instance:
+
+```bash
+powersync deploy --dry-run
+powersync deploy service-config --dry-run
+powersync deploy sync-config --dry-run
+```
+
+The command prints the target instance, runs the deploy validations, and then summarizes what would change: the `service.yaml` sections that differ from the deployed config, and a diff of the Sync Config. Nothing is deployed.
+
+Each command previews only what it deploys. `powersync deploy service-config --dry-run` reports the Sync Config as unchanged, and `powersync deploy sync-config --dry-run` reports the service config as unchanged.
+
+If the instance is not provisioned yet, the dry run skips Sync Config validation, because that check runs against a running instance.
+
+The service config summary lists section names only, because `service.yaml` holds connection strings and other secrets. To compare the full file, run `powersync pull instance` and diff the resulting `service-fetched.yaml` against your `service.yaml`.
+
+<Note>
+  Connections that pass a password with `secret` always show `replication` as
+  changed, because the value is sent again on every deploy.
+</Note>
+
 ### Run Commands Without Local Config
 
 To run commands (e.g. `powersync generate schema`, `powersync status`) against an instance managed elsewhere (e.g. Dashboard):
@@ -159,10 +184,10 @@ To run commands (e.g. `powersync generate schema`, `powersync status`) against a
 - **Or pass each time:** `--instance-id`, or set `INSTANCE_ID` in the environment.
 
 <Info>
-  The CLI resolves instance and linking context in a fixed order: flags take
-  precedence, then environment variables, then values in `cli.yaml`. For the
-  full resolution order and how to set up multiple instances (e.g. dev, staging,
-  prod), see [supplying linking information for Cloud and self-hosted
+  The CLI resolves the instance in a fixed order: flags first, then
+  `cli.yaml`, then environment variables. For the full resolution order and
+  how to set up multiple instances (e.g. dev, staging, prod), see [supplying
+  linking information for Cloud and self-hosted
   commands](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#supplying-linking-information-for-cloud-and-self-hosted-commands)
   in the CLI usage docs.
 </Info>
@@ -254,6 +279,7 @@ Then use the same commands as any self-hosted instance (`powersync status`, `pow
 | `powersync deploy`                                              | Deploy full config to linked Cloud instance                                        |
 | `powersync deploy service-config`                               | [Cloud] Deploy only service config                                                 |
 | `powersync deploy sync-config`                                  | [Cloud] Deploy only Sync Config                                                    |
+| `--dry-run` (any deploy command)                                | [Cloud] Validate and preview what that command would change, without deploying     |
 | `powersync validate`                                            | Validate config and Sync Streams/Rules                                             |
 | `powersync edit config`                                         | Open Config Studio (Monaco editor)                                                 |
 | `powersync status`                                              | Instance diagnostics (Cloud and self-hosted)                                       |
@@ -266,6 +292,8 @@ Then use the same commands as any self-hosted instance (`powersync status`, `pow
 | `powersync stop --confirm=yes`                                  | [Cloud] Stop instance (restart with deploy)                                        |
 | `powersync compact`                                             | [Cloud] Trigger [bucket compacting](/maintenance-ops/compacting-buckets) on demand |
 
+The CLI prints the instance it is about to act on before `powersync deploy`, `powersync stop`, `powersync destroy`, and `powersync compact` make any change, and at the start of `powersync status`. For a Cloud instance, the line shows the instance name with the instance, project, and organization IDs. For a self-hosted instance, it shows the API URL. Check this line before you confirm a destructive command.
+
 Run `powersync --help` or `powersync <command> --help` for flags. Full [command reference](https://github.com/powersync-ja/powersync-cli/blob/main/cli/README.md#commands) in the CLI repo.
 
 ## Deploying From CI (e.g. GitHub Actions)
@@ -274,6 +302,8 @@ You can automate Sync Config (and full config) deployments using the CLI in CI.
 
 **Secrets:** Set `PS_ADMIN_TOKEN` to your PowerSync personal access token. If the workflow does not use a linked directory, also set `INSTANCE_ID`. For self-hosted, `API_URL` can specify the PowerSync API base URL.
 
+The job log records the target instance line, so you can see which instance a run changed. For pull request checks, run `powersync deploy --dry-run` to validate the config and preview the changes without deploying.
+
 <Card
   title="GitHub Actions Demo"
   icon="github"
@@ -312,7 +342,7 @@ More information is available in the [PowerSync CLI repository](https://github.c
 | Resource                                                                                                   | Description                                                                                                                                                                                                         |
 | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [CLI README](https://github.com/powersync-ja/powersync-cli/blob/main/cli/README.md)                        | Getting started, Cloud and self-hosted overview, and full **command reference** with all flags.                                                                                                                     |
-| [General usage](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md)                     | **How the CLI works**: local config vs linking, resolution order (flags → env vars → `cli.yaml`), and **configuring multiple instances** (e.g. dev/staging/prod with separate directories or `!env` in `cli.yaml`). |
+| [General usage](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md)                     | **How the CLI works**: local config vs linking, resolution order (flags → `cli.yaml` → env vars), and **configuring multiple instances** (e.g. dev/staging/prod with separate directories or `!env` in `cli.yaml`). |
 | [Docker (local development)](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) | Self-hosted Docker workflow, configure/start/stop/reset, database and storage modules, and template layout.                                                                                                         |
 | [Config Studio (editor)](https://github.com/powersync-ja/powersync-cli/tree/main/packages/editor)          | Built-in Monaco-powered editor for `service.yaml` and `sync-config.yaml` (`powersync edit config`), schema validation, and local development.                                                                       |
 | [Examples](https://github.com/powersync-ja/powersync-cli/blob/main/examples/README.md)                     | Sample projects initialized with the CLI (e.g. Cloud pull, self-hosted Postgres, self-hosted Supabase).                                                                                                             |