From 5e13c59d1c2b8cea6c963e0c4b8670b9d61b309f Mon Sep 17 00:00:00 2001 From: LucDeCaf Date: Wed, 27 May 2026 15:12:23 +0200 Subject: [PATCH] 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.