From 5e13c59d1c2b8cea6c963e0c4b8670b9d61b309f Mon Sep 17 00:00:00 2001 From: LucDeCaf Date: Wed, 27 May 2026 15:12:23 +0200 Subject: [PATCH 1/4] Remove projectId and orgId references --- tools/cli.mdx | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/tools/cli.mdx b/tools/cli.mdx index a97cc1b6..da07a1d9 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -84,6 +84,7 @@ The CLI uses a config directory (default `powersync/`) with YAML files: | `cli.yaml` | Link file (written by `powersync link`); ties this directory to an instance | ### Developer Notes +* `cli.yaml` records the instance ID along with the organization and project IDs. The CLI normally writes all three for you. The organization and project IDs act as a cache: when both are present, the CLI uses them directly instead of looking them up from the instance, saving an API request. If they are missing, the CLI resolves them automatically from the instance ID. If they are present but incorrect for the instance, the CLI reports an error rather than overriding them. * Use the **`!env`** tag for secrets, e.g. `uri: !env PS_DATABASE_URI` (or `!env VAR::number` / `!env VAR::boolean` for types). * Edit files in your IDE, then run `powersync validate` and `powersync deploy`. For schema validation and `!env` support in your editor, run **`powersync configure ide`**; or run **`powersync edit config`** to open Config Studio (built-in web-based editor). * To use one config directory across multiple instances (e.g. dev, staging, prod), see the CLI usage docs on [configuring multiple instances](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#configuring-multiple-instances-eg-dev-staging-production). @@ -127,17 +128,19 @@ Pull config from an instance that already exists (e.g. created in the Dashboard) ```bash powersync login -powersync pull instance --project-id= --instance-id= +powersync pull instance --instance-id= ``` +The instance ID identifies the target on its own. The CLI looks up the organization and project from it, so `--org-id` and `--project-id` are not needed. + Then edit `service.yaml` and `sync-config.yaml` as needed, run `powersync validate`, and `powersync deploy`. Run `powersync pull instance` again (no IDs if already linked) to refresh from the cloud. ### Run Commands Without Local Config To run commands (e.g. `powersync generate schema`, `powersync status`) against an instance managed elsewhere (e.g. Dashboard): -- **Link once:** `powersync link cloud --instance-id= --project-id=` (writes `cli.yaml`); later commands use that instance. -- **Or pass each time:** `--instance-id`, `--project-id`, and `--org-id` when the token has multiple orgs. Or set `INSTANCE_ID`, `PROJECT_ID`, `ORG_ID` in the environment. +- **Link once:** `powersync link cloud --instance-id=` (writes `cli.yaml`); later commands use that instance. +- **Or pass each time:** `--instance-id`, or set `INSTANCE_ID` in the environment. The instance ID is all the CLI needs to identify the organization and project. The CLI resolves instance and linking context in a fixed order: flags take precedence, then environment variables, then values in `cli.yaml`. For the full resolution order and how to set up multiple instances (e.g. dev, staging, prod), see [supplying linking information for Cloud and self-hosted commands](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#supplying-linking-information-for-cloud-and-self-hosted-commands) in the CLI usage docs. @@ -219,10 +222,10 @@ Then use the same commands as any self-hosted instance (`powersync status`, `pow | `powersync init cloud` | Scaffold Cloud config directory | | `powersync init self-hosted` | Scaffold self-hosted config directory | | `powersync configure ide` | IDE: YAML schema validation and `!env` support | -| `powersync link cloud --project-id=` | Link to existing Cloud instance | +| `powersync link cloud --instance-id=` | Link to existing Cloud instance | | `powersync link cloud --create --project-id=` | Create new Cloud instance and link | | `powersync link self-hosted --api-url=` | Link to self-hosted instance | -| `powersync pull instance --project-id= --instance-id=` | Download Cloud config to local files | +| `powersync pull instance --instance-id=` | Download Cloud config to local files | | `powersync deploy` | Deploy full config to linked Cloud instance | | `powersync deploy service-config` | [Cloud] Deploy only service config | | `powersync deploy sync-config` | [Cloud] Deploy only sync config | @@ -244,7 +247,7 @@ Run `powersync --help` or `powersync --help` for flags. Full [command 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). For self-hosted, `API_URL` can specify the PowerSync API base URL. +**Secrets:** Set `PS_ADMIN_TOKEN` to your PowerSync personal access token. If the workflow does not use a linked directory, also set `INSTANCE_ID`. The CLI determines the organization and project from the instance. For self-hosted, `API_URL` can specify the PowerSync API base URL. ` | **`powersync link cloud --instance-id= --project-id=`** (writes `cli.yaml` in config directory). Or use `--directory` for a specific folder. | +| `npx powersync init` (enter token, org, project) | **`powersync login`** (token only). Then **`powersync init cloud`** to scaffold config, or **`powersync pull instance --instance-id=...`** to pull an existing instance. | +| `powersync instance set --instanceId=` | **`powersync link cloud --instance-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-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 Streams/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: **`PS_ADMIN_TOKEN`**, **`INSTANCE_ID`**, **`PROJECT_ID`**, **`ORG_ID`** (optional). | +| Org/project stored by init | No longer needed separately. The CLI determines the organization and project from the instance ID. For CI, set **`PS_ADMIN_TOKEN`** and **`INSTANCE_ID`**. | **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. From 6cc6fa2c94506ac93d3abd3461191cb918816b68 Mon Sep 17 00:00:00 2001 From: LucDeCaf Date: Tue, 9 Jun 2026 10:16:19 +0200 Subject: [PATCH 2/4] Remove more references to project/org id --- tools/cli.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/tools/cli.mdx b/tools/cli.mdx index 5fec41dd..6c909a8d 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -131,8 +131,6 @@ powersync login powersync pull instance --instance-id= ``` -The instance ID identifies the target on its own. The CLI looks up the organization and project from it, so `--org-id` and `--project-id` are not needed. - Then edit `service.yaml` and `sync-config.yaml` as needed, run `powersync validate`, and `powersync deploy`. Run `powersync pull instance` again (no IDs if already linked) to refresh from the cloud. ### Run Commands Without Local Config @@ -140,7 +138,7 @@ Then edit `service.yaml` and `sync-config.yaml` as needed, run `powersync valida To run commands (e.g. `powersync generate schema`, `powersync status`) against an instance managed elsewhere (e.g. Dashboard): - **Link once:** `powersync link cloud --instance-id=` (writes `cli.yaml`); later commands use that instance. -- **Or pass each time:** `--instance-id`, or set `INSTANCE_ID` in the environment. The instance ID is all the CLI needs to identify the organization and project. +- **Or pass each time:** `--instance-id`, or set `INSTANCE_ID` in the environment. The CLI resolves instance and linking context in a fixed order: flags take precedence, then environment variables, then values in `cli.yaml`. For the full resolution order and how to set up multiple instances (e.g. dev, staging, prod), see [supplying linking information for Cloud and self-hosted commands](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#supplying-linking-information-for-cloud-and-self-hosted-commands) in the CLI usage docs. @@ -248,7 +246,7 @@ Run `powersync --help` or `powersync --help` for flags. Full [command 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`. The CLI determines the organization and project from the instance. For self-hosted, `API_URL` can specify the PowerSync API base URL. +**Secrets:** Set `PS_ADMIN_TOKEN` to your PowerSync personal access token. If the workflow does not use a linked directory, also set `INSTANCE_ID`. For self-hosted, `API_URL` can specify the PowerSync API base URL. Date: Tue, 9 Jun 2026 10:21:46 +0200 Subject: [PATCH 3/4] Better wording --- tools/cli.mdx | 147 +++++++++++++++++++++++++++++--------------------- 1 file changed, 86 insertions(+), 61 deletions(-) diff --git a/tools/cli.mdx b/tools/cli.mdx index 6c909a8d..d92b4a9b 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -4,13 +4,25 @@ description: "Manage PowerSync Cloud and self-hosted instances from the command --- - + Install globally or run via npx - + PowerSync CLI repo on GitHub - + Changelog for the CLI @@ -18,11 +30,15 @@ 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 CLI is currently in [beta](/resources/feature-status). We recommend it for + new and existing projects. - 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. + 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 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). @@ -38,6 +54,7 @@ The CLI was overhauled in version 0.9.0. The redesign is based on this [design p - **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. + ## Installation @@ -77,18 +94,19 @@ To clear stored credentials: `powersync logout`. The CLI uses a config directory (default `powersync/`) with YAML files: -| File | Purpose | -|------|---------| -| `service.yaml` | Instance configuration: name, region, replication connection, client auth | -| `sync-config.yaml` | Sync Streams (or Sync Rules) | -| `cli.yaml` | Link file (written by `powersync link`); ties this directory to an instance | +| File | Purpose | +| ------------------ | --------------------------------------------------------------------------- | +| `service.yaml` | Instance configuration: name, region, replication connection, client auth | +| `sync-config.yaml` | Sync Streams (or Sync Rules) | +| `cli.yaml` | Link file (written by `powersync link`); ties this directory to an instance | ### Developer Notes -* `cli.yaml` records the instance ID along with the organization and project IDs. The CLI normally writes all three for you. The organization and project IDs act as a cache: when both are present, the CLI uses them directly instead of looking them up from the instance, saving an API request. If they are missing, the CLI resolves them automatically from the instance ID. If they are present but incorrect for the instance, the CLI reports an error rather than overriding them. -* Use the **`!env`** tag for secrets, e.g. `uri: !env PS_DATABASE_URI` (or `!env VAR::number` / `!env VAR::boolean` for types). -* Edit files in your IDE, then run `powersync validate` and `powersync deploy`. For schema validation and `!env` support in your editor, run **`powersync configure ide`**; or run **`powersync edit config`** to open Config Studio (built-in web-based editor). -* To use one config directory across multiple instances (e.g. dev, staging, prod), see the CLI usage docs on [configuring multiple instances](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#configuring-multiple-instances-eg-dev-staging-production). -* For Cloud secrets in `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. [Details](https://github.com/powersync-ja/powersync-cli#cloud-secrets-format-serviceyaml) + +- `cli.yaml` records the instance ID along with the organization and project IDs. The CLI normally writes all three for you. The organization and project IDs act as a cache: when both are present, the CLI uses them directly instead of looking them up from the instance, saving an API request. If they are missing, the CLI resolves them automatically from the instance ID. If they are present but incorrect for the instance, the CLI reports an error rather than overriding them. +- Use the **`!env`** tag for secrets, e.g. `uri: !env PS_DATABASE_URI` (or `!env VAR::number` / `!env VAR::boolean` for types). +- Edit files in your IDE, then run `powersync validate` and `powersync deploy`. For schema validation and `!env` support in your editor, run **`powersync configure ide`**; or run **`powersync edit config`** to open Config Studio (built-in web-based editor). +- To use one config directory across multiple instances (e.g. dev, staging, prod), see the CLI usage docs on [configuring multiple instances](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#configuring-multiple-instances-eg-dev-staging-production). +- For Cloud secrets in `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. [Details](https://github.com/powersync-ja/powersync-cli#cloud-secrets-format-serviceyaml) ## Cloud Workflows @@ -141,7 +159,12 @@ To run commands (e.g. `powersync generate schema`, `powersync status`) against a - **Or pass each time:** `--instance-id`, or set `INSTANCE_ID` in the environment. - The CLI resolves instance and linking context in a fixed order: flags take precedence, then environment variables, then values in `cli.yaml`. For the full resolution order and how to set up multiple instances (e.g. dev, staging, prod), see [supplying linking information for Cloud and self-hosted commands](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#supplying-linking-information-for-cloud-and-self-hosted-commands) in the CLI usage docs. + The CLI resolves instance and linking context in a fixed order: flags take + precedence, then environment variables, then values in `cli.yaml`. For the + full resolution order and how to set up multiple instances (e.g. dev, staging, + prod), see [supplying linking information for Cloud and self-hosted + commands](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#supplying-linking-information-for-cloud-and-self-hosted-commands) + in the CLI usage docs. ## Self-Hosted Workflows @@ -191,7 +214,7 @@ Use `--directory=` for a different config folder. ### Supported Commands (Self-Hosted) -Only these commands apply to self-hosted instances: **`powersync status`**, **`powersync generate schema`**, **`powersync generate token`**, **`powersync validate`**, **`powersync fetch instances`** (scans current directory for folders with `cli.yaml`). +Only these commands apply to self-hosted instances: **`powersync status`**, **`powersync generate schema`**, **`powersync generate token`**, **`powersync validate`**, **`powersync fetch instances`** (scans current directory for folders with `cli.yaml`). Cloud-only commands (**`powersync deploy`**, **`powersync pull instance`**, **`powersync fetch config`**, **`powersync destroy`**, **`powersync stop`**, **`powersync compact`**) do not apply. @@ -208,37 +231,40 @@ powersync docker start Then use the same commands as any self-hosted instance (`powersync status`, `powersync generate schema`, etc.). To stop: **`powersync docker stop`** (add `--remove` to remove containers, `--remove-volumes` to reset so init scripts run again). For a clean setup: **`powersync docker reset`** (stop and remove, then start). - For the full Docker workflow, all flags (`--database`, `--storage`, `--remove`, `--remove-volumes`), and how the template layout and init scripts work, see [Docker usage](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) in the CLI repo. Run `powersync docker --help` for command options. + For the full Docker workflow, all flags (`--database`, `--storage`, + `--remove`, `--remove-volumes`), and how the template layout and init scripts + work, see [Docker + usage](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) + in the CLI repo. Run `powersync docker --help` for command options. ## Common Commands -| Command | Description | -|---------|-------------| -| `powersync login` | Store PAT for Cloud (interactive or paste token); use `PS_ADMIN_TOKEN` in CI | -| `powersync logout` | Remove stored token | -| `powersync init cloud` | Scaffold Cloud config directory | -| `powersync init self-hosted` | Scaffold self-hosted config directory | -| `powersync configure ide` | IDE: YAML schema validation and `!env` support | -| `powersync link cloud --instance-id=` | Link to existing Cloud instance | -| `powersync link cloud --create --project-id=` | Create new Cloud instance and link | -| `powersync link self-hosted --api-url=` | Link to self-hosted instance | -| `powersync pull instance --instance-id=` | Download Cloud config to local files | -| `powersync deploy` | Deploy full config to linked Cloud instance | -| `powersync deploy service-config` | [Cloud] Deploy only service config | -| `powersync deploy sync-config` | [Cloud] Deploy only sync config | -| `powersync validate` | Validate config and Sync Streams/Rules | -| `powersync edit config` | Open Config Studio (Monaco editor) | -| `powersync status` | Instance diagnostics (Cloud and self-hosted) | -| `powersync generate schema --output=ts --output-path=schema.ts` | Generate client schema | -| `powersync generate token --subject=user-123` | Generate development JWT | -| `powersync fetch instances` | List Cloud and linked instances | -| `powersync fetch config` | [Cloud] Print instance config (YAML/JSON) | -| `powersync migrate sync-rules` | Migrate Sync Rules to Sync Streams | -| `powersync destroy --confirm=yes` | [Cloud] Permanently destroy instance | -| `powersync stop --confirm=yes` | [Cloud] Stop instance (restart with deploy) | -| `powersync compact` | [Cloud] Trigger [bucket compacting](/maintenance-ops/compacting-buckets) on demand | - +| Command | Description | +| --------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| `powersync login` | Store PAT for Cloud (interactive or paste token); use `PS_ADMIN_TOKEN` in CI | +| `powersync logout` | Remove stored token | +| `powersync init cloud` | Scaffold Cloud config directory | +| `powersync init self-hosted` | Scaffold self-hosted config directory | +| `powersync configure ide` | IDE: YAML schema validation and `!env` support | +| `powersync link cloud --instance-id=` | Link to existing Cloud instance | +| `powersync link cloud --create --project-id=` | Create new Cloud instance and link | +| `powersync link self-hosted --api-url=` | Link to self-hosted instance | +| `powersync pull instance --instance-id=` | Download Cloud config to local files | +| `powersync deploy` | Deploy full config to linked Cloud instance | +| `powersync deploy service-config` | [Cloud] Deploy only service config | +| `powersync deploy sync-config` | [Cloud] Deploy only sync config | +| `powersync validate` | Validate config and Sync Streams/Rules | +| `powersync edit config` | Open Config Studio (Monaco editor) | +| `powersync status` | Instance diagnostics (Cloud and self-hosted) | +| `powersync generate schema --output=ts --output-path=schema.ts` | Generate client schema | +| `powersync generate token --subject=user-123` | Generate development JWT | +| `powersync fetch instances` | List Cloud and linked instances | +| `powersync fetch config` | [Cloud] Print instance config (YAML/JSON) | +| `powersync migrate sync-rules` | Migrate Sync Rules to Sync Streams | +| `powersync destroy --confirm=yes` | [Cloud] Permanently destroy instance | +| `powersync stop --confirm=yes` | [Cloud] Stop instance (restart with deploy) | +| `powersync compact` | [Cloud] Trigger [bucket compacting](/maintenance-ops/compacting-buckets) on demand | Run `powersync --help` or `powersync --help` for flags. Full [command reference](https://github.com/powersync-ja/powersync-cli/blob/main/cli/README.md#commands) in the CLI repo. @@ -257,7 +283,6 @@ You can automate sync config (and full config) deployments using the CLI in CI. Example: deploy sync config on push to main - ## 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. Version 0.9.0 and above are **not backwards compatible** with 0.8.0. If you are not ready to migrate, you can stay on the old CLI: @@ -268,15 +293,15 @@ npm install -g @powersync/cli@0.8.0 Otherwise, upgrade to the latest **powersync** npm package 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 --instance-id=...`** to pull an existing instance. | -| `powersync instance set --instanceId=` | **`powersync link cloud --instance-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-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 Streams/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 | No longer needed separately. The CLI determines the organization and project from the instance ID. For CI, set **`PS_ADMIN_TOKEN`** and **`INSTANCE_ID`**. | +| 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 --instance-id=...`** to pull an existing instance. | +| `powersync instance set --instanceId=` | **`powersync link cloud --instance-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-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 Streams/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 | Not required separately. The CLI determines the organization and project from the instance ID and caches their IDs in `cli.yaml`. For CI, set **`PS_ADMIN_TOKEN`** and **`INSTANCE_ID`**. | **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. @@ -284,13 +309,13 @@ Otherwise, upgrade to the latest **powersync** npm package and follow the mappin More information is available in the [PowerSync CLI repository](https://github.com/powersync-ja/powersync-cli). -| 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 (local development)](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) | Self-hosted Docker workflow, configure/start/stop/reset, database and storage modules, and template layout. | -| [Config Studio (editor)](https://github.com/powersync-ja/powersync-cli/tree/main/packages/editor) | Built-in Monaco-powered editor for `service.yaml` and `sync-config.yaml` (`powersync edit config`), schema validation, and local development. | -| [Examples](https://github.com/powersync-ja/powersync-cli/blob/main/examples/README.md) | Sample projects initialized with the CLI (e.g. Cloud pull, self-hosted Postgres, self-hosted Supabase). | +| 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 (local development)](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage-docker.md) | Self-hosted Docker workflow, configure/start/stop/reset, database and storage modules, and template layout. | +| [Config Studio (editor)](https://github.com/powersync-ja/powersync-cli/tree/main/packages/editor) | Built-in Monaco-powered editor for `service.yaml` and `sync-config.yaml` (`powersync edit config`), schema validation, and local development. | +| [Examples](https://github.com/powersync-ja/powersync-cli/blob/main/examples/README.md) | Sample projects initialized with the CLI (e.g. Cloud pull, self-hosted Postgres, self-hosted Supabase). | ## Known Issues and Limitations From 7da84607afb0ad88913f1dd1e0dd280c69c90436 Mon Sep 17 00:00:00 2001 From: LucDeCaf Date: Tue, 9 Jun 2026 10:27:02 +0200 Subject: [PATCH 4/4] Formatting --- tools/cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/cli.mdx b/tools/cli.mdx index d92b4a9b..e011c14f 100644 --- a/tools/cli.mdx +++ b/tools/cli.mdx @@ -102,11 +102,11 @@ The CLI uses a config directory (default `powersync/`) with YAML files: ### Developer Notes -- `cli.yaml` records the instance ID along with the organization and project IDs. The CLI normally writes all three for you. The organization and project IDs act as a cache: when both are present, the CLI uses them directly instead of looking them up from the instance, saving an API request. If they are missing, the CLI resolves them automatically from the instance ID. If they are present but incorrect for the instance, the CLI reports an error rather than overriding them. - Use the **`!env`** tag for secrets, e.g. `uri: !env PS_DATABASE_URI` (or `!env VAR::number` / `!env VAR::boolean` for types). - Edit files in your IDE, then run `powersync validate` and `powersync deploy`. For schema validation and `!env` support in your editor, run **`powersync configure ide`**; or run **`powersync edit config`** to open Config Studio (built-in web-based editor). - To use one config directory across multiple instances (e.g. dev, staging, prod), see the CLI usage docs on [configuring multiple instances](https://github.com/powersync-ja/powersync-cli/blob/main/docs/usage.md#configuring-multiple-instances-eg-dev-staging-production). - For Cloud secrets in `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. [Details](https://github.com/powersync-ja/powersync-cli#cloud-secrets-format-serviceyaml) +- `cli.yaml` records the instance ID along with the organization and project IDs. The organization and project IDs act as a cache: when both are present, the CLI uses them directly instead of looking them up from the instance, saving an API request. If they are missing, the CLI resolves them automatically from the instance ID. If they are present but incorrect for the instance, the CLI reports an error rather than overriding them. ## Cloud Workflows