diff --git a/skills/powersync/AGENTS.md b/skills/powersync/AGENTS.md index e94f962..2f42974 100644 --- a/skills/powersync/AGENTS.md +++ b/skills/powersync/AGENTS.md @@ -121,7 +121,8 @@ Collect the minimum for the chosen path before changing app code. Only ask for s - Backend/database (do not assume Supabase — ask if unspecified) - Whether the PowerSync instance already exists - PowerSync instance URL, if it exists -- Project ID + instance ID, if using CLI with an existing instance +- Instance ID, if using CLI with an existing instance +- Project ID, if using CLI to create a new Cloud instance (`powersync link cloud --create`); also `--org-id` if the PAT covers multiple organizations - Source DB connection string, if PowerSync still needs it ### Additional for Supabase diff --git a/skills/powersync/references/onboarding-custom.md b/skills/powersync/references/onboarding-custom.md index bdb7308..a9da403 100644 --- a/skills/powersync/references/onboarding-custom.md +++ b/skills/powersync/references/onboarding-custom.md @@ -22,7 +22,8 @@ Collect before writing any code: - Database connection details (host, port, database, username, password or connection URI) - Whether a PowerSync instance already exists - PowerSync instance URL (if instance exists) -- Project ID and instance ID (if using CLI with existing Cloud instance) +- Instance ID (if using CLI with an existing Cloud instance) +- Project ID (if using CLI to create a new Cloud instance via `powersync link cloud --create`); also Org ID if the PAT covers multiple organizations - How the operator wants to handle auth (custom JWT, third-party provider like Auth0/Firebase, or dev tokens) - Whether they have an existing backend API or need to create one diff --git a/skills/powersync/references/onboarding-supabase.md b/skills/powersync/references/onboarding-supabase.md index 155355e..6463d9a 100644 --- a/skills/powersync/references/onboarding-supabase.md +++ b/skills/powersync/references/onboarding-supabase.md @@ -19,7 +19,8 @@ Collect before editing app code: - Whether the PowerSync Cloud instance already exists - PowerSync instance URL (if instance exists) -- Project ID and instance ID (if using CLI with existing instance) +- Instance ID (if using CLI with an existing instance) +- Project ID (if using CLI to create a new Cloud instance via `powersync link cloud --create`); also Org ID if the PAT covers multiple organizations - Supabase Postgres connection string (if source DB connection not yet configured) - `PS_ADMIN_TOKEN` or willingness to run `powersync login` (Cloud PAT only) @@ -42,7 +43,7 @@ Follow this sequence exactly. **Do not skip ahead to app code.** 4. **Scaffold and configure PowerSync.** - **New instance (CLI):** `powersync init cloud` → edit config → `powersync link cloud --create --project-id=` → deploy - **New instance (Dashboard):** Create project/instance → connect database → deploy sync config → enable Supabase Auth - - **Existing instance (CLI):** `powersync pull instance --project-id= --instance-id=` → edit → deploy + - **Existing instance (CLI):** `powersync pull instance --instance-id=` → edit → deploy See `references/powersync-cli.md` for full CLI workflow. Never run `powersync pull instance` after editing local config without backing up first. diff --git a/skills/powersync/references/powersync-cli.md b/skills/powersync/references/powersync-cli.md index 8239c32..c4e1b1d 100644 --- a/skills/powersync/references/powersync-cli.md +++ b/skills/powersync/references/powersync-cli.md @@ -87,11 +87,11 @@ The CLI needs to know which instance to operate against. It uses the first avail | Priority | Method | How | |----------|--------|-----| -| 1 (highest) | Flags | `--instance-id`, `--project-id`, `--api-url`, etc. | -| 2 | Environment variables | `INSTANCE_ID`, `PROJECT_ID`, `API_URL`, etc. | +| 1 (highest) | Flags | `--instance-id`, `--api-url`, etc. | +| 2 | Environment variables | `INSTANCE_ID`, `API_URL`, etc. | | 3 (lowest) | Link file | `powersync/cli.yaml` written by `powersync link` | -For Cloud, `--org-id` / `ORG_ID` is optional — omit it when your token has access to exactly one org. If the token covers multiple orgs, it must be provided. +For Cloud, `--instance-id` (or `INSTANCE_ID`, or a linked `cli.yaml`) is all that is needed to identify the instance — project and org are resolved automatically. `--project-id` and `--org-id` are deprecated as manual flags and only required for `powersync link cloud --create` (creating a brand-new instance, when no instance ID exists yet). For `--create`, `--org-id` is only needed if your token covers multiple organizations. ## Authentication @@ -273,16 +273,13 @@ Write it to `.env` as `POWERSYNC_URL=https://.powersync.journeyapps ### Existing Cloud Instance **Information the agent must collect from the operator:** -- Project ID - Instance ID -- Org ID (only if token covers multiple orgs) -The operator can find these on the PowerSync Dashboard or by running `powersync fetch instances` after `powersync login`. +The operator can find this on the PowerSync Dashboard or by running `powersync fetch instances` after `powersync login`. Project and org are resolved automatically from the instance. ```bash powersync login -powersync pull instance --project-id= --instance-id= -# Add --org-id= only if token has multiple orgs +powersync pull instance --instance-id= ``` This creates `powersync/`, writes `cli.yaml`, and downloads `service.yaml` and `sync-config.yaml`. @@ -318,7 +315,7 @@ Prefer targeted deploys when only one file changed. ```bash powersync login powersync fetch instances # see available instances and IDs -powersync link cloud --instance-id= --project-id= +powersync link cloud --instance-id= powersync generate schema powersync generate token ``` @@ -390,11 +387,8 @@ Supported self-hosted commands: `status`, `generate schema`, `generate token`, ` ### Via Flags ```bash -# Cloud -powersync stop --confirm=yes \ - --instance-id= \ - --project-id= -# Add --org-id= only if token has multiple orgs +# Cloud — project and org are resolved from --instance-id automatically +powersync stop --confirm=yes --instance-id= # Self-hosted (API key from PS_ADMIN_TOKEN or cli.yaml) powersync status --api-url=https://powersync.example.com @@ -405,8 +399,6 @@ powersync status --api-url=https://powersync.example.com ```bash # Cloud export INSTANCE_ID= -export PROJECT_ID= -# export ORG_ID= # only if token has multiple orgs powersync stop --confirm=yes # Self-hosted @@ -415,7 +407,7 @@ export PS_ADMIN_TOKEN=your-api-key powersync status --output=json # Inline -INSTANCE_ID= PROJECT_ID= powersync stop --confirm=yes +INSTANCE_ID= powersync stop --confirm=yes API_URL=https://... PS_ADMIN_TOKEN=... powersync status ``` @@ -439,10 +431,10 @@ Use one `powersync/` folder and vary instance info via environment variables. Bo ```yaml type: cloud instance_id: !env MY_INSTANCE_ID -project_id: !env MY_PROJECT_ID -org_id: !env MY_ORG_ID ``` +> `powersync link cloud` writes `instance_id`, `org_id`, and `project_id` by default to skip an extra API call per command. The minimal form above is equivalent — project and org are resolved from the instance at runtime. + `cli.yaml` (self-hosted): ```yaml type: self-hosted @@ -516,16 +508,13 @@ Required CI environment variables: | Variable | Purpose | |----------|---------| | `PS_ADMIN_TOKEN` | PowerSync personal access token | -| `INSTANCE_ID` | Target instance (if not using a linked directory) | -| `PROJECT_ID` | Target project (if not using a linked directory) | -| `ORG_ID` | Required only if token has multiple organizations | +| `INSTANCE_ID` | Target instance (if not using a linked directory). Project and org are resolved from this automatically. | | `API_URL` | Self-hosted: PowerSync API base URL | ```bash # Example: deploy sync config on push PS_ADMIN_TOKEN=${{ secrets.PS_ADMIN_TOKEN }} \ INSTANCE_ID=${{ vars.INSTANCE_ID }} \ -PROJECT_ID=${{ vars.PROJECT_ID }} \ powersync deploy sync-config ``` @@ -540,10 +529,10 @@ powersync deploy sync-config | `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 cloud --instance-id=` | Link to an existing Cloud instance | +| `powersync link cloud --create --project-id=` | Create a new Cloud instance and link (add `--org-id` only if token has multiple orgs) | | `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 pull instance --instance-id=` | Download Cloud config into local files | | `powersync deploy` | Deploy full config to linked Cloud instance | | `powersync deploy service-config` | Deploy only service config | | `powersync deploy sync-config` | Deploy only sync config (optional `--sync-config-file-path`) | @@ -587,13 +576,13 @@ Otherwise, upgrade to the latest `powersync` package and follow this mapping: | Previous CLI | New CLI | |-------------|---------| -| `npx powersync init` (enter token, org, project) | `powersync login` (token only). Then `powersync init cloud` to scaffold, 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`). Use `--directory` for a specific folder. | +| `npx powersync init` (enter token, org, project) | `powersync login` (token only). Then `powersync init cloud` to scaffold, or `powersync pull instance --instance-id=...` to pull an existing instance. | +| `powersync instance set --instanceId=` | `powersync link cloud --instance-id=` (writes `cli.yaml`). 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 rules | `powersync deploy sync-config` | | `powersync instance schema` | `powersync generate schema --output=... --output-path=...` | -| 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`. | +| Org/project stored by init | Org and project are now resolved automatically from `--instance-id`. Use `powersync link cloud --instance-id=` to store it in `powersync/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`. No more setting "current instance" separately from config — the directory and `cli.yaml` define the target.