diff --git a/tools/cli.mdx b/tools/cli.mdx index 50b3926a..df56e16d 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -151,6 +151,31 @@ powersync pull instance --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`. + + + Connections that pass a password with `secret` always show `replication` as + changed, because the value is sent again on every deploy. + + ### 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. - 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. @@ -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 --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. +