chore(cli): update CLI command flags

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

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
 

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=<id>` → deploy
    - **New instance (Dashboard):** Create project/instance → connect database → deploy sync config → enable Supabase Auth
-   - **Existing instance (CLI):** `powersync pull instance --project-id=<id> --instance-id=<id>` → edit → deploy
+   - **Existing instance (CLI):** `powersync pull instance --instance-id=<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.
 

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://<instance-id>.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=<project-id> --instance-id=<instance-id>
-# Add --org-id=<org-id> only if token has multiple orgs
+powersync pull instance --instance-id=<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=<id> --project-id=<id>
+powersync link cloud --instance-id=<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=<id> \
-  --project-id=<id>
-# Add --org-id=<id> only if token has multiple orgs
+# Cloud — project and org are resolved from --instance-id automatically
+powersync stop --confirm=yes --instance-id=<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=<id>
-export PROJECT_ID=<id>
-# export ORG_ID=<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=<id> PROJECT_ID=<id> powersync stop --confirm=yes
+INSTANCE_ID=<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=<id>` | Link to an existing Cloud instance |
-| `powersync link cloud --create --project-id=<id>` | Create a new Cloud instance and link |
+| `powersync link cloud --instance-id=<id>` | Link to an existing Cloud instance |
+| `powersync link cloud --create --project-id=<id>` | Create a new Cloud instance and link (add `--org-id` only if token has multiple orgs) |
 | `powersync link self-hosted --api-url=<url>` | Link to a self-hosted instance by API URL |
-| `powersync pull instance --project-id=<id> --instance-id=<id>` | Download Cloud config into local files |
+| `powersync pull instance --instance-id=<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=<id>` | `powersync link cloud --instance-id=<id> --project-id=<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=<id>` | `powersync link cloud --instance-id=<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=<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.