From a4bfe32f367c33bc6d1cef460b8b75d56bc1737d Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Mon, 23 Feb 2026 16:20:17 +0200 Subject: [PATCH 01/20] New CLI into docs --- tools/cli.mdx | 227 ++++++++++++++++++++++++++++++++++++++------- tools/overview.mdx | 4 +- 2 files changed, 193 insertions(+), 38 deletions(-) diff --git a/tools/cli.mdx b/tools/cli.mdx index c4c83982..c49a999b 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -1,69 +1,224 @@ --- -title: "CLI (Beta)" -description: "Manage your PowerSync Cloud environment programmatically" +title: "CLI" +description: "Manage PowerSync Cloud and self-hosted instances from the command line with config-as-code." --- -You can use the [PowerSync CLI](https://www.npmjs.com/package/powersync) to manage your PowerSync Cloud instances from your machine. Specifically, you can: +The PowerSync CLI lets you manage PowerSync Service instances, deploy sync config (your Sync Streams or Sync Rules), generate client schemas, and run diagnostics. It is distributed as the [powersync](https://www.npmjs.com/package/powersync) npm package. -* Manage your [PowerSync instances ](/architecture/powersync-service)(PowerSync Cloud) -* Validate and deploy [Sync Rules](/sync/rules/overview) to an instance from a local file -* Generate the [client-side schema](/intro/setup-guide#define-your-client-side-schema) +**Cloud:** Full support for PowerSync Cloud. Log in with a personal access token, then define your instance config in a `powersync/` directory (`service.yaml`, `sync.yaml`) and deploy with `powersync deploy`. - - The PowerSync CLI is not yet compatible with managing self-hosted PowerSync instances (PowerSync Open Edition and PowerSync Enterprise Self-Hosted Edition). This is on our roadmap. - +**Self-hosted:** You can link to an existing PowerSync Service instance and run a subset of commands (e.g. `powersync fetch status`, `powersync generate schema`, `powersync validate`). A Docker plugin is available for local self-hosted development. -### Getting started + + The PowerSync CLI was overhauled in **version TODO** (see the [powersync](https://www.npmjs.com/package/powersync) npm package for the current release). The redesign is based on this [public proposal](https://docs.google.com/document/d/1iqpJF2gog2jB-ZWeN8TBEjcad8aBKNKbue2yJ21q_-s/edit). + + Main improvements in the new version: **self-hosted support** (link to your own PowerSync Service and run commands such as fetch status, generate schema, validate); **open source**; and **improved DX**, including validated config files (`service.yaml`, `sync.yaml`) used for creating and deploying changes to PowerSync instances instead of long command-line flags. -To begin, initialize the CLI via `npx`: + See [Migrating from the previous CLI](#migrating-from-the-previous-cli) if you used the older flow. + + +## Installation + +Install globally or run via `npx`: + +```bash +npm install -g powersync +``` ```bash -npx powersync init +npx powersync --version ``` -### Personal Access Token +## Authentication (Cloud) + +Cloud commands require a PowerSync **personal access token (PAT)**. + +**Interactive login (recommended for local use):** + +```bash +powersync login +``` + +You can open a browser to [create a token in the PowerSync Dashboard](https://dashboard.powersync.com/account/access-tokens) or paste an existing token. The CLI stores the token in secure storage when available (e.g. macOS Keychain), or in a config file after confirmation. + +**CI and scripts:** Set the `TOKEN` environment variable. The CLI uses `TOKEN` when set; otherwise it uses the token from `powersync login`. + +```bash +export TOKEN=your-personal-access-token +powersync fetch instances --project-id= +``` + +To clear stored credentials: `powersync logout`. + +## Config-as-code + +The CLI uses a **config directory** (default `powersync/`) that holds: + +| File | Purpose | +|------|---------| +| `service.yaml` | Instance configuration: name, region, replication DB connection, client auth | +| `sync.yaml` | Sync Streams (or Sync Rules) configuration | +| `cli.yaml` | Link file (written by `powersync link`); ties this directory to an instance | + +All YAML files support the **`!env`** custom tag for secrets and environment-specific values, e.g. `uri: !env PS_DATABASE_URI`. Use `!env VAR::number` or `!env VAR::boolean` for typed substitution. For using one config directory across multiple instances (e.g. dev/staging/prod) via `!env` in `cli.yaml`, see the [CLI usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#configuring-multiple-instances-eg-dev-staging-production). + +Edit these files in your IDE, then run `powersync validate` and `powersync deploy`. + +## Cloud workflows + +### Create a new instance ```bash -npx powersync init +# Step 1: Log in and scaffold the config directory +powersync login +powersync init cloud + +# Step 2: Edit powersync/service.yaml (name, region, replication, auth) and sync config in sync.yaml; use !env for secrets -? Enter your API token: [hidden] +# Step 3: Create a new Cloud instance from your config and save its ID to cli.yaml +powersync link cloud --create --project-id= +# If your token has multiple orgs: add --org-id= + +# Step 4: Validate your config and deploy it to the new Cloud instance +powersync validate +powersync deploy ``` -You need to provide an access (API) token to initialize the CLI. These can be created in your [Account Settings](https://dashboard.powersync.com/account/access-tokens) in the PowerSync Dashboard. +Use `--directory=` for a different config folder (e.g. `--directory=powersync-prod`). + +### Use an existing instance (pull config) + +For an instance that already exists (e.g. created in the Dashboard), pull its config into a local directory: -Here you can also revoke access by deleting the token. +```bash +powersync login +powersync pull instance --project-id= --instance-id= +# Edit powersync/service.yaml and powersync/sync.yaml as needed +powersync validate +powersync deploy +``` -### Usage +This creates the config directory, writes `cli.yaml`, and downloads `service.yaml` and `sync.yaml`. Run `powersync pull instance` again (without IDs if already linked) to refresh local config from the cloud. + +### Run commands without local config + +You can run commands (e.g. `powersync generate schema`, `powersync generate token`, `powersync fetch status`) against an instance whose config is managed elsewhere (e.g. the Dashboard). Either link once with `powersync link cloud --instance-id= --project-id=`, or pass `--instance-id` and `--project-id` (and `--org-id` when your token has multiple orgs) on each command. You can also set `INSTANCE_ID`, `PROJECT_ID`, and optionally `ORG_ID` in the environment. For how the CLI resolves context (flags vs environment variables vs `cli.yaml`), and for multiple instances (e.g. dev/staging/prod with separate directories or `!env`), see the [CLI usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#supplying-linking-information-for-cloud-and-self-hosted-commands) in the PowerSync CLI repository. + +## Self-hosted workflows + +Run **`powersync init self-hosted`** to scaffold a config directory. Edit `service.yaml` with your instance details and use **`powersync link self-hosted --api-url `** to link to an existing running PowerSync Service. The CLI does not create or deploy to self-hosted instances; you manage the server and its config yourself. + +Supported self-hosted commands include: `powersync fetch status`, `powersync generate schema`, `powersync generate token`, `powersync validate`. Cloud-only commands (`powersync deploy`, `powersync pull instance`, `powersync fetch instances`, etc.) do not apply. + +### Docker plugin (local development) + +For local self-hosted development, use the Docker plugin: + +```bash +powersync init self-hosted +powersync docker configure +powersync docker start +``` + +Use **`powersync docker reset`** when you need a clean state (stop and remove, then start). For the full workflow, flags (`--database`, `--storage`, `--remove`, `--remove-volumes`), and how the Docker plugin uses templates and init scripts, see the [Docker plugin usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) in the PowerSync CLI repository. You can also run `powersync docker --help` for command options. + +## Common commands + +| Command | Description | +|---------|-------------| +| `powersync login` | Store PAT for Cloud (interactive or paste token) | +| `powersync logout` | Remove stored token | +| `powersync init cloud` | Scaffold Cloud config directory | +| `powersync init self-hosted` | Scaffold self-hosted config directory | +| `powersync link cloud --project-id=` | Link to an existing Cloud instance | +| `powersync link cloud --create --project-id=` | Create a new Cloud instance and link | +| `powersync pull instance --project-id= --instance-id=` | Download Cloud config into local files | +| `powersync deploy` | Deploy local config to linked Cloud instance | +| `powersync deploy sync-config` | Deploy only sync config | +| `powersync validate` | Validate config and sync rules/streams | +| `powersync fetch instances` | List Cloud instances (optionally by project/org) | +| `powersync fetch config` | Print linked Cloud instance config (YAML/JSON) | +| `powersync fetch status` | Instance diagnostics (connections, replication) | +| `powersync generate schema --output=ts --output-path=schema.ts` | Generate client-side schema | +| `powersync generate token --subject=user-123` | Generate a development JWT | + +For full usage and flags, run `powersync --help` or `powersync --help`. A complete [command reference](https://github.com/powersync-ja/powersync-cli/blob/main/cli/README.md#commands) is available in the PowerSync CLI repository; see also the [powersync npm package](https://www.npmjs.com/package/powersync). + +## Deploying from CI (e.g. GitHub Actions) + +You can automate sync config (and full config) deployments using the CLI in CI. Use the config directory as the source of truth: keep `service.yaml` and `sync.yaml` in the repo (with secrets via `!env` and CI secrets), then run `powersync deploy` (or `powersync deploy sync-config`). + +**Secrets:** Set `TOKEN` to your PowerSync personal access token. If the workflow does not use a linked directory, also set `INSTANCE_ID` and `PROJECT_ID` (and `ORG_ID` only if your token has multiple organizations). + + + Example: deploy sync config on push to main + + +The demo shows how to configure repository secrets and run the CLI in a workflow. With the new CLI, you typically use a `powersync/` directory in the repo and run `powersync deploy` or `powersync deploy sync-config` with `TOKEN` (and optionally `INSTANCE_ID`, `PROJECT_ID`, `ORG_ID`) set in the environment. + +## Migrating from the previous CLI + +If you used the older PowerSync CLI (e.g. `npx powersync init` to set token and org/project, then `powersync instance set`, `powersync instance deploy`, etc.), the new CLI uses a different flow. Upgrade to the latest **powersync** npm version and follow the mapping below. + +| Previous CLI | New CLI | +|--------------|---------| +| `npx powersync init` (enter token, org, project) | **`powersync login`** (token only). Then **`powersync init cloud`** to scaffold config, or **`powersync pull instance --project-id=... --instance-id=...`** to pull an existing instance. | +| `powersync instance set --instanceId=` | **`powersync link cloud --instance-id= --project-id=`** (writes `cli.yaml` in config directory). Or use `--directory` for a specific folder. | +| `powersync instance deploy` (interactive or long flag list) | Edit **`powersync/service.yaml`** and **`powersync/sync.yaml`**, then **`powersync deploy`**. Config is in files, not command args. | +| `powersync instance config` | **`powersync fetch config`** (output as YAML or JSON with `--output`). | +| Deploy only sync rules | **`powersync deploy sync-config`**. | +| `powersync instance schema` | **`powersync generate schema --output=... --output-path=...`** (and/or **`powersync fetch status`** for diagnostics). | +| Org/project stored by init | Pass **`--org-id`** and **`--project-id`** when needed, or use **`powersync link cloud`** so they are stored in **`powersync/cli.yaml`**. For CI, use env vars: **`TOKEN`**, **`INSTANCE_ID`**, **`PROJECT_ID`**, **`ORG_ID`** (optional). | + +**Summary:** Authenticate with **`powersync login`** (or `TOKEN` in CI). Use a **config directory** with `service.yaml` and `sync.yaml` as the source of truth. **Link** with **`powersync link cloud`** or **`powersync pull instance`**, then run **`powersync deploy`** or **`powersync deploy sync-config`**. No more setting “current instance” separately from config—the directory and `cli.yaml` define the target. + +## More documentation (CLI repository) + +Additional and advanced topics are documented in the PowerSync CLI repository: + +| 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`). | +| [Docker plugin](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. | +| [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). | + +## Known limitations + +* Certificates cannot be managed from the CLI. +* When secure storage is unavailable, `powersync login` may store the token in a plaintext config file only after explicit confirmation; prefer `TOKEN` in CI. +* Self-hosted: the CLI does not create instances or deploy config to your server; it only links to an existing API and runs a subset of commands (fetch status, generate schema/token, validate). The Docker plugin supports local development only. + +## Reference -For more information on the CLI's available commands, please refer to: -npm + Package and version history -### Deploying Sync Rules with GitHub Actions - -You can automate sync rule deployments using the PowerSync CLI in your CI/CD pipeline. This is useful for ensuring your sync rules are automatically deployed whenever changes are pushed to a repository. + + Create or revoke tokens in the PowerSync Dashboard + -See a complete example of deploying sync rules with GitHub Actions + CLI repository: usage docs, Docker plugin, examples - -The example repository demonstrates how to: -* Set up a GitHub Actions workflow to deploy sync rules on push to the `main` branch -* Configure required repository secrets (`POWERSYNC_AUTH_TOKEN`, `POWERSYNC_INSTANCE_ID`, `POWERSYNC_PROJECT_ID`, `POWERSYNC_ORG_ID`) -* Automatically deploy `sync-rules.yaml` changes - -### Known issues and limitations - -* Certificates cannot currently be managed from the CLI. -* The PowerSync CLI is not yet compatible with managing self-hosted PowerSync instances (PowerSync Open Edition and PowerSync Enterprise Self-Hosted Edition). This is on our roadmap. diff --git a/tools/overview.mdx b/tools/overview.mdx index ef6aae05..c54334df 100644 --- a/tools/overview.mdx +++ b/tools/overview.mdx @@ -8,8 +8,8 @@ sidebarTitle: Overview Dashboard for PowerSync Cloud. Allows managing your PowerSync organization, projects and instances. - - Manage your PowerSync Cloud instances from the command line. + + Manage PowerSync Cloud and self-hosted instances from the command line. Web app to inspect and debug syncing. Works with both cloud and self-hosted PowerSync Service instances. From 21f463f650f2b10a46440bb33f56e14e488c4e50 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Mon, 23 Feb 2026 17:11:00 +0200 Subject: [PATCH 02/20] Incorporate the CLI into steup instructions --- intro/setup-guide.mdx | 222 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 202 insertions(+), 20 deletions(-) diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index b7d85105..2caa8e97 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -177,16 +177,44 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel + **Dashboard** + + If you haven't yet, sign up for a free PowerSync Cloud account [here](https://accounts.journeyapps.com/portal/powersync-signup?s=docs). + + After signing up, you will be taken to the [PowerSync Dashboard](https://dashboard.powersync.com/). + + Here, create a new project. _Development_ and _Production_ instances of the PowerSync Service will be created by default in the project. + + --- + + **CLI** + If you haven't yet, sign up for a free PowerSync Cloud account [here](https://accounts.journeyapps.com/portal/powersync-signup?s=docs). - After signing up, you will be taken to the [PowerSync Dashboard](https://dashboard.powersync.com/). - - Here, create a new project. _Development_ and _Production_ instances of the PowerSync Service will be created by default in the project. + Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), then log in and scaffold the config directory: + + ```bash + npm install -g powersync + powersync login + powersync init cloud + ``` + + This creates a `powersync/` directory with `service.yaml` (instance name, region, connection, auth) and `sync.yaml` (sync config). Edit `powersync/service.yaml` to set your instance name and region — you'll configure the database connection in the next step. + + Then create the Cloud instance: + + ```bash + powersync link cloud --create --project-id= + ``` + + Find your project ID in the [PowerSync Dashboard](https://dashboard.powersync.com) URL, or run `powersync fetch instances` after logging in. - Self-hosted PowerSync runs via Docker. - + **Manual Docker setup** + + Self-hosted PowerSync runs via Docker. + Below is a minimal example of setting up the PowerSync Service with Postgres as the bucket storage database and example Sync Rules. MongoDB is also supported as a bucket storage database (docs are linked at the end of this step), and you will learn more about Sync Rules in a next step. ```bash @@ -230,8 +258,8 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel uri: postgresql://powersync_role:myhighlyrandompassword@powersync-postgres:5432/postgres sslmode: disable # Only for local/private networks - # Connection settings for bucket storage (Postgres and MongoDB are supported) - storage: + # Connection settings for bucket storage (Postgres and MongoDB are supported) + storage: type: postgresql uri: postgresql://powersync_storage_user:my_secure_user_password@powersync-postgres-storage:5432/powersync_storage sslmode: disable # Use 'disable' only for local/private networks @@ -247,17 +275,33 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel ``` - **Note**: This example assumes you've configured your source database with the required user and publication (see the previous step) - and are running it via Docker in the 'powersync-network' network. - + **Note**: This example assumes you've configured your source database with the required user and publication (see the previous step) + and are running it via Docker in the 'powersync-network' network. + If you are not using Docker, you will need to specify the connection details in the `config.yaml` file manually (see next step for more details). + --- + + **Docker plugin (CLI)** + + The [PowerSync CLI](/tools/cli) includes a Docker plugin that handles the Docker setup for you. Install the CLI (requires Node.js/npm), then scaffold the config directory and start the service: + + ```bash + npm install -g powersync + powersync init self-hosted + powersync docker configure --database postgres --storage postgres + powersync docker start + ``` + + The Docker plugin sets up Postgres for both the source database and bucket storage, creates the Docker Compose configuration, and starts the PowerSync Service. Run `powersync fetch status` to verify it's running. + **Learn More** * [Self-Hosting Introduction](/intro/self-hosting) * [Self-Host Demo App](https://github.com/powersync-ja/self-host-demo) for complete working examples. * [Self-Hosted Service Configuration](/configuration/powersync-service/self-hosted-instances) for more details on the config file structure. + * [CLI documentation](/tools/cli) for Docker plugin usage and all available commands. @@ -268,6 +312,8 @@ The next step is to connect your PowerSync Service instance to your source datab + **Dashboard** + In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance, then go to **Database Connections**: 1. Click **Connect to Source Database** @@ -287,13 +333,67 @@ The next step is to connect your PowerSync Service instance to your source datab **Learn More** - + + For more details on database connections, including provider-specific connection details (Supabase, AWS RDS, MongoDB Atlas, etc.), see [Source Database Connection](/configuration/source-db/connection). + + + --- + + **CLI** + + Edit `powersync/service.yaml` (created in the previous step) with your connection details. Use `!env` for secrets: + + + **Note**: Use the username (e.g., `powersync_role`) and password you created in Step 1: Configure your Source Database. + + + + ```yaml Postgres + replication: + connections: + - type: postgresql + uri: postgresql://powersync_role:myhighlyrandompassword@host:5432/postgres + sslmode: disable # 'verify-full' (default) or 'verify-ca' or 'disable' + # Note: 'disable' is only suitable for local/private networks + ``` + + ```yaml MongoDB + replication: + connections: + - type: mongodb + uri: mongodb+srv://user:password@cluster.mongodb.net/database + post_images: auto_configure + ``` + + ```yaml MySQL + replication: + connections: + - type: mysql + uri: mysql://repl_user:password@host:3306/database + ``` + + ```yaml SQL Server + replication: + connections: + - type: mssql + uri: mssql://user:password@host:1433/database + schema: dbo + ``` + + + You will run `powersync deploy` in a later step to deploy your config to the PowerSync Cloud instance. + + + **Learn More** + For more details on database connections, including provider-specific connection details (Supabase, AWS RDS, MongoDB Atlas, etc.), see [Source Database Connection](/configuration/source-db/connection). - For self-hosted setups, configure the source database connection in your `config.yaml` file (as you did in the previous step). Examples for the different database types are below. + **Manual Docker setup** + + Configure the source database connection in your `config.yaml` file (as you did in the previous step). Examples for the different database types are below. **Note**: Use the username (e.g., `powersync_role`) and password you created in Step 1: Configure your Source Database. @@ -302,9 +402,9 @@ The next step is to connect your PowerSync Service instance to your source datab ```yaml Postgres replication: - connections: - - type: postgresql # or mongodb, mysql, mssql - uri: postgresql://powersync_role:myhighlyrandompassword@powersync-postgres:5432/postgres # The connection URI or individual parameters can be specified. + connections: + - type: postgresql + uri: postgresql://powersync_role:myhighlyrandompassword@powersync-postgres:5432/postgres sslmode: disable # 'verify-full' (default) or 'verify-ca' or 'disable' # Note: 'disable' is only suitable for local/private networks, not for public networks ``` @@ -339,9 +439,21 @@ The next step is to connect your PowerSync Service instance to your source datab **Learn More** - + See the [self-host-demo app](https://github.com/powersync-ja/self-host-demo) for complete working examples of the different database types. + + --- + + **Docker plugin (CLI)** + + If you set up your instance using the Docker plugin in the previous step, `powersync docker configure` already merged connection config into `powersync/service.yaml`. Update the values with your actual credentials, then apply the changes: + + ```bash + powersync docker reset + ``` + + If you're connecting to an external database (not the Docker-managed Postgres), update the `replication.connections` section in `powersync/service.yaml` with your connection URI — same format as the examples above. @@ -394,16 +506,33 @@ We recommend starting with a simple **global bucket** that syncs data to all use + **Dashboard** + In the [PowerSync Dashboard](https://dashboard.powersync.com/): 1. Select your project and instance 2. Go to the **Sync Rules** view 3. Edit the YAML directly in the dashboard 4. Click **Deploy** to validate and deploy your Sync Rules + + --- + + **CLI** + + Edit `powersync/sync.yaml` with your sync config, then validate and deploy to the linked Cloud instance: + + ```bash + powersync validate + powersync deploy + ``` + + This deploys your full config (connection, auth, and sync config). For subsequent sync-only changes, use `powersync deploy sync-config` instead. - Add to your `config.yaml`: + **Manual Docker setup** + + Add the sync rules to your `config.yaml`: ```yaml sync_rules: @@ -414,6 +543,16 @@ We recommend starting with a simple **global bucket** that syncs data to all use - SELECT * FROM todos - SELECT * FROM lists WHERE archived = false ``` + + --- + + **Docker plugin (CLI)** + + Edit `powersync/sync.yaml` with your sync config, then apply the changes by resetting the stack: + + ```bash + powersync docker reset + ``` @@ -438,6 +577,8 @@ You'll use this token for two purposes: + **Dashboard** + 1. In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance 2. Go to the **Client Auth** view 3. Check the **Development tokens** setting and save your changes @@ -448,16 +589,57 @@ You'll use this token for two purposes: Development tokens expire after 12 hours. + + --- + + **CLI** + + Generate a development token with: + + ```bash + powersync generate token --subject=test-user + ``` + + Replace `test-user` with a user ID of your choice (this would normally be the user ID you want to test with). + + Requires `allow_temporary_tokens` to be enabled on the instance. Add it to `powersync/service.yaml` if you haven't already, then redeploy: + + ```yaml + client_auth: + allow_temporary_tokens: true + ``` + + ```bash + powersync deploy + ``` + + + Development tokens expire after 12 hours. + - For self-hosted setups, you can generate development tokens using the [powersync-service test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client): + **Manual Docker setup** - + For self-hosted setups, you can generate development tokens using the [powersync-service test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client): - + --- + + **Docker plugin (CLI)** + + Generate a development token with: + + ```bash + powersync generate token --subject=test-user + ``` + + Replace `test-user` with a user ID of your choice. The CLI signs the token using the shared secret from your instance config. + + + Development tokens expire after 12 hours. + From 1ee79fe721e5ad95457f457a50381ec7d8de49a0 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Mon, 23 Feb 2026 17:59:03 +0200 Subject: [PATCH 03/20] List CLI+docker plugin steps for self-hosted first --- intro/setup-guide.mdx | 90 +++++++++++++++++++++---------------------- 1 file changed, 45 insertions(+), 45 deletions(-) diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index 2caa8e97..75dd3206 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -211,6 +211,21 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel + **Docker plugin (CLI)** + + The [PowerSync CLI](/tools/cli) includes a Docker plugin that handles the Docker setup for you. Install the CLI (requires Node.js/npm), then scaffold the config directory and start the service: + + ```bash + npm install -g powersync + powersync init self-hosted + powersync docker configure --database postgres --storage postgres + powersync docker start + ``` + + The Docker plugin sets up Postgres for both the source database and bucket storage, creates the Docker Compose configuration, and starts the PowerSync Service. Run `powersync fetch status` to verify it's running. + + --- + **Manual Docker setup** Self-hosted PowerSync runs via Docker. @@ -281,21 +296,6 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel If you are not using Docker, you will need to specify the connection details in the `config.yaml` file manually (see next step for more details). - --- - - **Docker plugin (CLI)** - - The [PowerSync CLI](/tools/cli) includes a Docker plugin that handles the Docker setup for you. Install the CLI (requires Node.js/npm), then scaffold the config directory and start the service: - - ```bash - npm install -g powersync - powersync init self-hosted - powersync docker configure --database postgres --storage postgres - powersync docker start - ``` - - The Docker plugin sets up Postgres for both the source database and bucket storage, creates the Docker Compose configuration, and starts the PowerSync Service. Run `powersync fetch status` to verify it's running. - **Learn More** * [Self-Hosting Introduction](/intro/self-hosting) @@ -391,6 +391,18 @@ The next step is to connect your PowerSync Service instance to your source datab + **Docker plugin (CLI)** + + If you set up your instance using the Docker plugin in the previous step, `powersync docker configure` already merged connection config into `powersync/service.yaml`. Update the values with your actual credentials, then apply the changes: + + ```bash + powersync docker reset + ``` + + If you're connecting to an external database (not the Docker-managed Postgres), update the `replication.connections` section in `powersync/service.yaml` with your connection URI — same format as the examples below. + + --- + **Manual Docker setup** Configure the source database connection in your `config.yaml` file (as you did in the previous step). Examples for the different database types are below. @@ -442,18 +454,6 @@ The next step is to connect your PowerSync Service instance to your source datab See the [self-host-demo app](https://github.com/powersync-ja/self-host-demo) for complete working examples of the different database types. - - --- - - **Docker plugin (CLI)** - - If you set up your instance using the Docker plugin in the previous step, `powersync docker configure` already merged connection config into `powersync/service.yaml`. Update the values with your actual credentials, then apply the changes: - - ```bash - powersync docker reset - ``` - - If you're connecting to an external database (not the Docker-managed Postgres), update the `replication.connections` section in `powersync/service.yaml` with your connection URI — same format as the examples above. @@ -530,6 +530,16 @@ We recommend starting with a simple **global bucket** that syncs data to all use + **Docker plugin (CLI)** + + Edit `powersync/sync.yaml` with your sync config, then apply the changes by resetting the stack: + + ```bash + powersync docker reset + ``` + + --- + **Manual Docker setup** Add the sync rules to your `config.yaml`: @@ -543,16 +553,6 @@ We recommend starting with a simple **global bucket** that syncs data to all use - SELECT * FROM todos - SELECT * FROM lists WHERE archived = false ``` - - --- - - **Docker plugin (CLI)** - - Edit `powersync/sync.yaml` with your sync config, then apply the changes by resetting the stack: - - ```bash - powersync docker reset - ``` @@ -619,14 +619,6 @@ You'll use this token for two purposes: - **Manual Docker setup** - - For self-hosted setups, you can generate development tokens using the [powersync-service test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client): - - - - --- - **Docker plugin (CLI)** Generate a development token with: @@ -640,6 +632,14 @@ You'll use this token for two purposes: Development tokens expire after 12 hours. + + --- + + **Manual Docker setup** + + For self-hosted setups, you can generate development tokens using the [powersync-service test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client): + + From 9f3ddd8f7bb76030e48ca44648fefb293de229dd Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Mon, 23 Feb 2026 19:05:32 +0200 Subject: [PATCH 04/20] polish --- intro/setup-guide.mdx | 69 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 60 insertions(+), 9 deletions(-) diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index 75dd3206..11132b79 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -213,16 +213,35 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel **Docker plugin (CLI)** - The [PowerSync CLI](/tools/cli) includes a Docker plugin that handles the Docker setup for you. Install the CLI (requires Node.js/npm), then scaffold the config directory and start the service: + The [PowerSync CLI](/tools/cli) includes a Docker plugin that handles the Docker setup for you. Install the CLI (requires Node.js/npm), scaffold the config directory, and generate the Docker Compose setup: ```bash npm install -g powersync powersync init self-hosted powersync docker configure --database postgres --storage postgres + ``` + + The plugin sets up Postgres for both the source database and bucket storage and creates `powersync/docker/docker-compose.yaml`. Other databases are supported as well, you will learn more about this in the next step. Before starting, replace `powersync/sync.yaml` with this minimal sync config: + + ```yaml + streams: + lists: + # Streams without parameters sync the same data to all users + auto_subscribe: true + query: + # Sync all rows + - SELECT * FROM todos + ``` + + You'll update this with your actual tables/collections in a later step. + + Then start the PowerSync Service: + + ```bash powersync docker start ``` - The Docker plugin sets up Postgres for both the source database and bucket storage, creates the Docker Compose configuration, and starts the PowerSync Service. Run `powersync fetch status` to verify it's running. + Run `powersync fetch status` to verify it's running. --- @@ -300,8 +319,8 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel **Learn More** * [Self-Hosting Introduction](/intro/self-hosting) * [Self-Host Demo App](https://github.com/powersync-ja/self-host-demo) for complete working examples. + * [CLI documentation](/tools/cli). * [Self-Hosted Service Configuration](/configuration/powersync-service/self-hosted-instances) for more details on the config file structure. - * [CLI documentation](/tools/cli) for Docker plugin usage and all available commands. @@ -393,13 +412,15 @@ The next step is to connect your PowerSync Service instance to your source datab **Docker plugin (CLI)** - If you set up your instance using the Docker plugin in the previous step, `powersync docker configure` already merged connection config into `powersync/service.yaml`. Update the values with your actual credentials, then apply the changes: + If you used the Docker plugin in the previous step, the source database connection is already configured. `service.yaml` reads the connection URI from `!env PS_DATA_SOURCE_URI`. The Docker-managed Postgres (`pg-db`) was also pre-configured with `wal_level=logical` and a `powersync` publication by the init scripts. + + If you want to use an **external database** instead, update `PS_DATA_SOURCE_URI` in `powersync/docker/.env` with your connection details, then restart: ```bash powersync docker reset ``` - If you're connecting to an external database (not the Docker-managed Postgres), update the `replication.connections` section in `powersync/service.yaml` with your connection URI — same format as the examples below. + You'll also need to complete the source database setup from Step 1 (replication user, publication) on your external database before this will work. --- @@ -532,9 +553,10 @@ We recommend starting with a simple **global bucket** that syncs data to all use **Docker plugin (CLI)** - Edit `powersync/sync.yaml` with your sync config, then apply the changes by resetting the stack: + Edit `powersync/sync.yaml` with your sync config. The default file has a placeholder (`SELECT * FROM todos`) — replace it with your actual table/collection names. Then apply the changes: ```bash + powersync validate powersync docker reset ``` @@ -542,7 +564,7 @@ We recommend starting with a simple **global bucket** that syncs data to all use **Manual Docker setup** - Add the sync rules to your `config.yaml`: + Add the sync rules to your `config.yaml`, for example: ```yaml sync_rules: @@ -621,13 +643,42 @@ You'll use this token for two purposes: **Docker plugin (CLI)** - Generate a development token with: + `powersync generate token` signs a JWT using the client auth key from `service.yaml`. The default template doesn't include one, so add an HMAC key first. + + Generate a random secret (base64url-encoded): ```bash + openssl rand -base64 32 | tr '+/' '-_' | tr -d '=' + ``` + + Add the secret to `powersync/docker/.env`: + + ```bash + PS_CLIENT_AUTH_KEY= + ``` + + Add the key to `powersync/service.yaml`: + + ```yaml + client_auth: + jwks: + keys: + - kty: oct + alg: HS256 + kid: dev-key + k: !env PS_CLIENT_AUTH_KEY + ``` + + Apply the changes and generate the token: + + ```bash + powersync docker reset powersync generate token --subject=test-user ``` - Replace `test-user` with a user ID of your choice. The CLI signs the token using the shared secret from your instance config. + Replace test-user with the user ID you want to authenticate: + - If you’re using global Sync Rules, you can use any value (e.g., test-user) since all data syncs to all users + - If you’re using user-specific Sync Rules, use a user ID that matches a user in your database (this will be used as request.user_id() in your Sync Rules) Development tokens expire after 12 hours. From 3a7782a79e691ec1b196c6a053ddf780c2877eb9 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Mon, 23 Feb 2026 20:22:33 +0200 Subject: [PATCH 05/20] Fix example --- intro/setup-guide.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index 11132b79..1c44185e 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -224,13 +224,14 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel The plugin sets up Postgres for both the source database and bucket storage and creates `powersync/docker/docker-compose.yaml`. Other databases are supported as well, you will learn more about this in the next step. Before starting, replace `powersync/sync.yaml` with this minimal sync config: ```yaml + config: + edition: 2 + streams: - lists: + todos: # Streams without parameters sync the same data to all users auto_subscribe: true - query: - # Sync all rows - - SELECT * FROM todos + query: "SELECT * FROM todos" ``` You'll update this with your actual tables/collections in a later step. From 23ccd1edc4b097f675d9f4ad4f9ff0aa93726eed Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Tue, 24 Feb 2026 13:02:47 +0200 Subject: [PATCH 06/20] Simpler dev token instructions --- intro/setup-guide.mdx | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index 1c44185e..e8f6100f 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -652,22 +652,19 @@ You'll use this token for two purposes: openssl rand -base64 32 | tr '+/' '-_' | tr -d '=' ``` - Add the secret to `powersync/docker/.env`: - ```bash - PS_CLIENT_AUTH_KEY= - ``` - - Add the key to `powersync/service.yaml`: + Add the secret to `powersync/service.yaml`: ```yaml client_auth: + audience: ['http://localhost:8080', 'http://127.0.0.1:8080'] + # static collection of public keys for JWT verification jwks: keys: - kty: oct - alg: HS256 - kid: dev-key - k: !env PS_CLIENT_AUTH_KEY + alg: 'HS256' + k: '[base64url-encoded-shared-secret]' + kid: 'dev-key-1' ``` Apply the changes and generate the token: From 4eb359d15968a66726426c5bfff6efe6dbdfa0a3 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 25 Feb 2026 13:10:30 +0200 Subject: [PATCH 07/20] Rename to sync-config.yaml --- intro/setup-guide.mdx | 20 ++++++++++---------- tools/cli.mdx | 38 +++++++++++++++++++------------------- 2 files changed, 29 insertions(+), 29 deletions(-) diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index e8f6100f..96b28d9f 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -199,7 +199,7 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel powersync init cloud ``` - This creates a `powersync/` directory with `service.yaml` (instance name, region, connection, auth) and `sync.yaml` (sync config). Edit `powersync/service.yaml` to set your instance name and region — you'll configure the database connection in the next step. + This creates a `powersync/` directory with `service.yaml` (instance name, region, connection, auth) and `sync-config.yaml` (sync config). Edit `powersync/service.yaml` to set your instance name and region — you'll configure the database connection in the next step. Then create the Cloud instance: @@ -211,9 +211,9 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel - **Docker plugin (CLI)** + **Docker (CLI)** - The [PowerSync CLI](/tools/cli) includes a Docker plugin that handles the Docker setup for you. Install the CLI (requires Node.js/npm), scaffold the config directory, and generate the Docker Compose setup: + The [PowerSync CLI](/tools/cli) can run PowerSync locally with Docker. Install the CLI (requires Node.js/npm), scaffold the config directory, and generate the Docker Compose setup: ```bash npm install -g powersync @@ -221,7 +221,7 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel powersync docker configure --database postgres --storage postgres ``` - The plugin sets up Postgres for both the source database and bucket storage and creates `powersync/docker/docker-compose.yaml`. Other databases are supported as well, you will learn more about this in the next step. Before starting, replace `powersync/sync.yaml` with this minimal sync config: + Docker sets up Postgres for both the source database and bucket storage and creates `powersync/docker/docker-compose.yaml`. Other databases are supported as well, you will learn more about this in the next step. Before starting, replace `powersync/sync-config.yaml` with this minimal sync config: ```yaml config: @@ -411,9 +411,9 @@ The next step is to connect your PowerSync Service instance to your source datab - **Docker plugin (CLI)** + **Docker (CLI)** - If you used the Docker plugin in the previous step, the source database connection is already configured. `service.yaml` reads the connection URI from `!env PS_DATA_SOURCE_URI`. The Docker-managed Postgres (`pg-db`) was also pre-configured with `wal_level=logical` and a `powersync` publication by the init scripts. + If you used Docker in the previous step, the source database connection is already configured. `service.yaml` reads the connection URI from `!env PS_DATA_SOURCE_URI`. The Docker-managed Postgres (`pg-db`) was also pre-configured with `wal_level=logical` and a `powersync` publication by the init scripts. If you want to use an **external database** instead, update `PS_DATA_SOURCE_URI` in `powersync/docker/.env` with your connection details, then restart: @@ -541,7 +541,7 @@ We recommend starting with a simple **global bucket** that syncs data to all use **CLI** - Edit `powersync/sync.yaml` with your sync config, then validate and deploy to the linked Cloud instance: + Edit `powersync/sync-config.yaml` with your sync config, then validate and deploy to the linked Cloud instance: ```bash powersync validate @@ -552,9 +552,9 @@ We recommend starting with a simple **global bucket** that syncs data to all use - **Docker plugin (CLI)** + **Docker (CLI)** - Edit `powersync/sync.yaml` with your sync config. The default file has a placeholder (`SELECT * FROM todos`) — replace it with your actual table/collection names. Then apply the changes: + Edit `powersync/sync-config.yaml` with your sync config. The default file has a placeholder (`SELECT * FROM todos`) — replace it with your actual table/collection names. Then apply the changes: ```bash powersync validate @@ -642,7 +642,7 @@ You'll use this token for two purposes: - **Docker plugin (CLI)** + **Docker (CLI)** `powersync generate token` signs a JWT using the client auth key from `service.yaml`. The default template doesn't include one, so add an HMAC key first. diff --git a/tools/cli.mdx b/tools/cli.mdx index c49a999b..f58683e8 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -5,17 +5,17 @@ description: "Manage PowerSync Cloud and self-hosted instances from the command The PowerSync CLI lets you manage PowerSync Service instances, deploy sync config (your Sync Streams or Sync Rules), generate client schemas, and run diagnostics. It is distributed as the [powersync](https://www.npmjs.com/package/powersync) npm package. -**Cloud:** Full support for PowerSync Cloud. Log in with a personal access token, then define your instance config in a `powersync/` directory (`service.yaml`, `sync.yaml`) and deploy with `powersync deploy`. +**Cloud:** Full support for PowerSync Cloud. Log in with a personal access token, then define your instance config in a `powersync/` directory (`service.yaml`, `sync-config.yaml`) and deploy with `powersync deploy`. -**Self-hosted:** You can link to an existing PowerSync Service instance and run a subset of commands (e.g. `powersync fetch status`, `powersync generate schema`, `powersync validate`). A Docker plugin is available for local self-hosted development. +**Self-hosted:** You can link to an existing PowerSync Service instance and run a subset of commands (e.g. `powersync fetch status`, `powersync generate schema`, `powersync validate`). Docker is supported for local development. - + The PowerSync CLI was overhauled in **version TODO** (see the [powersync](https://www.npmjs.com/package/powersync) npm package for the current release). The redesign is based on this [public proposal](https://docs.google.com/document/d/1iqpJF2gog2jB-ZWeN8TBEjcad8aBKNKbue2yJ21q_-s/edit). - Main improvements in the new version: **self-hosted support** (link to your own PowerSync Service and run commands such as fetch status, generate schema, validate); **open source**; and **improved DX**, including validated config files (`service.yaml`, `sync.yaml`) used for creating and deploying changes to PowerSync instances instead of long command-line flags. + Main improvements in the new version: **self-hosted support** (link to your own PowerSync Service and run commands such as fetch status, generate schema, validate); **open source**; and **improved DX**, including validated config files (`service.yaml`, `sync-config.yaml`) used for creating and deploying changes to PowerSync instances instead of long command-line flags. See [Migrating from the previous CLI](#migrating-from-the-previous-cli) if you used the older flow. - + ## Installation @@ -57,7 +57,7 @@ The CLI uses a **config directory** (default `powersync/`) that holds: | File | Purpose | |------|---------| | `service.yaml` | Instance configuration: name, region, replication DB connection, client auth | -| `sync.yaml` | Sync Streams (or Sync Rules) configuration | +| `sync-config.yaml` | Sync Streams (or Sync Rules) configuration | | `cli.yaml` | Link file (written by `powersync link`); ties this directory to an instance | All YAML files support the **`!env`** custom tag for secrets and environment-specific values, e.g. `uri: !env PS_DATABASE_URI`. Use `!env VAR::number` or `!env VAR::boolean` for typed substitution. For using one config directory across multiple instances (e.g. dev/staging/prod) via `!env` in `cli.yaml`, see the [CLI usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#configuring-multiple-instances-eg-dev-staging-production). @@ -73,7 +73,7 @@ Edit these files in your IDE, then run `powersync validate` and `powersync deplo powersync login powersync init cloud -# Step 2: Edit powersync/service.yaml (name, region, replication, auth) and sync config in sync.yaml; use !env for secrets +# Step 2: Edit powersync/service.yaml (name, region, replication, auth) and sync config in sync-config.yaml; use !env for secrets # Step 3: Create a new Cloud instance from your config and save its ID to cli.yaml powersync link cloud --create --project-id= @@ -93,12 +93,12 @@ For an instance that already exists (e.g. created in the Dashboard), pull its co ```bash powersync login powersync pull instance --project-id= --instance-id= -# Edit powersync/service.yaml and powersync/sync.yaml as needed +# Edit powersync/service.yaml and powersync/sync-config.yaml as needed powersync validate powersync deploy ``` -This creates the config directory, writes `cli.yaml`, and downloads `service.yaml` and `sync.yaml`. Run `powersync pull instance` again (without IDs if already linked) to refresh local config from the cloud. +This creates the config directory, writes `cli.yaml`, and downloads `service.yaml` and `sync-config.yaml`. Run `powersync pull instance` again (without IDs if already linked) to refresh local config from the cloud. ### Run commands without local config @@ -110,9 +110,9 @@ Run **`powersync init self-hosted`** to scaffold a config directory. Edit `servi Supported self-hosted commands include: `powersync fetch status`, `powersync generate schema`, `powersync generate token`, `powersync validate`. Cloud-only commands (`powersync deploy`, `powersync pull instance`, `powersync fetch instances`, etc.) do not apply. -### Docker plugin (local development) +### Docker (local development) -For local self-hosted development, use the Docker plugin: +For local self-hosted development, use Docker: ```bash powersync init self-hosted @@ -120,7 +120,7 @@ powersync docker configure powersync docker start ``` -Use **`powersync docker reset`** when you need a clean state (stop and remove, then start). For the full workflow, flags (`--database`, `--storage`, `--remove`, `--remove-volumes`), and how the Docker plugin uses templates and init scripts, see the [Docker plugin usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) in the PowerSync CLI repository. You can also run `powersync docker --help` for command options. +Use **`powersync docker reset`** when you need a clean state (stop and remove, then start). For the full workflow, flags (`--database`, `--storage`, `--remove`, `--remove-volumes`), and how the Docker setup uses templates and init scripts, see the [Docker usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) in the PowerSync CLI repository. You can also run `powersync docker --help` for command options. ## Common commands @@ -146,7 +146,7 @@ For full usage and flags, run `powersync --help` or `powersync --help` ## Deploying from CI (e.g. GitHub Actions) -You can automate sync config (and full config) deployments using the CLI in CI. Use the config directory as the source of truth: keep `service.yaml` and `sync.yaml` in the repo (with secrets via `!env` and CI secrets), then run `powersync deploy` (or `powersync deploy sync-config`). +You can automate sync config (and full config) deployments using the CLI in CI. Use the config directory as the source of truth: keep `service.yaml` and `sync-config.yaml` in the repo (with secrets via `!env` and CI secrets), then run `powersync deploy` (or `powersync deploy sync-config`). **Secrets:** Set `TOKEN` to your PowerSync personal access token. If the workflow does not use a linked directory, also set `INSTANCE_ID` and `PROJECT_ID` (and `ORG_ID` only if your token has multiple organizations). @@ -169,13 +169,13 @@ If you used the older PowerSync CLI (e.g. `npx powersync init` to set token and |--------------|---------| | `npx powersync init` (enter token, org, project) | **`powersync login`** (token only). Then **`powersync init cloud`** to scaffold config, or **`powersync pull instance --project-id=... --instance-id=...`** to pull an existing instance. | | `powersync instance set --instanceId=` | **`powersync link cloud --instance-id= --project-id=`** (writes `cli.yaml` in config directory). Or use `--directory` for a specific folder. | -| `powersync instance deploy` (interactive or long flag list) | Edit **`powersync/service.yaml`** and **`powersync/sync.yaml`**, then **`powersync deploy`**. Config is in files, not command args. | +| `powersync instance deploy` (interactive or long flag list) | Edit **`powersync/service.yaml`** and **`powersync/sync-config.yaml`**, then **`powersync deploy`**. Config is in files, not command args. | | `powersync instance config` | **`powersync fetch config`** (output as YAML or JSON with `--output`). | | Deploy only sync rules | **`powersync deploy sync-config`**. | | `powersync instance schema` | **`powersync generate schema --output=... --output-path=...`** (and/or **`powersync fetch status`** for diagnostics). | | Org/project stored by init | Pass **`--org-id`** and **`--project-id`** when needed, or use **`powersync link cloud`** so they are stored in **`powersync/cli.yaml`**. For CI, use env vars: **`TOKEN`**, **`INSTANCE_ID`**, **`PROJECT_ID`**, **`ORG_ID`** (optional). | -**Summary:** Authenticate with **`powersync login`** (or `TOKEN` in CI). Use a **config directory** with `service.yaml` and `sync.yaml` as the source of truth. **Link** with **`powersync link cloud`** or **`powersync pull instance`**, then run **`powersync deploy`** or **`powersync deploy sync-config`**. No more setting “current instance” separately from config—the directory and `cli.yaml` define the target. +**Summary:** Authenticate with **`powersync login`** (or `TOKEN` in CI). Use a **config directory** with `service.yaml` and `sync-config.yaml` as the source of truth. **Link** with **`powersync link cloud`** or **`powersync pull instance`**, then run **`powersync deploy`** or **`powersync deploy sync-config`**. No more setting “current instance” separately from config—the directory and `cli.yaml` define the target. ## More documentation (CLI repository) @@ -185,14 +185,14 @@ Additional and advanced topics are documented in the PowerSync CLI repository: |----------|-------------| | [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`). | -| [Docker plugin](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. | +| [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. | | [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). | ## Known limitations * Certificates cannot be managed from the CLI. -* When secure storage is unavailable, `powersync login` may store the token in a plaintext config file only after explicit confirmation; prefer `TOKEN` in CI. -* Self-hosted: the CLI does not create instances or deploy config to your server; it only links to an existing API and runs a subset of commands (fetch status, generate schema/token, validate). The Docker plugin supports local development only. +* When secure storage is unavailable, `powersync login` may store the token in a plaintext config file after explicit confirmation; prefer `TOKEN` in CI. +* Self-hosted: the CLI does not create instances or deploy config to your server; it only links to an existing API and runs a subset of commands (fetch status, generate schema/token, validate). Docker supports local development only. ## Reference @@ -220,5 +220,5 @@ Additional and advanced topics are documented in the PowerSync CLI repository: href="https://github.com/powersync-ja/powersync-cli" horizontal > - CLI repository: usage docs, Docker plugin, examples + CLI repository: usage docs, Docker usage, examples From 76d1638fd531d2874ed9e287eb419c8ad948870d Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 25 Feb 2026 15:51:54 +0200 Subject: [PATCH 08/20] More updates for self-hosted workflows --- intro/self-hosting.mdx | 5 +- intro/setup-guide.mdx | 26 ++-- maintenance-ops/self-hosting/diagnostics.mdx | 13 ++ maintenance-ops/self-hosting/overview.mdx | 6 +- .../self-hosting/update-sync-rules.mdx | 50 +++++-- tools/local-development.mdx | 128 +++++++++--------- 6 files changed, 139 insertions(+), 89 deletions(-) diff --git a/intro/self-hosting.mdx b/intro/self-hosting.mdx index ec8e9fce..08637b53 100644 --- a/intro/self-hosting.mdx +++ b/intro/self-hosting.mdx @@ -9,7 +9,6 @@ The [PowerSync Service](https://github.com/powersync-ja/powersync-service) can b * Note that the [PowerSync Dashboard](https://dashboard.powersync.com/) is currently not available when self-hosting PowerSync. - * The PowerSync Open Edition is currently considered a beta release as it still requires more detailed documentation and guides. From a stability perspective, the Open Edition is production-ready. It uses the same codebase as our Cloud version. See [Feature Status](/resources/feature-status) for how we define beta releases. * Please reach out on our [Discord](https://discord.gg/powersync) if you have any questions not yet covered in these docs. @@ -27,9 +26,9 @@ The quickest way to get a feel for the system is to run our example project on y -## Local Development With Docker Compose +## Local Development -If you plan to self-host for development purposes only, see [Local Development](/tools/local-development) for how to easily do this using Docker Compose. +To run PowerSync locally, see [Local Development](/tools/local-development). The easiest path is the [PowerSync CLI](/tools/cli), which sets up a Docker Compose stack for you. ## Full Installation diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index 96b28d9f..e7155a22 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -211,9 +211,9 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel - **Docker (CLI)** + **CLI** - The [PowerSync CLI](/tools/cli) can run PowerSync locally with Docker. Install the CLI (requires Node.js/npm), scaffold the config directory, and generate the Docker Compose setup: + Recommended for getting started. For custom setups use the [Manual](#manual-docker-setup) path below. Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), scaffold the config directory, and generate the Docker Compose setup: ```bash npm install -g powersync @@ -246,11 +246,11 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel --- - **Manual Docker setup** + **Manual** - Self-hosted PowerSync runs via Docker. + Self-hosted PowerSync runs via Docker. The commands below illustrate the basic PowerSync Service requirements. - Below is a minimal example of setting up the PowerSync Service with Postgres as the bucket storage database and example Sync Rules. MongoDB is also supported as a bucket storage database (docs are linked at the end of this step), and you will learn more about Sync Rules in a next step. + Below is a minimal example using Postgres for bucket storage. MongoDB is also supported as bucket storage. The source database connection is configured in the next step — you can use the Docker-managed Postgres from Step 1 or point to an external database instead. ```bash # 1. Create a directory for your config @@ -316,6 +316,10 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel If you are not using Docker, you will need to specify the connection details in the `config.yaml` file manually (see next step for more details). + + The [PowerSync CLI](/tools/cli) works alongside any running instance — including one set up manually. Once your service is running, you can use `powersync fetch status`, `powersync validate`, `powersync generate schema`, and `powersync generate token` without having used the CLI to set it up. + + **Learn More** * [Self-Hosting Introduction](/intro/self-hosting) @@ -411,7 +415,7 @@ The next step is to connect your PowerSync Service instance to your source datab - **Docker (CLI)** + **CLI** If you used Docker in the previous step, the source database connection is already configured. `service.yaml` reads the connection URI from `!env PS_DATA_SOURCE_URI`. The Docker-managed Postgres (`pg-db`) was also pre-configured with `wal_level=logical` and a `powersync` publication by the init scripts. @@ -425,7 +429,7 @@ The next step is to connect your PowerSync Service instance to your source datab --- - **Manual Docker setup** + **Manual** Configure the source database connection in your `config.yaml` file (as you did in the previous step). Examples for the different database types are below. @@ -552,7 +556,7 @@ We recommend starting with a simple **global bucket** that syncs data to all use - **Docker (CLI)** + **CLI** Edit `powersync/sync-config.yaml` with your sync config. The default file has a placeholder (`SELECT * FROM todos`) — replace it with your actual table/collection names. Then apply the changes: @@ -563,7 +567,7 @@ We recommend starting with a simple **global bucket** that syncs data to all use --- - **Manual Docker setup** + **Manual** Add the sync rules to your `config.yaml`, for example: @@ -642,7 +646,7 @@ You'll use this token for two purposes: - **Docker (CLI)** + **CLI** `powersync generate token` signs a JWT using the client auth key from `service.yaml`. The default template doesn't include one, so add an HMAC key first. @@ -684,7 +688,7 @@ You'll use this token for two purposes: --- - **Manual Docker setup** + **Manual** For self-hosted setups, you can generate development tokens using the [powersync-service test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client): diff --git a/maintenance-ops/self-hosting/diagnostics.mdx b/maintenance-ops/self-hosting/diagnostics.mdx index 1184bbcc..cf37c509 100644 --- a/maintenance-ops/self-hosting/diagnostics.mdx +++ b/maintenance-ops/self-hosting/diagnostics.mdx @@ -9,6 +9,19 @@ This API provides the following diagnostic information: - Connections → Connected backend source database and any active errors associated with the connection. - Active Sync Rules → Currently deployed sync rules and the status of the sync rules. +## CLI + +If you have the [PowerSync CLI](/tools/cli) installed, use `powersync fetch status` to check instance status without calling the API directly. This works with any running PowerSync instance — local or remote. + +```bash +powersync fetch status + +# Extract a specific field +powersync fetch status --output=json | jq '.connections[0]' +``` + +## Diagnostics API + # Configuration 1. To enable the Diagnostics API, specify an API token in your PowerSync YAML file: diff --git a/maintenance-ops/self-hosting/overview.mdx b/maintenance-ops/self-hosting/overview.mdx index a45fd284..3b471b1d 100644 --- a/maintenance-ops/self-hosting/overview.mdx +++ b/maintenance-ops/self-hosting/overview.mdx @@ -6,6 +6,10 @@ sidebarTitle: Overview import SelfHostDeploymentPlatformsCards from '/snippets/self-host-deployment-platforms-cards.mdx'; + + The [PowerSync CLI](/tools/cli) provides commands that work alongside any running self-hosted instance: `powersync fetch status`, `powersync validate`, `powersync generate schema`, `powersync generate token`. You don't need to have set up the instance with the CLI to use these. + + ## Production Topics Details for production self-hosted PowerSync deployments, including architecture/setup recommendations, security, health checks, maintenance, and monitoring. @@ -13,7 +17,7 @@ Details for production self-hosted PowerSync deployments, including architecture - + diff --git a/maintenance-ops/self-hosting/update-sync-rules.mdx b/maintenance-ops/self-hosting/update-sync-rules.mdx index 4b62498a..1f4d4b41 100644 --- a/maintenance-ops/self-hosting/update-sync-rules.mdx +++ b/maintenance-ops/self-hosting/update-sync-rules.mdx @@ -1,23 +1,49 @@ --- -title: "Update Sync Rules" -description: "How to update sync rules in a self-hosted PowerSync deployment" +title: "Update Sync Streams (Sync Config)" +description: "How to update Sync Streams (or legacy Sync Rules) in a self-hosted PowerSync deployment" --- -There are two ways to update sync rules in a self-hosted deployment: +There are three ways to update your sync config in a self-hosted deployment: -1. **Config file** - Update your config and restart the service -2. **API endpoint** - Deploy at runtime without restarting +1. **CLI** — Edit your config and apply with `powersync docker reset` (recommended if using the CLI) +2. **Config file** — Update your config and restart the service +3. **API endpoint** — Deploy at runtime without restarting - During deployment, existing sync rules continue serving clients while new - rules process. Clients seamlessly transition once [initial + During deployment, existing Sync Streams/Sync Rules continue serving clients while new + sync config processes. Clients seamlessly transition once [initial replication](/architecture/powersync-service#initial-replication-vs-incremental-replication) completes. -## Option 1: Config File (Recommended) + + Run `powersync validate` in the CLIbefore deploying to catch errors in your sync config without applying changes. Works with any running PowerSync instance. + -Define sync rules in your `powersync.yaml` either inline or via a separate file. See [Self-Hosted Instance Configuration](/configuration/powersync-service/self-hosted-instances) for the full config reference and [Sync Rules](/sync/rules/overview) for syntax. +## Option 1: CLI + +If you set up PowerSync using the CLI (`powersync docker`), update your sync config and apply it without a full service restart: + + + + Update `powersync/sync-config.yaml` in your project directory. + + + ```bash + powersync validate + ``` + + + ```bash + powersync docker reset + ``` + This restarts the PowerSync Service and applies your updated sync config. + + + +## Option 2: Config File + +Define your sync config in `powersync.yaml` either inline or via a separate file. See [Self-Hosted Instance Configuration](/configuration/powersync-service/self-hosted-instances) for the full config reference. @@ -46,13 +72,13 @@ Define sync rules in your `powersync.yaml` either inline or via a separate file. docker compose restart powersync ``` - Once the service starts up, it will load the updated sync rules and begin processing them while continuing to serve existing rules until initial replication completes. + Once the service starts up, it will load the updated sync config and begin processing it while continuing to serve the existing config until initial replication completes. -## Option 2: Deploy via API +## Option 3: Deploy via API -Deploy sync rules at runtime without restarting. Useful for quick iterations during development. +Deploy sync config at runtime without restarting. Useful for quick iterations during development. The API is disabled when sync rules are defined in `powersync.yaml`. Config diff --git a/tools/local-development.mdx b/tools/local-development.mdx index 71baf68b..51c42f34 100644 --- a/tools/local-development.mdx +++ b/tools/local-development.mdx @@ -1,19 +1,28 @@ --- title: "Local Development" -description: "Using Docker Compose to self-host PowerSync for development purposes." +description: "Getting started with self-hosted PowerSync on your development machine." --- -It's possible to host the full PowerSync Service stack on your development machine using pure Docker, but Docker Compose can simplify things. +The easiest way to run PowerSync locally is with the [PowerSync CLI](/tools/cli), which scaffolds and manages a Docker Compose stack for you. -Below is a minimal Docker Compose setup for self-hosting PowerSync on your development machine. Note that Docker Compose is primarily designed for development and testing environments. +See the [Setup Guide](/intro/setup-guide) for step-by-step CLI instructions: `powersync init self-hosted` + `powersync docker configure` + `powersync docker start`. -1. Create a new folder to work in: +If you'd prefer to write your own Docker Compose setup, here's a minimal example. + +## Docker Compose Example + +Create a working directory with three files: -```bash -mkdir powersync-service && cd powersync-service ``` +powersync-service/ + docker-compose.yml + service.yaml + sync-config.yaml +``` + +### `docker-compose.yml` -1. Create a `docker-compose.yml` file with the below contents: +This example uses Postgres as the source database and MongoDB as bucket storage. Postgres is also supported as bucket storage — see [Self-Hosted Instance Configuration](/configuration/powersync-service/self-hosted-instances) for details. ```yaml services: @@ -22,17 +31,19 @@ services: depends_on: mongo-rs-init: condition: service_completed_successfully - postgres: # This is not required, but is nice to have + postgres: condition: service_healthy image: journeyapps/powersync-service:latest command: ["start", "-r", "unified"] volumes: - - ./config/config.yaml:/config/config.yaml + - ./service.yaml:/config/service.yaml + - ./sync-config.yaml:/config/sync-config.yaml environment: - POWERSYNC_CONFIG_PATH: /config/config.yaml + POWERSYNC_CONFIG_PATH: /config/service.yaml ports: - 8080:8080 + # Source database (Postgres with logical replication enabled) postgres: image: postgres:latest restart: always @@ -52,7 +63,7 @@ services: timeout: 5s retries: 5 - # MongoDB Service used internally + # MongoDB used internally for bucket storage mongo: image: mongo:7.0 command: --replSet rs0 --bind_ip_all --quiet @@ -61,7 +72,8 @@ services: - 27017:27017 volumes: - mongo_storage:/data/db - # Initializes the MongoDB replica set. This service will not usually be actively running + + # Initializes the MongoDB replica set. This service will not usually be actively running mongo-rs-init: image: mongo:7.0 depends_on: @@ -75,83 +87,75 @@ services: volumes: mongo_storage: pg_data: - ``` -1. Create a config volume that contains a `config.yaml` file, this configured the PowerSync Service itself +### `service.yaml` -```bash -mkdir config && cd config -``` - -Put the below into `/config/config.yaml` : +The main PowerSync Service configuration. See [Self-Hosted Instance Configuration](/configuration/powersync-service/self-hosted-instances) for the full reference. ```yaml +# Source database connection replication: connections: - type: postgresql uri: postgresql://postgres:postgres@postgres:5432/postgres + sslmode: disable # verify-full, verify-ca, or disable - # SSL settings - sslmode: disable # 'verify-full' (default) or 'verify-ca' or 'disable' - -# Connection settings for bucket storage +# Bucket storage (MongoDB shown; Postgres is also supported) storage: type: mongodb - uri: mongodb://mongo:27017/powersync_demo + uri: mongodb://mongo:27017/powersync_storage # The port which the PowerSync API server will listen on port: 8080 -# Specify sync rules -sync_rules: - # TODO use specific sync rules here - content: | - bucket_definitions: - global: - data: - - SELECT * FROM lists - - SELECT * FROM todos +# Points to the sync config file +sync_config: + path: sync-config.yaml # Settings for client authentication client_auth: # Enable this if using Supabase Auth supabase: false - - # JWKS URIs can be specified here. - jwks_uri: [TODO] + # Or enter a static collection of public keys for JWT verification, and generate a development token using the CLI (`powersync generate token`) + # jwks: + # keys: + # - kty: 'RSA' + # n: '[rsa-modulus]' + # e: '[rsa-exponent]' + # alg: 'RS256' + # kid: '[key-id]' # JWKS audience - audience: ['powersync-dev', 'powersync'] - - # Settings for telemetry reporting - # See https://docs.powersync.com/self-hosting/telemetry - telemetry: - # Opt out of reporting anonymized usage metrics to PowerSync telemetry service - disable_telemetry_sharing: false + # audience: ['powersync-dev', 'powersync', 'http://localhost:8080'] ``` -For some additional details on this file, see [Service Configuration](/configuration/powersync-service/self-hosted-instances). - -Next, the `client_auth` sections needs to be completed. +### `sync-config.yaml` -The PowerSync Service can verify JWTs from client applications using either HMAC (HS\*) or RSA (RS\*) based algorithms. It can also obtain the necessary settings from Supabase automatically if you are using it. +Defines what data syncs to clients. See [Sync Streams](/sync/streams/overview) for full syntax. -1. In the case of Supabase, simply set the `supabase` key to `true` -2. In the case of HS\* algorithms, specify the secret as base64 encoded in the `k`field. -3. In the case of RS\* based algorithms, the public key(s) can be specified either by supplying a JWKS URI or hard coding the public key in the config file. - 1. If using a JWKS URI, we have an example endpoint available [here](https://hlstmcktecziostiaplz.supabase.co/functions/v1/powersync-jwks); ensure that your response looks similar. - 2. If hardcoding, see the syntax below. We also have an example [key generator](https://github.com/powersync-ja/self-host-demo/tree/main/key-generator) script. +```yaml +config: + edition: 3 + +streams: + global: + # Streams without parameters sync the same data to all users + auto_subscribe: true + queries: + - SELECT * FROM todos + - SELECT * FROM lists +``` -example of hard coded HS256 config +### Start the stack -```yaml -client_auth: - jwks: - keys: - - kty: 'RSA' - n: 't-3d9e6XGtVsDB49CxVPn6P4OK6ir-wHP0CtTTq3VK6ofz2TWNrcHbCks6MszyWuBN1qb1ir_qudwwIeS69InEFm9WOYG1jIp6OBUNY4LPvkWfhSqcU6BasRAkYllC65CnSiVuTs4TlVgE-CBZQwQCvyrYgQgczC-GnI2HEB2SGTnXnBTXmAFEAd7xh_IROURZm1C6RnD2fXmiR1PxJsBn1w2hWYk0L8rQPlkthXwHNKd964rDir2qSTzVaHVvrFaxKiTlTe8uP4PR6OZT4pE0NDI2KNkyPauIeXp8HrwpZiUd8Znc8LQ-mj-hxfxtynYhxvcd6O_jyxa_41wjPeeQ' - e: 'AQAB' - alg: 'RS256' - kid: 'powersync-0abb8a873a' +```bash +docker compose up ``` + +## Resources + +- [self-host-demo](https://github.com/powersync-ja/self-host-demo) — complete working examples with Docker Compose +- [Self-Hosted Instance Configuration](/configuration/powersync-service/self-hosted-instances) — full `service.yaml` reference +- [Sync Streams](/sync/streams/overview) — sync config syntax +- [Generate a Development Token](/intro/setup-guide#5-generate-a-development-token) — for testing without a full auth setup From b45ec544cc7fa09349e7ef13a5599d599aeee0ac Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 25 Feb 2026 16:39:07 +0200 Subject: [PATCH 09/20] Improve setup guide flow --- configuration/auth/development-tokens.mdx | 3 +- intro/setup-guide.mdx | 408 +++++++++------------- snippets/dev-token-self-hosted-steps.mdx | 46 ++- 3 files changed, 202 insertions(+), 255 deletions(-) diff --git a/configuration/auth/development-tokens.mdx b/configuration/auth/development-tokens.mdx index d49c4a8f..bc8ebf3e 100644 --- a/configuration/auth/development-tokens.mdx +++ b/configuration/auth/development-tokens.mdx @@ -30,8 +30,7 @@ This can also be used to generate a token for a specific user to debug issues. - For self-hosted setups, you can generate development tokens using the [powersync-service test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client): - + Follow the steps below. Steps 1 and 2 configure signing keys and your PowerSync config; in Step 3 you can use the **CLI (recommended)** or the [test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client) to generate the token. diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index e7155a22..9ff92fdd 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -20,6 +20,10 @@ import DevTokenSelfHostedSteps from '/snippets/dev-token-self-hosted-steps.mdx'; PowerSync needs to connect to your source database (Postgres, MongoDB, MySQL or SQL Server) to replicate data. Before setting up PowerSync, you need to configure your database with the appropriate permissions and replication settings. + +Using the CLI and want a managed self-hosted Postgres instance? You can skip to [Step 2](#2-set-up-powersync-service-instance) and set one up automatically. + + Configuring Postgres for PowerSync involves three main tasks: @@ -176,168 +180,163 @@ PowerSync needs to connect to your source database (Postgres, MongoDB, MySQL or PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be self-hosted (PowerSync Open Edition or PowerSync Enterprise Self-Hosted Edition). - - **Dashboard** - - If you haven't yet, sign up for a free PowerSync Cloud account [here](https://accounts.journeyapps.com/portal/powersync-signup?s=docs). - - After signing up, you will be taken to the [PowerSync Dashboard](https://dashboard.powersync.com/). - - Here, create a new project. _Development_ and _Production_ instances of the PowerSync Service will be created by default in the project. - - --- - - **CLI** + + If you haven't yet, sign up for a free PowerSync Cloud account [here](https://accounts.journeyapps.com/portal/powersync-signup?s=docs). - If you haven't yet, sign up for a free PowerSync Cloud account [here](https://accounts.journeyapps.com/portal/powersync-signup?s=docs). + After signing up, you will be taken to the [PowerSync Dashboard](https://dashboard.powersync.com/). - Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), then log in and scaffold the config directory: - - ```bash - npm install -g powersync - powersync login - powersync init cloud - ``` - - This creates a `powersync/` directory with `service.yaml` (instance name, region, connection, auth) and `sync-config.yaml` (sync config). Edit `powersync/service.yaml` to set your instance name and region — you'll configure the database connection in the next step. - - Then create the Cloud instance: - - ```bash - powersync link cloud --create --project-id= - ``` + Here, create a new project. _Development_ and _Production_ instances of the PowerSync Service will be created by default in the project. + - Find your project ID in the [PowerSync Dashboard](https://dashboard.powersync.com) URL, or run `powersync fetch instances` after logging in. - + + If you haven't yet, sign up for a free PowerSync Cloud account [here](https://accounts.journeyapps.com/portal/powersync-signup?s=docs). - - **CLI** + Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), then log in and scaffold the config directory: - Recommended for getting started. For custom setups use the [Manual](#manual-docker-setup) path below. Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), scaffold the config directory, and generate the Docker Compose setup: + ```bash + npm install -g powersync + powersync login + powersync init cloud + ``` - ```bash - npm install -g powersync - powersync init self-hosted - powersync docker configure --database postgres --storage postgres - ``` + This creates a `powersync/` directory with `service.yaml` (instance name, region, connection, auth) and `sync-config.yaml` (sync config). Edit `powersync/service.yaml` to set your instance name and region — you'll configure the database connection in the next step. - Docker sets up Postgres for both the source database and bucket storage and creates `powersync/docker/docker-compose.yaml`. Other databases are supported as well, you will learn more about this in the next step. Before starting, replace `powersync/sync-config.yaml` with this minimal sync config: + Then create the Cloud instance: - ```yaml - config: - edition: 2 + ```bash + powersync link cloud --create --project-id= + ``` - streams: - todos: - # Streams without parameters sync the same data to all users - auto_subscribe: true - query: "SELECT * FROM todos" - ``` + Find your project ID in the [PowerSync Dashboard](https://dashboard.powersync.com) URL, or run `powersync fetch instances` after logging in. + - You'll update this with your actual tables/collections in a later step. + + Recommended for getting started. For custom setups use the **Manual (Self-Hosted)** tab. Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), scaffold the config directory, and generate the Docker Compose setup: - Then start the PowerSync Service: + ```bash + npm install -g powersync + powersync init self-hosted + powersync docker configure --database postgres --storage postgres + ``` - ```bash - powersync docker start - ``` + Docker sets up Postgres for both the source database and bucket storage and creates `powersync/docker/docker-compose.yaml`. Other databases are supported as well, you will learn more about this in the next step. Before starting, replace `powersync/sync-config.yaml` with this minimal sync config: - Run `powersync fetch status` to verify it's running. + ```yaml + config: + edition: 2 + + streams: + todos: + # Streams without parameters sync the same data to all users + auto_subscribe: true + query: "SELECT * FROM todos" + ``` - --- + You'll update this with your actual tables/collections in a later step. - **Manual** + Then start the PowerSync Service: - Self-hosted PowerSync runs via Docker. The commands below illustrate the basic PowerSync Service requirements. + ```bash + powersync docker start + ``` - Below is a minimal example using Postgres for bucket storage. MongoDB is also supported as bucket storage. The source database connection is configured in the next step — you can use the Docker-managed Postgres from Step 1 or point to an external database instead. + Run `powersync fetch status` to verify it's running. - ```bash - # 1. Create a directory for your config - mkdir powersync-service && cd powersync-service + + **Learn More** + * [Self-Hosting Introduction](/intro/self-hosting) + * [Self-Host Demo App](https://github.com/powersync-ja/self-host-demo) for complete working examples. + * [Self-Hosted Service Configuration](/configuration/powersync-service/self-hosted-instances) for more details on the config file structure. + * [CLI documentation](/tools/cli) + + - # 2. Set up bucket storage (Postgres and MongoDB are supported) - docker run -d \ - --name powersync-postgres-storage \ - --network powersync-network \ - -p 5433:5432 \ - -e POSTGRES_PASSWORD="my_secure_storage_password" \ - -e POSTGRES_DB=powersync_storage \ - postgres:18 + + Self-hosted PowerSync runs via Docker. The commands below illustrate the basic PowerSync Service requirements. - ## Set up Postgres storage user - docker exec -it powersync-postgres-storage psql -U postgres -d powersync_storage -c " - CREATE USER powersync_storage_user WITH PASSWORD 'my_secure_user_password'; - GRANT CREATE ON DATABASE powersync_storage TO powersync_storage_user;" + Below is a minimal example using Postgres for bucket storage. MongoDB is also supported as bucket storage. The source database connection is configured in the next step — you can use the Docker-managed Postgres from Step 1 or point to an external database instead. - # 3. Create config.yaml (see below) + ```bash + # 1. Create a directory for your config + mkdir powersync-service && cd powersync-service + + # 2. Set up bucket storage (Postgres and MongoDB are supported) + docker run -d \ + --name powersync-postgres-storage \ + --network powersync-network \ + -p 5433:5432 \ + -e POSTGRES_PASSWORD="my_secure_storage_password" \ + -e POSTGRES_DB=powersync_storage \ + postgres:18 + + ## Set up Postgres storage user + docker exec -it powersync-postgres-storage psql -U postgres -d powersync_storage -c " + CREATE USER powersync_storage_user WITH PASSWORD 'my_secure_user_password'; + GRANT CREATE ON DATABASE powersync_storage TO powersync_storage_user;" + + # 3. Create config.yaml (see below) + + # 4. Run PowerSync Service + # The Service config can be specified as an environment variable (shown below), as a filepath, or as a command line parameter + # See these docs for more details: https://docs.powersync.com/configuration/powersync-service/self-hosted-instances + docker run -d \ + --name powersync \ + --network powersync-network \ + -p 8080:8080 \ + -e POWERSYNC_CONFIG_B64="$(base64 -i ./config.yaml)" \ + journeyapps/powersync-service:latest + ``` - # 4. Run PowerSync Service - # The Service config can be specified as an environment variable (shown below), as a filepath, or as a command line parameter - # See these docs for more details: https://docs.powersync.com/configuration/powersync-service/self-hosted-instances - docker run -d \ - --name powersync \ - --network powersync-network \ - -p 8080:8080 \ - -e POWERSYNC_CONFIG_B64="$(base64 -i ./config.yaml)" \ - journeyapps/powersync-service:latest - ``` + **Basic `config.yaml` structure:** - **Basic `config.yaml` structure:** - - ```yaml - # Source database connection (see the next step for more details) - replication: - connections: - - type: postgresql # or mongodb, mysql, mssql - uri: postgresql://powersync_role:myhighlyrandompassword@powersync-postgres:5432/postgres - sslmode: disable # Only for local/private networks - - # Connection settings for bucket storage (Postgres and MongoDB are supported) - storage: - type: postgresql - uri: postgresql://powersync_storage_user:my_secure_user_password@powersync-postgres-storage:5432/powersync_storage - sslmode: disable # Use 'disable' only for local/private networks - - # Sync Rules (defined in a later step) - sync_rules: - content: | - bucket_definitions: - global: - data: - - SELECT * FROM lists - - SELECT * FROM todos - ``` + ```yaml + # Source database connection (see the next step for more details) + replication: + connections: + - type: postgresql # or mongodb, mysql, mssql + uri: postgresql://powersync_role:myhighlyrandompassword@powersync-postgres:5432/postgres + sslmode: disable # Only for local/private networks + + # Connection settings for bucket storage (Postgres and MongoDB are supported) + storage: + type: postgresql + uri: postgresql://powersync_storage_user:my_secure_user_password@powersync-postgres-storage:5432/powersync_storage + sslmode: disable # Use 'disable' only for local/private networks + + # Sync Rules (defined in a later step) + sync_rules: + content: | + bucket_definitions: + global: + data: + - SELECT * FROM lists + - SELECT * FROM todos + ``` - - **Note**: This example assumes you've configured your source database with the required user and publication (see the previous step) - and are running it via Docker in the 'powersync-network' network. + + **Note**: This example assumes you've configured your source database with the required user and publication (see the previous step) + and are running it via Docker in the 'powersync-network' network. - If you are not using Docker, you will need to specify the connection details in the `config.yaml` file manually (see next step for more details). - + If you are not using Docker, you will need to specify the connection details in the `config.yaml` file manually (see next step for more details). + - - The [PowerSync CLI](/tools/cli) works alongside any running instance — including one set up manually. Once your service is running, you can use `powersync fetch status`, `powersync validate`, `powersync generate schema`, and `powersync generate token` without having used the CLI to set it up. - + + **Learn More** + * [Self-Hosting Introduction](/intro/self-hosting) + * [Self-Host Demo App](https://github.com/powersync-ja/self-host-demo) for complete working examples. + * [Self-Hosted Service Configuration](/configuration/powersync-service/self-hosted-instances) for more details on the config file structure. + * [CLI documentation](/tools/cli) + - - **Learn More** - * [Self-Hosting Introduction](/intro/self-hosting) - * [Self-Host Demo App](https://github.com/powersync-ja/self-host-demo) for complete working examples. - * [CLI documentation](/tools/cli). - * [Self-Hosted Service Configuration](/configuration/powersync-service/self-hosted-instances) for more details on the config file structure. - - - + + # 3. Connect PowerSync to Your Source Database The next step is to connect your PowerSync Service instance to your source database. - - **Dashboard** - + In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance, then go to **Database Connections**: 1. Click **Connect to Source Database** @@ -360,11 +359,9 @@ The next step is to connect your PowerSync Service instance to your source datab For more details on database connections, including provider-specific connection details (Supabase, AWS RDS, MongoDB Atlas, etc.), see [Source Database Connection](/configuration/source-db/connection). + - --- - - **CLI** - + Edit `powersync/service.yaml` (created in the previous step) with your connection details. Use `!env` for secrets: @@ -414,9 +411,7 @@ The next step is to connect your PowerSync Service instance to your source datab - - **CLI** - + If you used Docker in the previous step, the source database connection is already configured. `service.yaml` reads the connection URI from `!env PS_DATA_SOURCE_URI`. The Docker-managed Postgres (`pg-db`) was also pre-configured with `wal_level=logical` and a `powersync` publication by the init scripts. If you want to use an **external database** instead, update `PS_DATA_SOURCE_URI` in `powersync/docker/.env` with your connection details, then restart: @@ -426,11 +421,9 @@ The next step is to connect your PowerSync Service instance to your source datab ``` You'll also need to complete the source database setup from Step 1 (replication user, publication) on your external database before this will work. + - --- - - **Manual** - + Configure the source database connection in your `config.yaml` file (as you did in the previous step). Examples for the different database types are below. @@ -531,57 +524,49 @@ We recommend starting with a simple **global bucket** that syncs data to all use ### Deploy Sync Rules - - **Dashboard** - - In the [PowerSync Dashboard](https://dashboard.powersync.com/): - - 1. Select your project and instance - 2. Go to the **Sync Rules** view - 3. Edit the YAML directly in the dashboard - 4. Click **Deploy** to validate and deploy your Sync Rules - - --- - - **CLI** - - Edit `powersync/sync-config.yaml` with your sync config, then validate and deploy to the linked Cloud instance: + + In the [PowerSync Dashboard](https://dashboard.powersync.com/): - ```bash - powersync validate - powersync deploy - ``` - - This deploys your full config (connection, auth, and sync config). For subsequent sync-only changes, use `powersync deploy sync-config` instead. - + 1. Select your project and instance + 2. Go to the **Sync Rules** view + 3. Edit the YAML directly in the dashboard + 4. Click **Deploy** to validate and deploy your Sync Rules + - - **CLI** + + Edit `powersync/sync-config.yaml` with your sync config, then validate and deploy to the linked Cloud instance: - Edit `powersync/sync-config.yaml` with your sync config. The default file has a placeholder (`SELECT * FROM todos`) — replace it with your actual table/collection names. Then apply the changes: + ```bash + powersync validate + powersync deploy + ``` - ```bash - powersync validate - powersync docker reset - ``` + This deploys your full config (connection, auth, and sync config). For subsequent sync-only changes, use `powersync deploy sync-config` instead. + - --- + + Edit `powersync/sync-config.yaml` with your sync config. The default file has a placeholder (`SELECT * FROM todos`) — replace it with your actual table/collection names. Then apply the changes: - **Manual** + ```bash + powersync validate + powersync docker reset + ``` + - Add the sync rules to your `config.yaml`, for example: + + Add the sync rules to your `config.yaml`, for example: - ```yaml - sync_rules: - content: | - bucket_definitions: - global: - data: - - SELECT * FROM todos - - SELECT * FROM lists WHERE archived = false - ``` - - + ```yaml + sync_rules: + content: | + bucket_definitions: + global: + data: + - SELECT * FROM todos + - SELECT * FROM lists WHERE archived = false + ``` + + **Note**: Table/collection names within your Sync Rules must match the table names defined in your client-side schema (defined in a later step below). @@ -603,9 +588,7 @@ You'll use this token for two purposes: - **Connecting your app** (in a later step) to test the client SDK integration - - **Dashboard** - + 1. In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance 2. Go to the **Client Auth** view 3. Check the **Development tokens** setting and save your changes @@ -616,11 +599,9 @@ You'll use this token for two purposes: Development tokens expire after 12 hours. + - --- - - **CLI** - + Generate a development token with: ```bash @@ -646,57 +627,12 @@ You'll use this token for two purposes: - **CLI** - - `powersync generate token` signs a JWT using the client auth key from `service.yaml`. The default template doesn't include one, so add an HMAC key first. - - Generate a random secret (base64url-encoded): - - ```bash - openssl rand -base64 32 | tr '+/' '-_' | tr -d '=' - ``` - - - Add the secret to `powersync/service.yaml`: - - ```yaml - client_auth: - audience: ['http://localhost:8080', 'http://127.0.0.1:8080'] - # static collection of public keys for JWT verification - jwks: - keys: - - kty: oct - alg: 'HS256' - k: '[base64url-encoded-shared-secret]' - kid: 'dev-key-1' - ``` - - Apply the changes and generate the token: - - ```bash - powersync docker reset - powersync generate token --subject=test-user - ``` - - Replace test-user with the user ID you want to authenticate: - - If you’re using global Sync Rules, you can use any value (e.g., test-user) since all data syncs to all users - - If you’re using user-specific Sync Rules, use a user ID that matches a user in your database (this will be used as request.user_id() in your Sync Rules) - - - Development tokens expire after 12 hours. - - - --- - - **Manual** - - For self-hosted setups, you can generate development tokens using the [powersync-service test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client): + Follow the steps below. Steps 1 and 2 configure signing keys and your PowerSync config; in Step 3 you can use the **CLI (recommended)** or the test-client to generate the token. - # 6. [Optional] Test Sync with the Sync Diagnostics Client Before implementing the PowerSync Client SDK in your app, you can validate that syncing is working correctly using our [Sync Diagnostics Client](https://diagnostics-app.powersync.com) (this hosted version works with both PowerSync Cloud and self-hosted setups). diff --git a/snippets/dev-token-self-hosted-steps.mdx b/snippets/dev-token-self-hosted-steps.mdx index 5018ef0a..37f0962d 100644 --- a/snippets/dev-token-self-hosted-steps.mdx +++ b/snippets/dev-token-self-hosted-steps.mdx @@ -36,8 +36,8 @@ - - Add the `client_auth` parameter to your `config.yaml`: + + Add the `client_auth` parameter to your PowerSync config (e.g. `config.yaml` or, when using the CLI, `service.yaml`): @@ -80,25 +80,37 @@ - 1. If you have not done so already, clone the [`powersync-service` repo](https://github.com/powersync-ja/powersync-service/tree/main) - 2. Install the dependencies: - - In the project root, run the following commands: + Choose either the CLI (recommended) or the test-client: + + + + If you use the [PowerSync CLI](/tools/cli), apply your config changes (e.g. restart your PowerSync Service or run `powersync docker reset` if running locally with Docker), then run: + ```bash - pnpm install - pnpm build + powersync generate token --subject=test-user ``` - - In the `test-client` directory, run the following commands: + + Replace `test-user` with the user ID you want to authenticate: + - If you're using **global Sync Rules** or data without parameters, you can use any value (e.g., `test-user`) since all data syncs to all users + - If you're using **user-specific Sync Rules** or **Sync Streams** that filter by user, use a user ID that matches a user in your database (this will be used as `request.user_id()` in Sync Rules or `auth.user_id()` in Sync Streams) + + + + 1. If you have not done so already, clone the [`powersync-service` repo](https://github.com/powersync-ja/powersync-service/tree/main) + 2. Install and build: + - In the project root: `pnpm install` and `pnpm build` + - In the `test-client` directory: `pnpm build` + 3. Generate a token from the `test-client` directory, pointing at your config file: + ```bash - pnpm build + node dist/bin.js generate-token --config path/to/config.yaml --sub test-user ``` - 3. Generate a new token by running the following command in the `test-client` directory with your updated `config.yaml` file: - ```bash - node dist/bin.js generate-token --config path/to/config.yaml --sub test-user - ``` - - Replace `test-user` with the user ID you want to authenticate: - - If you're using **global Sync Rules**, you can use any value (e.g., `test-user`) since all data syncs to all users - - If you're using **user-specific Sync Rules**, use a user ID that matches a user in your database (this will be used as `request.user_id()` in your Sync Rules) + + Replace `test-user` with the user ID you want to authenticate: + - If you're using **global Sync Rules** or data without parameters, you can use any value (e.g., `test-user`) since all data syncs to all users + - If you're using **user-specific Sync Rules** or **Sync Streams** that filter by user, use a user ID that matches a user in your database (this will be used as `request.user_id()` in Sync Rules or `auth.user_id()` in Sync Streams) + + From 265e73de4c064cbf8c3c49af8d03dc5268e987f6 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 25 Feb 2026 16:51:56 +0200 Subject: [PATCH 10/20] Minor polish --- configuration/auth/development-tokens.mdx | 2 +- configuration/source-db/setup.mdx | 2 +- intro/setup-guide.mdx | 4 ++-- tools/cli.mdx | 14 +++++++++----- 4 files changed, 13 insertions(+), 9 deletions(-) diff --git a/configuration/auth/development-tokens.mdx b/configuration/auth/development-tokens.mdx index bc8ebf3e..db9c820e 100644 --- a/configuration/auth/development-tokens.mdx +++ b/configuration/auth/development-tokens.mdx @@ -30,7 +30,7 @@ This can also be used to generate a token for a specific user to debug issues. - Follow the steps below. Steps 1 and 2 configure signing keys and your PowerSync config; in Step 3 you can use the **CLI (recommended)** or the [test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client) to generate the token. + Follow the steps below. Steps 1 and 2 configure signing keys and your PowerSync Service config; in Step 3 you can use the PowerSync CLI (recommended) or the [test-client](https://github.com/powersync-ja/powersync-service/tree/main/test-client) to generate the token. diff --git a/configuration/source-db/setup.mdx b/configuration/source-db/setup.mdx index 4946f785..7f52c552 100644 --- a/configuration/source-db/setup.mdx +++ b/configuration/source-db/setup.mdx @@ -615,7 +615,7 @@ Due to the fundamental differences in how CDC works compared to logical replicat 2. **Polling Interval**: The frequency at which PowerSync polls the CDC change tables for changes. The default value is once every 1000ms. This can be changed by setting the `pollingIntervalMs` parameter in the PowerSync configuration. -Configuration parameters for SQL Server like `pollingIntervalMs` and `pollingBatchSize` (see below) can currently only be [set when self-hosting](/intro/setup-guide#self-hosted-2) PowerSync. We are working on exposing these settings for SQL Server source database connections in the PowerSync Dashboard for PowerSync Cloud instances. +Configuration parameters for SQL Server like `pollingIntervalMs` and `pollingBatchSize` (see below) can currently only be [set when self-hosting](/intro/self-hosting) PowerSync. We are working on exposing these settings for SQL Server source database connections in the PowerSync Dashboard for PowerSync Cloud instances. ### Memory Management diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index 9ff92fdd..fc7158b9 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -1,7 +1,7 @@ --- title: "PowerSync Setup Guide" sidebarTitle: "Setup Guide" -description: "This guide walks you through adding PowerSync to your app project step-by-step. " +description: "This guide walks you through adding PowerSync to your app project step-by-step." --- import LocalOnly from '/snippets/local-only-escape.mdx'; @@ -21,7 +21,7 @@ import DevTokenSelfHostedSteps from '/snippets/dev-token-self-hosted-steps.mdx'; PowerSync needs to connect to your source database (Postgres, MongoDB, MySQL or SQL Server) to replicate data. Before setting up PowerSync, you need to configure your database with the appropriate permissions and replication settings. -Using the CLI and want a managed self-hosted Postgres instance? You can skip to [Step 2](#2-set-up-powersync-service-instance) and set one up automatically. +Using the [PowerSync CLI](/tools/cli) and want a managed Postgres instance? You can skip to [Step 2](#2-set-up-powersync-service-instance) and set one up automatically with the **CLI (Self-Hosted)** tab. diff --git a/tools/cli.mdx b/tools/cli.mdx index f58683e8..9efaaf5a 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -9,11 +9,15 @@ The PowerSync CLI lets you manage PowerSync Service instances, deploy sync confi **Self-hosted:** You can link to an existing PowerSync Service instance and run a subset of commands (e.g. `powersync fetch status`, `powersync generate schema`, `powersync validate`). Docker is supported for local development. + + For a full step-by-step flow using the CLI, use the [Setup Guide](/intro/setup-guide): choose the **CLI (Cloud)** or **CLI (Self-Hosted)** tab in steps 2–5 to configure your instance, connect the source database, deploy sync config, and generate development tokens. + + - The PowerSync CLI was overhauled in **version TODO** (see the [powersync](https://www.npmjs.com/package/powersync) npm package for the current release). The redesign is based on this [public proposal](https://docs.google.com/document/d/1iqpJF2gog2jB-ZWeN8TBEjcad8aBKNKbue2yJ21q_-s/edit). + The PowerSync CLI was overhauled in version TODO. The redesign is based on this [design proposal](https://docs.google.com/document/d/1iqpJF2gog2jB-ZWeN8TBEjcad8aBKNKbue2yJ21q_-s/edit). + + Main improvements: **self-hosted support** (link to your own PowerSync Service and run commands such as fetch status, generate schema, validate); **open source**; and **improved DX**, including validated config files (`service.yaml`, `sync-config.yaml`) used for creating and deploying changes to PowerSync instances instead of long command-line flags. - Main improvements in the new version: **self-hosted support** (link to your own PowerSync Service and run commands such as fetch status, generate schema, validate); **open source**; and **improved DX**, including validated config files (`service.yaml`, `sync-config.yaml`) used for creating and deploying changes to PowerSync instances instead of long command-line flags. - See [Migrating from the previous CLI](#migrating-from-the-previous-cli) if you used the older flow. @@ -177,9 +181,9 @@ If you used the older PowerSync CLI (e.g. `npx powersync init` to set token and **Summary:** Authenticate with **`powersync login`** (or `TOKEN` in CI). Use a **config directory** with `service.yaml` and `sync-config.yaml` as the source of truth. **Link** with **`powersync link cloud`** or **`powersync pull instance`**, then run **`powersync deploy`** or **`powersync deploy sync-config`**. No more setting “current instance” separately from config—the directory and `cli.yaml` define the target. -## More documentation (CLI repository) +## Additional documentation (CLI Repository) -Additional and advanced topics are documented in the PowerSync CLI repository: +The following are documented in the [PowerSync CLI repository](https://github.com/powersync-ja/powersync-cli); this page covers the main workflows and commands you need for the [Setup Guide](/intro/setup-guide) and day-to-day use. | Resource | Description | |----------|-------------| From 80c81dd3914d152c4bcb5e7ab336db06373b0d16 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 25 Feb 2026 16:55:39 +0200 Subject: [PATCH 11/20] Wording --- intro/setup-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index fc7158b9..04a4fc02 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -211,7 +211,7 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel - Recommended for getting started. For custom setups use the **Manual (Self-Hosted)** tab. Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), scaffold the config directory, and generate the Docker Compose setup: + Recommended for getting started: the CLI scaffolds your config directory and generates the Docker Compose stack (including a managed Postgres instance) so you can run PowerSync locally with minimal setup. For custom setups use the **Manual (Self-Hosted)** tab. Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), then run: ```bash npm install -g powersync From 2a132dd75cc376fee62cf3247954f30a92784f97 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 26 Feb 2026 15:47:30 +0200 Subject: [PATCH 12/20] rename powersync fetch status to powersync status --- intro/setup-guide.mdx | 2 +- maintenance-ops/self-hosting/diagnostics.mdx | 6 +++--- maintenance-ops/self-hosting/overview.mdx | 2 +- tools/cli.mdx | 10 +++++----- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index 86baecc0..23559e42 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -240,7 +240,7 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel powersync docker start ``` - Run `powersync fetch status` to verify it's running. + Run `powersync status` to verify it's running. **Learn More** diff --git a/maintenance-ops/self-hosting/diagnostics.mdx b/maintenance-ops/self-hosting/diagnostics.mdx index cf37c509..1a4d69aa 100644 --- a/maintenance-ops/self-hosting/diagnostics.mdx +++ b/maintenance-ops/self-hosting/diagnostics.mdx @@ -11,13 +11,13 @@ This API provides the following diagnostic information: ## CLI -If you have the [PowerSync CLI](/tools/cli) installed, use `powersync fetch status` to check instance status without calling the API directly. This works with any running PowerSync instance — local or remote. +If you have the [PowerSync CLI](/tools/cli) installed, use `powersync status` to check instance status without calling the API directly. This works with any running PowerSync instance — local or remote. ```bash -powersync fetch status +powersync status # Extract a specific field -powersync fetch status --output=json | jq '.connections[0]' +powersync status --output=json | jq '.connections[0]' ``` ## Diagnostics API diff --git a/maintenance-ops/self-hosting/overview.mdx b/maintenance-ops/self-hosting/overview.mdx index 3b471b1d..b1adc3d5 100644 --- a/maintenance-ops/self-hosting/overview.mdx +++ b/maintenance-ops/self-hosting/overview.mdx @@ -7,7 +7,7 @@ import SelfHostDeploymentPlatformsCards from '/snippets/self-host-deployment-pla - The [PowerSync CLI](/tools/cli) provides commands that work alongside any running self-hosted instance: `powersync fetch status`, `powersync validate`, `powersync generate schema`, `powersync generate token`. You don't need to have set up the instance with the CLI to use these. + The [PowerSync CLI](/tools/cli) provides commands that work alongside any running self-hosted instance: `powersync status`, `powersync validate`, `powersync generate schema`, `powersync generate token`. You don't need to have set up the instance with the CLI to use these. ## Production Topics diff --git a/tools/cli.mdx b/tools/cli.mdx index 9efaaf5a..2d8ce2af 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -7,7 +7,7 @@ The PowerSync CLI lets you manage PowerSync Service instances, deploy sync confi **Cloud:** Full support for PowerSync Cloud. Log in with a personal access token, then define your instance config in a `powersync/` directory (`service.yaml`, `sync-config.yaml`) and deploy with `powersync deploy`. -**Self-hosted:** You can link to an existing PowerSync Service instance and run a subset of commands (e.g. `powersync fetch status`, `powersync generate schema`, `powersync validate`). Docker is supported for local development. +**Self-hosted:** You can link to an existing PowerSync Service instance and run a subset of commands (e.g. `powersync status`, `powersync generate schema`, `powersync validate`). Docker is supported for local development. For a full step-by-step flow using the CLI, use the [Setup Guide](/intro/setup-guide): choose the **CLI (Cloud)** or **CLI (Self-Hosted)** tab in steps 2–5 to configure your instance, connect the source database, deploy sync config, and generate development tokens. @@ -106,13 +106,13 @@ This creates the config directory, writes `cli.yaml`, and downloads `service.yam ### Run commands without local config -You can run commands (e.g. `powersync generate schema`, `powersync generate token`, `powersync fetch status`) against an instance whose config is managed elsewhere (e.g. the Dashboard). Either link once with `powersync link cloud --instance-id= --project-id=`, or pass `--instance-id` and `--project-id` (and `--org-id` when your token has multiple orgs) on each command. You can also set `INSTANCE_ID`, `PROJECT_ID`, and optionally `ORG_ID` in the environment. For how the CLI resolves context (flags vs environment variables vs `cli.yaml`), and for multiple instances (e.g. dev/staging/prod with separate directories or `!env`), see the [CLI usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#supplying-linking-information-for-cloud-and-self-hosted-commands) in the PowerSync CLI repository. +You can run commands (e.g. `powersync generate schema`, `powersync generate token`, `powersync status`) against an instance whose config is managed elsewhere (e.g. the Dashboard). Either link once with `powersync link cloud --instance-id= --project-id=`, or pass `--instance-id` and `--project-id` (and `--org-id` when your token has multiple orgs) on each command. You can also set `INSTANCE_ID`, `PROJECT_ID`, and optionally `ORG_ID` in the environment. For how the CLI resolves context (flags vs environment variables vs `cli.yaml`), and for multiple instances (e.g. dev/staging/prod with separate directories or `!env`), see the [CLI usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#supplying-linking-information-for-cloud-and-self-hosted-commands) in the PowerSync CLI repository. ## Self-hosted workflows Run **`powersync init self-hosted`** to scaffold a config directory. Edit `service.yaml` with your instance details and use **`powersync link self-hosted --api-url `** to link to an existing running PowerSync Service. The CLI does not create or deploy to self-hosted instances; you manage the server and its config yourself. -Supported self-hosted commands include: `powersync fetch status`, `powersync generate schema`, `powersync generate token`, `powersync validate`. Cloud-only commands (`powersync deploy`, `powersync pull instance`, `powersync fetch instances`, etc.) do not apply. +Supported self-hosted commands include: `powersync status`, `powersync generate schema`, `powersync generate token`, `powersync validate`. Cloud-only commands (`powersync deploy`, `powersync pull instance`, `powersync fetch instances`, etc.) do not apply. ### Docker (local development) @@ -142,7 +142,7 @@ Use **`powersync docker reset`** when you need a clean state (stop and remove, t | `powersync validate` | Validate config and sync rules/streams | | `powersync fetch instances` | List Cloud instances (optionally by project/org) | | `powersync fetch config` | Print linked Cloud instance config (YAML/JSON) | -| `powersync fetch status` | Instance diagnostics (connections, replication) | +| `powersync status` | Instance diagnostics (connections, replication) | | `powersync generate schema --output=ts --output-path=schema.ts` | Generate client-side schema | | `powersync generate token --subject=user-123` | Generate a development JWT | @@ -176,7 +176,7 @@ If you used the older PowerSync CLI (e.g. `npx powersync init` to set token and | `powersync instance deploy` (interactive or long flag list) | Edit **`powersync/service.yaml`** and **`powersync/sync-config.yaml`**, then **`powersync deploy`**. Config is in files, not command args. | | `powersync instance config` | **`powersync fetch config`** (output as YAML or JSON with `--output`). | | Deploy only sync rules | **`powersync deploy sync-config`**. | -| `powersync instance schema` | **`powersync generate schema --output=... --output-path=...`** (and/or **`powersync fetch status`** for diagnostics). | +| `powersync instance schema` | **`powersync generate schema --output=... --output-path=...`** (and/or **`powersync status`** for diagnostics). | | Org/project stored by init | Pass **`--org-id`** and **`--project-id`** when needed, or use **`powersync link cloud`** so they are stored in **`powersync/cli.yaml`**. For CI, use env vars: **`TOKEN`**, **`INSTANCE_ID`**, **`PROJECT_ID`**, **`ORG_ID`** (optional). | **Summary:** Authenticate with **`powersync login`** (or `TOKEN` in CI). Use a **config directory** with `service.yaml` and `sync-config.yaml` as the source of truth. **Link** with **`powersync link cloud`** or **`powersync pull instance`**, then run **`powersync deploy`** or **`powersync deploy sync-config`**. No more setting “current instance” separately from config—the directory and `cli.yaml` define the target. From b32b7e83557f982cc1654802b55af3bba1c5c243 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 26 Feb 2026 16:03:58 +0200 Subject: [PATCH 13/20] Renames and polish --- .../self-hosting/update-sync-rules.mdx | 4 +-- tools/cli.mdx | 26 +++++++++---------- tools/local-development.mdx | 6 ++--- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/maintenance-ops/self-hosting/update-sync-rules.mdx b/maintenance-ops/self-hosting/update-sync-rules.mdx index 1f4d4b41..a2a6f1fc 100644 --- a/maintenance-ops/self-hosting/update-sync-rules.mdx +++ b/maintenance-ops/self-hosting/update-sync-rules.mdx @@ -5,7 +5,7 @@ description: "How to update Sync Streams (or legacy Sync Rules) in a self-hosted There are three ways to update your sync config in a self-hosted deployment: -1. **CLI** — Edit your config and apply with `powersync docker reset` (recommended if using the CLI) +1. **CLI** — Edit your config and apply with `powersync docker reset` 2. **Config file** — Update your config and restart the service 3. **API endpoint** — Deploy at runtime without restarting @@ -17,7 +17,7 @@ There are three ways to update your sync config in a self-hosted deployment: - Run `powersync validate` in the CLIbefore deploying to catch errors in your sync config without applying changes. Works with any running PowerSync instance. + Run `powersync validate` in the CLI before deploying to catch errors in your sync config without applying changes. ## Option 1: CLI diff --git a/tools/cli.mdx b/tools/cli.mdx index 2d8ce2af..35a0a96f 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -3,11 +3,11 @@ title: "CLI" description: "Manage PowerSync Cloud and self-hosted instances from the command line with config-as-code." --- -The PowerSync CLI lets you manage PowerSync Service instances, deploy sync config (your Sync Streams or Sync Rules), generate client schemas, and run diagnostics. It is distributed as the [powersync](https://www.npmjs.com/package/powersync) npm package. +The PowerSync CLI lets you manage PowerSync Service instances, deploy sync config (your Sync Streams or Sync Rules), generate client schemas, run diagnostics, and more. It is distributed as the [powersync](https://www.npmjs.com/package/powersync) npm package. -**Cloud:** Full support for PowerSync Cloud. Log in with a personal access token, then define your instance config in a `powersync/` directory (`service.yaml`, `sync-config.yaml`) and deploy with `powersync deploy`. +**Cloud:** Full support for PowerSync Cloud. Log in with a personal access token, then define your instance config in a `powersync/` directory (`service.yaml`, `sync-config.yaml`) in your project and deploy with `powersync deploy`. -**Self-hosted:** You can link to an existing PowerSync Service instance and run a subset of commands (e.g. `powersync status`, `powersync generate schema`, `powersync validate`). Docker is supported for local development. +**Self-hosted:** You can link to an existing PowerSync Service instance and run a subset of commands (e.g. `powersync status`, `powersync generate schema`, `powersync validate`). The CLI does not provision or deploy to a remote server; for development, you can use **Docker** to run a local PowerSync Service (and optional DB/storage) on your machine. For a full step-by-step flow using the CLI, use the [Setup Guide](/intro/setup-guide): choose the **CLI (Cloud)** or **CLI (Self-Hosted)** tab in steps 2–5 to configure your instance, connect the source database, deploy sync config, and generate development tokens. @@ -45,7 +45,7 @@ powersync login You can open a browser to [create a token in the PowerSync Dashboard](https://dashboard.powersync.com/account/access-tokens) or paste an existing token. The CLI stores the token in secure storage when available (e.g. macOS Keychain), or in a config file after confirmation. -**CI and scripts:** Set the `TOKEN` environment variable. The CLI uses `TOKEN` when set; otherwise it uses the token from `powersync login`. +**CI and scripts:** Set the `PS_ADMIN_TOKEN` environment variable. The CLI uses `PS_ADMIN_TOKEN` when set; otherwise it uses the token from `powersync login`. ```bash export TOKEN=your-personal-access-token @@ -116,7 +116,7 @@ Supported self-hosted commands include: `powersync status`, `powersync generate ### Docker (local development) -For local self-hosted development, use Docker: +The CLI can start a PowerSync Service via **Docker**: it runs the service (and optionally a source database and bucket storage) in containers on your machine. That gives you a real API to develop against without deploying to any server. ```bash powersync init self-hosted @@ -124,7 +124,7 @@ powersync docker configure powersync docker start ``` -Use **`powersync docker reset`** when you need a clean state (stop and remove, then start). For the full workflow, flags (`--database`, `--storage`, `--remove`, `--remove-volumes`), and how the Docker setup uses templates and init scripts, see the [Docker usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) in the PowerSync CLI repository. You can also run `powersync docker --help` for command options. +After `powersync docker start`, link to the local API (e.g. `powersync link self-hosted --api-url http://localhost:8080`) and use the same commands as for any self-hosted instance (`powersync status`, `powersync generate schema`, etc.). Use **`powersync docker reset`** when you need a clean state (stop and remove, then start). For the full workflow, flags (`--database`, `--storage`, `--remove`, `--remove-volumes`), and how the Docker setup uses templates and init scripts, see the [Docker usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) in the PowerSync CLI repository. You can also run `powersync docker --help` for command options. ## Common commands @@ -152,7 +152,7 @@ For full usage and flags, run `powersync --help` or `powersync --help` You can automate sync config (and full config) deployments using the CLI in CI. Use the config directory as the source of truth: keep `service.yaml` and `sync-config.yaml` in the repo (with secrets via `!env` and CI secrets), then run `powersync deploy` (or `powersync deploy sync-config`). -**Secrets:** Set `TOKEN` to your PowerSync personal access token. If the workflow does not use a linked directory, also set `INSTANCE_ID` and `PROJECT_ID` (and `ORG_ID` only if your token has multiple organizations). +**Secrets:** Set `PS_ADMIN_TOKEN` to your PowerSync personal access token. If the workflow does not use a linked directory, also set `INSTANCE_ID` and `PROJECT_ID` (and `ORG_ID` only if your token has multiple organizations). -The demo shows how to configure repository secrets and run the CLI in a workflow. With the new CLI, you typically use a `powersync/` directory in the repo and run `powersync deploy` or `powersync deploy sync-config` with `TOKEN` (and optionally `INSTANCE_ID`, `PROJECT_ID`, `ORG_ID`) set in the environment. +The demo shows how to configure repository secrets and run the CLI in a workflow. With the new CLI, you typically use a `powersync/` directory in the repo and run `powersync deploy` or `powersync deploy sync-config` with `PS_ADMIN_TOKEN` (and optionally `INSTANCE_ID`, `PROJECT_ID`, `ORG_ID`) set in the environment. ## Migrating from the previous CLI @@ -177,13 +177,13 @@ If you used the older PowerSync CLI (e.g. `npx powersync init` to set token and | `powersync instance config` | **`powersync fetch config`** (output as YAML or JSON with `--output`). | | Deploy only sync rules | **`powersync deploy sync-config`**. | | `powersync instance schema` | **`powersync generate schema --output=... --output-path=...`** (and/or **`powersync status`** for diagnostics). | -| Org/project stored by init | Pass **`--org-id`** and **`--project-id`** when needed, or use **`powersync link cloud`** so they are stored in **`powersync/cli.yaml`**. For CI, use env vars: **`TOKEN`**, **`INSTANCE_ID`**, **`PROJECT_ID`**, **`ORG_ID`** (optional). | +| Org/project stored by init | Pass **`--org-id`** and **`--project-id`** when needed, or use **`powersync link cloud`** so they are stored in **`powersync/cli.yaml`**. For CI, use env vars: **`PS_ADMIN_TOKEN`**, **`INSTANCE_ID`**, **`PROJECT_ID`**, **`ORG_ID`** (optional). | -**Summary:** Authenticate with **`powersync login`** (or `TOKEN` in CI). Use a **config directory** with `service.yaml` and `sync-config.yaml` as the source of truth. **Link** with **`powersync link cloud`** or **`powersync pull instance`**, then run **`powersync deploy`** or **`powersync deploy sync-config`**. No more setting “current instance” separately from config—the directory and `cli.yaml` define the target. +**Summary:** Authenticate with **`powersync login`** (or `PS_ADMIN_TOKEN` in CI). Use a **config directory** with `service.yaml` and `sync-config.yaml` as the source of truth. **Link** with **`powersync link cloud`** or **`powersync pull instance`**, then run **`powersync deploy`** or **`powersync deploy sync-config`**. No more setting “current instance” separately from config—the directory and `cli.yaml` define the target. ## Additional documentation (CLI Repository) -The following are documented in the [PowerSync CLI repository](https://github.com/powersync-ja/powersync-cli); this page covers the main workflows and commands you need for the [Setup Guide](/intro/setup-guide) and day-to-day use. +More information is available in the [PowerSync CLI repository](https://github.com/powersync-ja/powersync-cli). | Resource | Description | |----------|-------------| @@ -195,8 +195,8 @@ The following are documented in the [PowerSync CLI repository](https://github.co ## Known limitations * Certificates cannot be managed from the CLI. -* When secure storage is unavailable, `powersync login` may store the token in a plaintext config file after explicit confirmation; prefer `TOKEN` in CI. -* Self-hosted: the CLI does not create instances or deploy config to your server; it only links to an existing API and runs a subset of commands (fetch status, generate schema/token, validate). Docker supports local development only. +* When secure storage is unavailable, `powersync login` may store the token in a plaintext config file after explicit confirmation. +* Self-hosted: the CLI does not create or manage instances on your server, or deploy config to it; it only links to an existing API and runs a subset of commands (status, generate schema/token, validate). The sole exception is **Docker**: it starts a local PowerSync Service (and optional DB/storage) in containers on your machine for development — not a remote or production instance. ## Reference diff --git a/tools/local-development.mdx b/tools/local-development.mdx index 51c42f34..9acf44c3 100644 --- a/tools/local-development.mdx +++ b/tools/local-development.mdx @@ -14,13 +14,13 @@ If you'd prefer to write your own Docker Compose setup, here's a minimal example Create a working directory with three files: ``` -powersync-service/ - docker-compose.yml +powersync/ + docker-compose.yaml service.yaml sync-config.yaml ``` -### `docker-compose.yml` +### `docker-compose.yaml` This example uses Postgres as the source database and MongoDB as bucket storage. Postgres is also supported as bucket storage — see [Self-Hosted Instance Configuration](/configuration/powersync-service/self-hosted-instances) for details. From 445db61da5fb9fd69467ba8e4d768aed26aecdb5 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 26 Feb 2026 16:06:42 +0200 Subject: [PATCH 14/20] polish --- snippets/dev-token-self-hosted-steps.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/snippets/dev-token-self-hosted-steps.mdx b/snippets/dev-token-self-hosted-steps.mdx index 37f0962d..1df14280 100644 --- a/snippets/dev-token-self-hosted-steps.mdx +++ b/snippets/dev-token-self-hosted-steps.mdx @@ -37,7 +37,7 @@ - Add the `client_auth` parameter to your PowerSync config (e.g. `config.yaml` or, when using the CLI, `service.yaml`): + Add the `client_auth` parameter to your PowerSync config (e.g. `service.yaml`): @@ -80,11 +80,11 @@ - Choose either the CLI (recommended) or the test-client: + Choose either the [PowerSync CLI](/tools/cli) (recommended) or the test-client: - If you use the [PowerSync CLI](/tools/cli), apply your config changes (e.g. restart your PowerSync Service or run `powersync docker reset` if running locally with Docker), then run: + Apply your config changes (e.g. restart your PowerSync Service or run `powersync docker reset` if running locally with Docker), then run: ```bash powersync generate token --subject=test-user From e702f4363fbd515ab376dcb971f9108bb1ca4973 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Mon, 2 Mar 2026 13:52:44 +0200 Subject: [PATCH 15/20] Polish --- tools/cli.mdx | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/tools/cli.mdx b/tools/cli.mdx index 35a0a96f..09ca1c11 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -1,13 +1,13 @@ --- title: "CLI" -description: "Manage PowerSync Cloud and self-hosted instances from the command line with config-as-code." +description: "Manage PowerSync Cloud and self-hosted instances from the command line." --- The PowerSync CLI lets you manage PowerSync Service instances, deploy sync config (your Sync Streams or Sync Rules), generate client schemas, run diagnostics, and more. It is distributed as the [powersync](https://www.npmjs.com/package/powersync) npm package. **Cloud:** Full support for PowerSync Cloud. Log in with a personal access token, then define your instance config in a `powersync/` directory (`service.yaml`, `sync-config.yaml`) in your project and deploy with `powersync deploy`. -**Self-hosted:** You can link to an existing PowerSync Service instance and run a subset of commands (e.g. `powersync status`, `powersync generate schema`, `powersync validate`). The CLI does not provision or deploy to a remote server; for development, you can use **Docker** to run a local PowerSync Service (and optional DB/storage) on your machine. +**Self-hosted:** You can link to an existing PowerSync Service instance and run a subset of commands (e.g. `powersync status`, `powersync generate schema`, `powersync validate`). The CLI does not provision or deploy to a remote server; for development, you can use **Docker** to bootstrap a new self-hosted project and run a local PowerSync Service (and optional DB/storage) on your machine. For a full step-by-step flow using the CLI, use the [Setup Guide](/intro/setup-guide): choose the **CLI (Cloud)** or **CLI (Self-Hosted)** tab in steps 2–5 to configure your instance, connect the source database, deploy sync config, and generate development tokens. @@ -16,8 +16,11 @@ The PowerSync CLI lets you manage PowerSync Service instances, deploy sync confi The PowerSync CLI was overhauled in version TODO. The redesign is based on this [design proposal](https://docs.google.com/document/d/1iqpJF2gog2jB-ZWeN8TBEjcad8aBKNKbue2yJ21q_-s/edit). - Main improvements: **self-hosted support** (link to your own PowerSync Service and run commands such as fetch status, generate schema, validate); **open source**; and **improved DX**, including validated config files (`service.yaml`, `sync-config.yaml`) used for creating and deploying changes to PowerSync instances instead of long command-line flags. - + **Main improvements:** + - **Self-hosted support** — Link to your own PowerSync Service and run commands (e.g. `powersync status`, `powersync generate schema`, `powersync validate`). Use `powersync docker configure` to bootstrap a local dev setup. + - **Config in files** — Define instance and sync config in `service.yaml` and `sync-config.yaml` in your project. Version in git, run `powersync validate`, then `powersync deploy` instead of long command-line flags. + - **Open source** — CLI source and advanced docs are in the [PowerSync CLI repository](https://github.com/powersync-ja/powersync-cli). + See [Migrating from the previous CLI](#migrating-from-the-previous-cli) if you used the older flow. @@ -30,7 +33,7 @@ npm install -g powersync ``` ```bash -npx powersync --version +npx powersync@0.9.0 # or latest version ``` ## Authentication (Cloud) @@ -54,9 +57,9 @@ powersync fetch instances --project-id= To clear stored credentials: `powersync logout`. -## Config-as-code +## Config files -The CLI uses a **config directory** (default `powersync/`) that holds: +Define your instance and sync config in YAML files so you can version them in git, review changes before deploying, and run `powersync validate` before `powersync deploy`. The CLI uses a **config directory** (default `powersync/`) that holds: | File | Purpose | |------|---------| From 135908752093ba4e10c0d4869580f24375bb4346 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Mon, 2 Mar 2026 14:34:39 +0200 Subject: [PATCH 16/20] Polish --- tools/cli.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tools/cli.mdx b/tools/cli.mdx index 09ca1c11..1a5bb037 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -195,11 +195,11 @@ More information is available in the [PowerSync CLI repository](https://github.c | [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. | | [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). | -## Known limitations +## Known issues and limitations -* Certificates cannot be managed from the CLI. -* When secure storage is unavailable, `powersync login` may store the token in a plaintext config file after explicit confirmation. -* Self-hosted: the CLI does not create or manage instances on your server, or deploy config to it; it only links to an existing API and runs a subset of commands (status, generate schema/token, validate). The sole exception is **Docker**: it starts a local PowerSync Service (and optional DB/storage) in containers on your machine for development — not a remote or production instance. +- When secure storage is unavailable, `powersync login` may store the token in a plaintext config file after explicit confirmation. +- Self-hosted: the CLI does not create or manage instances on your server, or deploy config to it; it only links to an existing API and runs a subset of commands (status, generate schema/token, validate). The sole exception is **Docker**: it starts a local PowerSync Service (and optional DB/storage) in containers on your machine for development — not a remote or production instance. +-Some validation checks require a connected instance to complete successfully; validation of an unprovisioned instance may show errors that resolve after the first deployment. ## Reference From 423376e5c5d7050ba30a6f4d74a457a1700409b9 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Tue, 3 Mar 2026 17:55:36 +0200 Subject: [PATCH 17/20] typo --- intro/setup-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index de0eb35d..b915ece1 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -583,7 +583,7 @@ PowerSync uses either **Sync Streams** (or legacy **Sync Rules**) to control whi In the [PowerSync Dashboard](https://dashboard.powersync.com/): 1. Select your project and instance - 2. Go to the **Sync Rules** view + 2. Go to the **Sync Streams** or **Sync Rules** view (depending on which you’re using) 3. Edit the YAML directly in the dashboard 4. Click **Deploy** to validate and deploy your Sync Rules From 424be650dacee37b94a0503fb2fd409c3205ddf6 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 4 Mar 2026 11:41:46 +0200 Subject: [PATCH 18/20] links --- tools/cli.mdx | 12 ++++++------ tools/local-development.mdx | 1 + 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/tools/cli.mdx b/tools/cli.mdx index 1a5bb037..dd7d7202 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -14,12 +14,12 @@ The PowerSync CLI lets you manage PowerSync Service instances, deploy sync confi - The PowerSync CLI was overhauled in version TODO. The redesign is based on this [design proposal](https://docs.google.com/document/d/1iqpJF2gog2jB-ZWeN8TBEjcad8aBKNKbue2yJ21q_-s/edit). + The PowerSync CLI was overhauled in version 0.9.0. The redesign is based on this [design proposal](https://docs.google.com/document/d/1iqpJF2gog2jB-ZWeN8TBEjcad8aBKNKbue2yJ21q_-s/edit). **Main improvements:** - **Self-hosted support** — Link to your own PowerSync Service and run commands (e.g. `powersync status`, `powersync generate schema`, `powersync validate`). Use `powersync docker configure` to bootstrap a local dev setup. - **Config in files** — Define instance and sync config in `service.yaml` and `sync-config.yaml` in your project. Version in git, run `powersync validate`, then `powersync deploy` instead of long command-line flags. - - **Open source** — CLI source and advanced docs are in the [PowerSync CLI repository](https://github.com/powersync-ja/powersync-cli). + - **Open source** — CLI source code and advanced docs are in the public [PowerSync CLI repository](https://github.com/powersync-ja/powersync-cli). See [Migrating from the previous CLI](#migrating-from-the-previous-cli) if you used the older flow. @@ -184,9 +184,9 @@ If you used the older PowerSync CLI (e.g. `npx powersync init` to set token and **Summary:** Authenticate with **`powersync login`** (or `PS_ADMIN_TOKEN` in CI). Use a **config directory** with `service.yaml` and `sync-config.yaml` as the source of truth. **Link** with **`powersync link cloud`** or **`powersync pull instance`**, then run **`powersync deploy`** or **`powersync deploy sync-config`**. No more setting “current instance” separately from config—the directory and `cli.yaml` define the target. -## Additional documentation (CLI Repository) +## Additional documentation (CLI repository) -More information is available in the [PowerSync CLI repository](https://github.com/powersync-ja/powersync-cli). +More information is available in the public [PowerSync CLI repository](https://github.com/powersync-ja/powersync-cli). | Resource | Description | |----------|-------------| @@ -222,10 +222,10 @@ More information is available in the [PowerSync CLI repository](https://github.c - CLI repository: usage docs, Docker usage, examples + Source code, usage docs, Docker usage, and examples diff --git a/tools/local-development.mdx b/tools/local-development.mdx index 9acf44c3..1b349b6f 100644 --- a/tools/local-development.mdx +++ b/tools/local-development.mdx @@ -155,6 +155,7 @@ docker compose up ## Resources +- [PowerSync CLI](https://github.com/powersync-ja/powersync-cli) — open source CLI; use it to scaffold and run a Docker-based local stack - [self-host-demo](https://github.com/powersync-ja/self-host-demo) — complete working examples with Docker Compose - [Self-Hosted Instance Configuration](/configuration/powersync-service/self-hosted-instances) — full `service.yaml` reference - [Sync Streams](/sync/streams/overview) — sync config syntax From e542f2e3bcee493d834bf8fc4de5267af9bdb47d Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 4 Mar 2026 14:14:35 +0200 Subject: [PATCH 19/20] PR feedback --- configuration/source-db/setup.mdx | 2 +- intro/setup-guide.mdx | 19 ++++++++++++------- tools/cli.mdx | 11 +++++------ 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/configuration/source-db/setup.mdx b/configuration/source-db/setup.mdx index a24be61f..0bf8b080 100644 --- a/configuration/source-db/setup.mdx +++ b/configuration/source-db/setup.mdx @@ -615,7 +615,7 @@ Due to the fundamental differences in how CDC works compared to logical replicat 2. **Polling Interval**: The frequency at which PowerSync polls the CDC change tables for changes. The default value is once every 1000ms. This can be changed by setting the `pollingIntervalMs` parameter in the PowerSync configuration. -Configuration parameters for SQL Server like `pollingIntervalMs` and `pollingBatchSize` (see below) can currently only be [set when self-hosting](/intro/self-hosting) PowerSync. We are working on exposing these settings for SQL Server source database connections in the PowerSync Dashboard for PowerSync Cloud instances. +Configuration parameters for SQL Server like `pollingIntervalMs` and `pollingBatchSize` (see below) can currently only be set when self-hosting PowerSync (e.g. via your config file or the [PowerSync CLI](/tools/cli)). We are working on exposing these settings in the PowerSync Dashboard for PowerSync Cloud instances. ### Memory Management diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index b915ece1..7eceeb17 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -21,7 +21,7 @@ import DevTokenSelfHostedSteps from '/snippets/dev-token-self-hosted-steps.mdx'; PowerSync needs to connect to your source database (Postgres, MongoDB, MySQL or SQL Server) to replicate data. Before setting up PowerSync, you need to configure your database with the appropriate permissions and replication settings. -Using the [PowerSync CLI](/tools/cli) and want a managed Postgres instance? You can skip to [Step 2](#2-set-up-powersync-service-instance) and set one up automatically with the **CLI (Self-Hosted)** tab. +Using the [PowerSync CLI](/tools/cli) and want an automatically integrated Postgres instance for local development? You can skip to [Step 2](#2-set-up-powersync-service-instance) and set one up with the **CLI (Self-Hosted)** tab. @@ -211,7 +211,7 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel - Recommended for getting started: the CLI scaffolds your config directory and generates the Docker Compose stack (including a managed Postgres instance) so you can run PowerSync locally with minimal setup. For custom setups use the **Manual (Self-Hosted)** tab. Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm), then run: + Recommended for getting started: the CLI scaffolds your config directory and generates the Docker Compose stack (including a Postgres instance for the source database and storage) so you can run PowerSync locally with minimal setup. For custom setups use the **Manual (Self-Hosted)** tab. Install the [PowerSync CLI](/tools/cli) (requires Node.js/npm); alternative installation options (e.g. installers via GitHub releases) will be available in the near future. Then run: ```bash npm install -g powersync @@ -234,6 +234,8 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel You'll update this with your actual tables/collections in a later step. + The Docker Postgres instance runs init scripts only on first start. Create your specific tables before running `powersync docker start` for the first time. + Then start the PowerSync Service: ```bash @@ -303,12 +305,15 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel uri: postgresql://powersync_storage_user:my_secure_user_password@powersync-postgres-storage:5432/powersync_storage sslmode: disable # Use 'disable' only for local/private networks - # Sync Rules (defined in a later step) - sync_rules: + # Sync Streams config (defined in a later step) + sync_config: content: | - bucket_definitions: - global: - data: + config: + edition: 3 + streams: + shared_data: + auto_subscribe: true + queries: - SELECT * FROM lists - SELECT * FROM todos ``` diff --git a/tools/cli.mdx b/tools/cli.mdx index dd7d7202..6e35782c 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -33,7 +33,7 @@ npm install -g powersync ``` ```bash -npx powersync@0.9.0 # or latest version +npx powersync@0.9.0 # 0.9.0 is the first version with the new CLI ``` ## Authentication (Cloud) @@ -51,7 +51,7 @@ You can open a browser to [create a token in the PowerSync Dashboard](https://da **CI and scripts:** Set the `PS_ADMIN_TOKEN` environment variable. The CLI uses `PS_ADMIN_TOKEN` when set; otherwise it uses the token from `powersync login`. ```bash -export TOKEN=your-personal-access-token +export PS_ADMIN_TOKEN=your-personal-access-token powersync fetch instances --project-id= ``` @@ -113,9 +113,9 @@ You can run commands (e.g. `powersync generate schema`, `powersync generate toke ## Self-hosted workflows -Run **`powersync init self-hosted`** to scaffold a config directory. Edit `service.yaml` with your instance details and use **`powersync link self-hosted --api-url `** to link to an existing running PowerSync Service. The CLI does not create or deploy to self-hosted instances; you manage the server and its config yourself. +Run **`powersync init self-hosted`** to scaffold a config directory. Edit `service.yaml` with your instance details and use **`powersync link self-hosted --api-url `** to link to an existing running PowerSync Service. When using Docker (see below), **`powersync docker configure`** links to the local API automatically. The CLI does not create or deploy to self-hosted instances; you manage the server and its config yourself. -Supported self-hosted commands include: `powersync status`, `powersync generate schema`, `powersync generate token`, `powersync validate`. Cloud-only commands (`powersync deploy`, `powersync pull instance`, `powersync fetch instances`, etc.) do not apply. +Supported self-hosted commands include: `powersync status`, `powersync generate schema`, `powersync generate token`, `powersync validate`, and `powersync fetch instances` (scans the current directory for folders containing `cli.yaml` and prints resolved link information). Cloud-only commands (`powersync deploy`, `powersync pull instance`, etc.) do not apply. ### Docker (local development) @@ -127,7 +127,7 @@ powersync docker configure powersync docker start ``` -After `powersync docker start`, link to the local API (e.g. `powersync link self-hosted --api-url http://localhost:8080`) and use the same commands as for any self-hosted instance (`powersync status`, `powersync generate schema`, etc.). Use **`powersync docker reset`** when you need a clean state (stop and remove, then start). For the full workflow, flags (`--database`, `--storage`, `--remove`, `--remove-volumes`), and how the Docker setup uses templates and init scripts, see the [Docker usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) in the PowerSync CLI repository. You can also run `powersync docker --help` for command options. +**`powersync docker configure`** links to the local API automatically. After `powersync docker start`, use the same commands as for any self-hosted instance (`powersync status`, `powersync generate schema`, etc.). Use **`powersync docker reset`** when you need a clean state (stop and remove, then start). For the full workflow, flags (`--database`, `--storage`, `--remove`, `--remove-volumes`), and how the Docker setup uses templates and init scripts, see the [Docker usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) in the PowerSync CLI repository. You can also run `powersync docker --help` for command options. ## Common commands @@ -166,7 +166,6 @@ You can automate sync config (and full config) deployments using the CLI in CI. Example: deploy sync config on push to main -The demo shows how to configure repository secrets and run the CLI in a workflow. With the new CLI, you typically use a `powersync/` directory in the repo and run `powersync deploy` or `powersync deploy sync-config` with `PS_ADMIN_TOKEN` (and optionally `INSTANCE_ID`, `PROJECT_ID`, `ORG_ID`) set in the environment. ## Migrating from the previous CLI From 5810f684169d9028c72aa9e615105b528bcf8f64 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Wed, 4 Mar 2026 15:06:48 +0200 Subject: [PATCH 20/20] Polish --- intro/setup-guide.mdx | 2 +- tools/cli.mdx | 56 +++++++++++++++++++++++++++++++------------ 2 files changed, 42 insertions(+), 16 deletions(-) diff --git a/intro/setup-guide.mdx b/intro/setup-guide.mdx index 7eceeb17..a08ec8db 100644 --- a/intro/setup-guide.mdx +++ b/intro/setup-guide.mdx @@ -234,7 +234,7 @@ PowerSync is available as a cloud-hosted service (PowerSync Cloud) or can be sel You'll update this with your actual tables/collections in a later step. - The Docker Postgres instance runs init scripts only on first start. Create your specific tables before running `powersync docker start` for the first time. + The Docker Postgres instance runs init scripts only on first start. Create your specific tables before running `powersync docker start` for the first time. See the [Docker usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) in the PowerSync CLI repository for more details. Then start the PowerSync Service: diff --git a/tools/cli.mdx b/tools/cli.mdx index 6e35782c..759fd81b 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -5,6 +5,10 @@ description: "Manage PowerSync Cloud and self-hosted instances from the command The PowerSync CLI lets you manage PowerSync Service instances, deploy sync config (your Sync Streams or Sync Rules), generate client schemas, run diagnostics, and more. It is distributed as the [powersync](https://www.npmjs.com/package/powersync) npm package. + + The CLI is currently in [beta](/resources/feature-status). We recommend it for new and existing projects; the 0.9.0+ design is the supported path going forward. + + **Cloud:** Full support for PowerSync Cloud. Log in with a personal access token, then define your instance config in a `powersync/` directory (`service.yaml`, `sync-config.yaml`) in your project and deploy with `powersync deploy`. **Self-hosted:** You can link to an existing PowerSync Service instance and run a subset of commands (e.g. `powersync status`, `powersync generate schema`, `powersync validate`). The CLI does not provision or deploy to a remote server; for development, you can use **Docker** to bootstrap a new self-hosted project and run a local PowerSync Service (and optional DB/storage) on your machine. @@ -17,9 +21,13 @@ The PowerSync CLI lets you manage PowerSync Service instances, deploy sync confi The PowerSync CLI was overhauled in version 0.9.0. The redesign is based on this [design proposal](https://docs.google.com/document/d/1iqpJF2gog2jB-ZWeN8TBEjcad8aBKNKbue2yJ21q_-s/edit). **Main improvements:** - - **Self-hosted support** — Link to your own PowerSync Service and run commands (e.g. `powersync status`, `powersync generate schema`, `powersync validate`). Use `powersync docker configure` to bootstrap a local dev setup. - - **Config in files** — Define instance and sync config in `service.yaml` and `sync-config.yaml` in your project. Version in git, run `powersync validate`, then `powersync deploy` instead of long command-line flags. - - **Open source** — CLI source code and advanced docs are in the public [PowerSync CLI repository](https://github.com/powersync-ja/powersync-cli). + - **Project-based config** — A `powersync/` directory in your repo holds `service.yaml` and `sync-config.yaml`, so you version and review config with your app code. + - **Self-hosted support** — Most commands work against any linked instance, PowerSyncCloud and self-hosted. You can also use `powersync docker configure` to scaffold a local PowerSync stack with no manual setup. + - **Better validation** — `powersync validate` checks your config before deploy and reports errors with line and column numbers. + - **Config Studio** — `powersync edit config` opens a built-in editor with schema validation, autocomplete, inline errors, and more. See the [Config Studio README](https://github.com/powersync-ja/powersync-cli/tree/main/packages/editor). + - **Browser login** — `powersync login` opens a browser to create or paste a PAT and stores it; in CI use `PS_ADMIN_TOKEN`. + - **Plugins** — npm-based plugin system ([OCLIF](https://oclif.io)); install with `powersync plugins install ` or build with `@powersync/cli-core`. + - **Open source** — Source and advanced docs are in the [PowerSync CLI repo](https://github.com/powersync-ja/powersync-cli). See [Migrating from the previous CLI](#migrating-from-the-previous-cli) if you used the older flow. @@ -69,7 +77,11 @@ Define your instance and sync config in YAML files so you can version them in gi All YAML files support the **`!env`** custom tag for secrets and environment-specific values, e.g. `uri: !env PS_DATABASE_URI`. Use `!env VAR::number` or `!env VAR::boolean` for typed substitution. For using one config directory across multiple instances (e.g. dev/staging/prod) via `!env` in `cli.yaml`, see the [CLI usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#configuring-multiple-instances-eg-dev-staging-production). -Edit these files in your IDE, then run `powersync validate` and `powersync deploy`. +Edit these files in your IDE, then run `powersync validate` and `powersync deploy`. For better IDE support (YAML schema validation, `!env` custom tag, autocomplete), run **`powersync configure ide`**. Alternatively, use **Config Studio**: run **`powersync edit config`** to open a built-in web editor that edits `service.yaml` and `sync-config.yaml` with schema-aware validation, autocomplete, and inline sync config errors. The editor writes changes back to your config directory. See the [Config Studio README](https://github.com/powersync-ja/powersync-cli/tree/main/packages/editor) for details. + + + **Cloud secrets:** For Cloud `service.yaml`, use `password: secret: !env VAR` to supply the value from an environment variable at deploy time. After the first deploy you can switch to `secret_ref: default_password` to reuse the stored secret without re-supplying it. See the [CLI README](https://github.com/powersync-ja/powersync-cli#cloud-secrets-format-serviceyaml) for details. + ## Cloud workflows @@ -113,9 +125,9 @@ You can run commands (e.g. `powersync generate schema`, `powersync generate toke ## Self-hosted workflows -Run **`powersync init self-hosted`** to scaffold a config directory. Edit `service.yaml` with your instance details and use **`powersync link self-hosted --api-url `** to link to an existing running PowerSync Service. When using Docker (see below), **`powersync docker configure`** links to the local API automatically. The CLI does not create or deploy to self-hosted instances; you manage the server and its config yourself. +Run **`powersync init self-hosted`** to scaffold a config directory. Edit `service.yaml` with your instance details (including `api.tokens` for API key auth) and use **`powersync link self-hosted --api-url `** to link to an existing running PowerSync Service. The link writes `cli.yaml`; set **`api_key`** in `cli.yaml` (e.g. `api_key: !env PS_ADMIN_TOKEN`) or set the **`PS_ADMIN_TOKEN`** environment variable so the CLI can authenticate. When using Docker (see below), **`powersync docker configure`** links to the local API automatically. The CLI does not create or deploy to self-hosted instances; you manage the server and its config yourself. -Supported self-hosted commands include: `powersync status`, `powersync generate schema`, `powersync generate token`, `powersync validate`, and `powersync fetch instances` (scans the current directory for folders containing `cli.yaml` and prints resolved link information). Cloud-only commands (`powersync deploy`, `powersync pull instance`, etc.) do not apply. +Supported self-hosted commands include: `powersync status`, `powersync generate schema`, `powersync generate token`, `powersync validate`, and `powersync fetch instances` (lists linked instances by scanning the current directory for folders with `cli.yaml`). Cloud-only commands (`powersync deploy`, `powersync pull instance`, `powersync fetch config`, `powersync destroy`, `powersync stop`, etc.) do not apply. ### Docker (local development) @@ -127,7 +139,7 @@ powersync docker configure powersync docker start ``` -**`powersync docker configure`** links to the local API automatically. After `powersync docker start`, use the same commands as for any self-hosted instance (`powersync status`, `powersync generate schema`, etc.). Use **`powersync docker reset`** when you need a clean state (stop and remove, then start). For the full workflow, flags (`--database`, `--storage`, `--remove`, `--remove-volumes`), and how the Docker setup uses templates and init scripts, see the [Docker usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) in the PowerSync CLI repository. You can also run `powersync docker --help` for command options. +**`powersync docker configure`** links to the local API automatically. After `powersync docker start`, use the same commands as for any self-hosted instance (`powersync status`, `powersync generate schema`, etc.). Use **`powersync docker stop`** to stop the stack (add `--remove` to remove containers, `--remove-volumes` to reset so init scripts run again on next start). Use **`powersync docker reset`** when you need a clean state (stop and remove, then start). For the full workflow, flags (`--database`, `--storage`, `--remove`, `--remove-volumes`), and how the Docker setup uses templates and init scripts, see the [Docker usage docs](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) in the PowerSync CLI repository. You can also run `powersync docker --help` for command options. ## Common commands @@ -137,17 +149,24 @@ powersync docker start | `powersync logout` | Remove stored token | | `powersync init cloud` | Scaffold Cloud config directory | | `powersync init self-hosted` | Scaffold self-hosted config directory | +| `powersync configure ide` | Configure IDE for YAML schema validation and `!env` support | | `powersync link cloud --project-id=` | Link to an existing Cloud instance | | `powersync link cloud --create --project-id=` | Create a new Cloud instance and link | +| `powersync link self-hosted --api-url=` | Link to a self-hosted instance by API URL | | `powersync pull instance --project-id= --instance-id=` | Download Cloud config into local files | -| `powersync deploy` | Deploy local config to linked Cloud instance | -| `powersync deploy sync-config` | Deploy only sync config | +| `powersync deploy` | Deploy full config to linked Cloud instance | +| `powersync deploy service-config` | Deploy only service config (no sync config) | +| `powersync deploy sync-config` | Deploy only sync config (optional `--sync-config-file-path`) | | `powersync validate` | Validate config and sync rules/streams | -| `powersync fetch instances` | List Cloud instances (optionally by project/org) | +| `powersync edit config` | Open Config Studio (Monaco editor for service.yaml and sync-config.yaml) | +| `powersync migrate sync-rules` | Migrate Sync Rules to Sync Streams | +| `powersync fetch instances` | List Cloud and linked instances (optionally by project/org) | | `powersync fetch config` | Print linked Cloud instance config (YAML/JSON) | -| `powersync status` | Instance diagnostics (connections, replication) | +| `powersync status` | Instance diagnostics (connections, replication); Cloud and self-hosted | | `powersync generate schema --output=ts --output-path=schema.ts` | Generate client-side schema | | `powersync generate token --subject=user-123` | Generate a development JWT | +| `powersync destroy --confirm=yes` | [Cloud only] Permanently destroy the linked instance | +| `powersync stop --confirm=yes` | [Cloud only] Stop the linked instance (restart with deploy) | For full usage and flags, run `powersync --help` or `powersync --help`. A complete [command reference](https://github.com/powersync-ja/powersync-cli/blob/main/cli/README.md#commands) is available in the PowerSync CLI repository; see also the [powersync npm package](https://www.npmjs.com/package/powersync). @@ -155,7 +174,7 @@ For full usage and flags, run `powersync --help` or `powersync --help` You can automate sync config (and full config) deployments using the CLI in CI. Use the config directory as the source of truth: keep `service.yaml` and `sync-config.yaml` in the repo (with secrets via `!env` and CI secrets), then run `powersync deploy` (or `powersync deploy sync-config`). -**Secrets:** Set `PS_ADMIN_TOKEN` to your PowerSync personal access token. If the workflow does not use a linked directory, also set `INSTANCE_ID` and `PROJECT_ID` (and `ORG_ID` only if your token has multiple organizations). +**Secrets:** Set `PS_ADMIN_TOKEN` to your PowerSync personal access token. If the workflow does not use a linked directory, also set `INSTANCE_ID` and `PROJECT_ID` (and `ORG_ID` only if your token has multiple organizations). For self-hosted, `API_URL` can specify the PowerSync API base URL.