Merge branch 'init' into packaging

stevensJourney · stevensJourney · commit 682e439c7291 · 2026-03-01T15:05:06.000+02:00
diff --git a/cli/README.md b/cli/README.md
@@ -42,7 +42,7 @@ npx powersync --version
 The PowerSync CLI lets you manage PowerSync instances and run commands (generate schemas, tokens, validate config, fetch status, and more). Support is split into two modes:
 
 - **Cloud** – Full support for [PowerSync Cloud](https://powersync.com). You can create new instances, deploy and pull config from the Dashboard, and run all Cloud commands. Authenticate with **`powersync login`** (or the `PS_ADMIN_TOKEN` env var), then use **`powersync init cloud`** / **`powersync link cloud`** or **`powersync pull instance`** to work with projects.
-- **Self-hosted** – Limited support for your own PowerSync Service. You link to an existing running instance and can run a subset of commands (e.g. **`powersync fetch status`**, **`powersync generate schema`**, **`powersync validate`**). The CLI does not create, deploy to, or pull config from self-hosted instances; you manage the server and its config yourself. We also expose a [PowerSync Docker topic](../plugins/docker/README.md) for local self-hosted development.
+- **Self-hosted** – Limited support for your own PowerSync Service. You link to an existing running instance and can run a subset of commands (e.g. **`powersync status`**, **`powersync generate schema`**, **`powersync validate`**). The CLI does not create, deploy to, or pull config from self-hosted instances; you manage the server and its config yourself. We also expose a [PowerSync Docker topic](../plugins/docker/README.md) for local self-hosted development.
 
 The sections below go into detail for [Cloud](#cloud) and [Self-hosted](#self-hosted).
 
@@ -126,7 +126,7 @@ To refresh local config after external edits from the cloud when already linked,
 
 ## Running commands against externally managed instances
 
-You can run CLI commands (e.g. **`powersync generate schema`**, **`powersync generate token`**, **`powersync fetch status`**) against a Cloud instance whose configuration is managed elsewhere—for example in the PowerSync Dashboard. No local config directory or link file is required.
+You can run CLI commands (e.g. **`powersync generate schema`**, **`powersync generate token`**, **`powersync status`**) against a Cloud instance whose configuration is managed elsewhere—for example in the PowerSync Dashboard. No local config directory or link file is required.
 
 Specify the instance using **environment variables** or **CLI flags** (flags take precedence): `--instance-id` and `--project-id` (or `INSTANCE_ID`, `PROJECT_ID`). **`--org-id` is optional**: when omitted, the CLI uses the token’s single organization if the token has access to exactly one; if the token has multiple orgs, you must pass **`--org-id`** (or set `ORG_ID`).
 
@@ -143,7 +143,7 @@ powersync generate schema --output-path=schema.ts --output=ts
 
 # Self-hosted
 
-The CLI can run a subset of commands against **self-hosted** PowerSync instances (your own API). Self-hosted support is more limited than Cloud: you link to an existing running API and use the same config directory concept, but only certain commands apply (e.g. **`powersync fetch status`**, **`powersync generate schema`**, **`powersync generate token`**, **`powersync validate`**). There is no **deploy** or **pull instance** for self-hosted; you manage config on the server yourself.
+The CLI can run a subset of commands against **self-hosted** PowerSync instances (your own API). Self-hosted support is more limited than Cloud: you link to an existing running API and use the same config directory concept, but only certain commands apply (e.g. **`powersync status`**, **`powersync generate schema`**, **`powersync generate token`**, **`powersync validate`**). There is no **deploy** or **pull instance** for self-hosted; you manage config on the server yourself.
 
 ## Authentication
 
@@ -169,13 +169,13 @@ The CLI resolves **`!env PS_ADMIN_TOKEN`** from the `PS_ADMIN_TOKEN` environment
 
 ## Creating a self-hosted project and limitations
 
-Run **`powersync init self-hosted`** to scaffold a config directory. Edit **`service.yaml`** with your instance details and use **`!env`** for secrets. This gives you a **partial** project: the CLI does not create or provision a self-hosted instance. You must already have a running PowerSync API. The CLI cannot deploy config to or pull config from a self-hosted instance; you manage **`service.yaml`** and **`sync-config.yaml`** on the server yourself. Use the CLI to link (**`powersync link self-hosted --api-url <url>`**), then run the supported commands (e.g. **`powersync fetch status`**, **`powersync generate schema`**) against that API.
+Run **`powersync init self-hosted`** to scaffold a config directory. Edit **`service.yaml`** with your instance details and use **`!env`** for secrets. This gives you a **partial** project: the CLI does not create or provision a self-hosted instance. You must already have a running PowerSync API. The CLI cannot deploy config to or pull config from a self-hosted instance; you manage **`service.yaml`** and **`sync-config.yaml`** on the server yourself. Use the CLI to link (**`powersync link self-hosted --api-url <url>`**), then run the supported commands (e.g. **`powersync status`**, **`powersync generate schema`**) against that API.
 
 ```sh
 powersync init self-hosted
   # then edit powersync/service.yaml
 powersync link self-hosted --api-url https://powersync.example.com
-powersync fetch status
+powersync status
 ```
 
 Use `--directory` for a different config folder.
@@ -186,7 +186,7 @@ We expose a [PowerSync Docker topic](../plugins/docker/README.md) for running a
 
 ## Command support
 
-Only some CLI commands work with self-hosted instances. Supported commands include **`powersync fetch status`**, **`powersync generate schema`**, **`powersync generate token`**, **`powersync validate`**, and **`powersync link self-hosted`**. Cloud-only commands such as **`powersync deploy`**, **`powersync destroy`**, **`powersync pull instance`**, **`powersync fetch config`**, and **`powersync fetch instances`** do not apply to self-hosted.
+Only some CLI commands work with self-hosted instances. Supported commands include **`powersync status`**, **`powersync generate schema`**, **`powersync generate token`**, **`powersync validate`**, and **`powersync link self-hosted`**. Cloud-only commands such as **`powersync deploy`**, **`powersync destroy`**, **`powersync pull instance`**, **`powersync fetch config`**, and **`powersync fetch instances`** do not apply to self-hosted.
 
 # Known Limitations
 
@@ -245,7 +245,7 @@ You can supply instance and auth context via environment variables (useful for C
 Example (Cloud):
 
 ```sh
-PS_ADMIN_TOKEN=your-token PROJECT_ID=456 INSTANCE_ID=789 powersync fetch status
+PS_ADMIN_TOKEN=your-token PROJECT_ID=456 INSTANCE_ID=789 powersync status
 ```
 
 See [docs/usage.md](../docs/usage.md) for full usage and resolution order (flags, env, cli.yaml).
@@ -561,7 +561,7 @@ DESCRIPTION
 
   Run `docker compose down` then `docker compose up -d --wait`: stops and removes containers, then starts the stack and
   waits for services (including PowerSync) to be healthy. Use when you want a clean bring-up (e.g. after config
-  changes). Use `powersync fetch status` to debug running instances.
+  changes). Use `powersync status` to debug running instances.
 
 EXAMPLES
   $ powersync docker reset
@@ -587,7 +587,7 @@ DESCRIPTION
   Start the self-hosted PowerSync stack via Docker Compose.
 
   Runs `docker compose up -d --wait` for the project docker/ compose file; waits for services (including PowerSync) to
-  be healthy. Use `powersync fetch status` to debug running instances.
+  be healthy. Use `powersync status` to debug running instances.
 
 EXAMPLES
   $ powersync docker start
diff --git a/cli/package.json b/cli/package.json
@@ -122,7 +122,6 @@
     "build": "tsc -b && pnpm prepack",
     "lint": "eslint",
     "postpack": "shx rm -f oclif.manifest.json",
-    "posttest": "pnpm run lint",
     "pretest": "pnpm run build",
     "readme:generate": "oclif readme && pnpm exec prettier --write README.md",
     "prepack": "oclif manifest && pnpm run readme:generate",
diff --git a/cli/src/commands/deploy/index.ts b/cli/src/commands/deploy/index.ts
@@ -317,7 +317,7 @@ export default class DeployAll extends CloudInstanceCommand {
           sync_rules: project.syncRulesContent ?? ''
         })
         .catch((error) => {
-          if (retry === 9) {
+          if (retry === 99) {
             this.styledError({
               error,
               message: `Failed to validate sync config for instance ${project.linked.instance_id} in project ${project.linked.project_id} in org ${project.linked.org_id}. Ensure the sync config is valid before deploying.`,
@@ -342,6 +342,9 @@ export default class DeployAll extends CloudInstanceCommand {
           suggestions: ['Check your sync config and try again.']
         });
       }
+
+      // Validation succeeded with no errors
+      return;
     }
   }
 
@@ -381,7 +384,7 @@ export default class DeployAll extends CloudInstanceCommand {
       this.log(ux.colorize('green', 'Deployment operation completed successfully!'));
     } else {
       this.styledError({
-        message: `Deploy failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync fetch status')}`
+        message: `Deploy failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync status')}`
       });
     }
   }
diff --git a/cli/src/commands/deploy/sync-config.ts b/cli/src/commands/deploy/sync-config.ts
@@ -1,9 +1,10 @@
 import { ux } from '@oclif/core/ux';
 import { routes } from '@powersync/management-types';
 
+import { DEFAULT_DEPLOY_TIMEOUT_MS } from '../../api/cloud/wait-for-operation.js';
 import DeployAll from './index.js';
 
-export class DeploySyncConfig extends DeployAll {
+export default class DeploySyncConfig extends DeployAll {
   static description = 'Deploy only sync config changes.';
   static examples = [
     '<%= config.bin %> <%= command.id %>',
@@ -55,7 +56,7 @@ export class DeploySyncConfig extends DeployAll {
   }
 
   async run(): Promise<void> {
-    const { flags } = await this.parse(DeployAll);
+    const { flags } = await this.parse(DeploySyncConfig);
 
     const project = await this.loadProject(flags, {
       // We don't need the config to be managed locally for this
@@ -65,6 +66,8 @@ export class DeploySyncConfig extends DeployAll {
     const { linked } = project;
     this.parseConfig(project.projectDirectory);
 
+    const deployTimeoutMs = (flags['deploy-timeout'] ?? DEFAULT_DEPLOY_TIMEOUT_MS / 1000) * 1000;
+
     // The existing config is required to deploy changes. The instance should have been created already.
     const cloudConfigState = await this.loadCloudConfigState();
 
@@ -97,7 +100,7 @@ export class DeploySyncConfig extends DeployAll {
         `\nThe instance is not currently provisioned. Triggering a deploy in order to reprovision. This may take a few minutes.\n`
       );
       // Don't yet update the sync config since the instance is not provisioned, but deploy to trigger provisioning
-      await this.deployAll({ cloudConfigState, deployTimeoutMs: flags.timeout, updateSyncConfig: false });
+      await this.deployAll({ cloudConfigState, deployTimeoutMs, updateSyncConfig: false });
     }
 
     // Validate sync config
@@ -106,6 +109,6 @@ export class DeploySyncConfig extends DeployAll {
 
     this.log('Validations completed successfully.\n');
 
-    await this.deploySyncConfig({ cloudConfigState, timeout: flags.timeout });
+    await this.deploySyncConfig({ cloudConfigState, timeout: deployTimeoutMs });
   }
 }
diff --git a/cli/src/commands/destroy.ts b/cli/src/commands/destroy.ts
@@ -56,7 +56,7 @@ export default class Destroy extends CloudInstanceCommand {
         this.log(ux.colorize('green', 'Instance destroyed successfully.'));
       } else {
         this.styledError({
-          message: `Operation failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync fetch status')}`
+          message: `Operation failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync status')}`
         });
       }
     } catch (error) {
diff --git a/cli/src/commands/link/cloud.ts b/cli/src/commands/link/cloud.ts
@@ -89,15 +89,14 @@ export default class LinkCloud extends CloudInstanceCommand {
         this.styledError({ error, message: 'Failed to create Cloud instance' });
       }
 
-      const projectDir = this.ensureProjectDirectory({ directory });
       ensureServiceTypeMatches({
         command: this,
         configRequired: false,
         directoryLabel: directory,
         expectedType: ServiceType.CLOUD,
-        projectDir
+        projectDir: projectDirectory
       });
-      writeCloudLink(projectDir, { instanceId: newInstanceId, orgId, projectId });
+      writeCloudLink(projectDirectory, { instanceId: newInstanceId, orgId, projectId });
       this.log(
         ux.colorize('green', `Created Cloud instance ${newInstanceId} and updated ${directory}/${CLI_FILENAME}.`)
       );
diff --git a/cli/src/commands/logout.ts b/cli/src/commands/logout.ts
@@ -8,6 +8,7 @@ export default class Logout extends PowerSyncCommand {
   static summary = 'Remove stored auth token.';
 
   async run(): Promise<void> {
+    await this.parse(Logout);
     const { authentication } = Services;
 
     const token = await authentication.getToken();
diff --git a/cli/src/commands/stop.ts b/cli/src/commands/stop.ts
@@ -58,7 +58,7 @@ export default class Stop extends CloudInstanceCommand {
         this.log(ux.colorize('green', 'Instance stopped successfully.'));
       } else {
         this.styledError({
-          message: `Operation failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync fetch status')}`
+          message: `Operation failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync status')}`
         });
       }
     } catch (error) {
diff --git a/cli/test/commands/link.test.ts b/cli/test/commands/link.test.ts
@@ -29,8 +29,8 @@ const accountsClientMock = {
   listProjects: vi.fn()
 };
 
-vi.spyOn(cliCore, 'createAccountsHubClient').mockImplementation(
-  async () => accountsClientMock as unknown as Awaited<ReturnType<typeof cliCore.createAccountsHubClient>>
+vi.spyOn(cliCore, 'createAccountsHubClient').mockResolvedValue(
+  accountsClientMock as unknown as Awaited<ReturnType<typeof cliCore.createAccountsHubClient>>
 );
 
 function writeServiceYaml(projectDir: string, type: 'cloud' | 'self-hosted') {
diff --git a/docs/usage-docker.md b/docs/usage-docker.md
@@ -68,7 +68,7 @@ Use **`powersync docker reset`** only when you need to start from a clean state:
 
 All of these use the project name from **cli.yaml** unless you pass **`--project-name`** (e.g. to stop from any directory or to target a specific project).
 
-Use **`powersync fetch status`** to debug a running instance.
+Use **`powersync status`** to debug a running instance.
 
 ---
 
@@ -127,7 +127,7 @@ powersync docker start --directory=my-powersync
 Configure sets **cli.yaml** with **api_url** and **api_key** for the local stack so you can run **fetch status**, **validate**, **generate schema**, etc. without extra flags:
 
 ```bash
-powersync fetch status
+powersync status
 powersync validate
 powersync generate schema --output=ts --output-path=./schema.ts
 ```
diff --git a/docs/usage.md b/docs/usage.md
@@ -222,7 +222,7 @@ If you decline this prompt, login exits without storing a token. Use `PS_ADMIN_T
 
 # Supplying Linking Information for Cloud and Self-Hosted Commands
 
-Cloud and self-hosted commands need instance (and for Cloud, org and project) identifiers. **Cloud only:** `powersync deploy`, `powersync deploy service-config`, `powersync deploy sync-config`, `powersync destroy`, `powersync stop`, `powersync fetch config`, `powersync pull instance`. **Both:** `powersync fetch status`, `powersync generate schema`, `powersync generate token`, `powersync validate`. The same three methods apply: the CLI uses the first that is available for each field (flags override environment variables, environment variables override link file). For Cloud, **org_id is optional**: when not set via flags, env, or link file, the CLI fetches the token’s organizations and uses the single org if there is exactly one; if the token has multiple orgs, the command errors and you must pass `--org-id` (or set `ORG_ID`).
+Cloud and self-hosted commands need instance (and for Cloud, org and project) identifiers. **Cloud only:** `powersync deploy`, `powersync deploy service-config`, `powersync deploy sync-config`, `powersync destroy`, `powersync stop`, `powersync fetch config`, `powersync pull instance`. **Both:** `powersync status`, `powersync generate schema`, `powersync generate token`, `powersync validate`. The same three methods apply: the CLI uses the first that is available for each field (flags override environment variables, environment variables override link file). For Cloud, **org_id is optional**: when not set via flags, env, or link file, the CLI fetches the token’s organizations and uses the single org if there is exactly one; if the token has multiple orgs, the command errors and you must pass `--org-id` (or set `ORG_ID`).
 
 1. **Flags**
    - **Cloud:** `--instance-id`, `--project-id` (required when using instance-id), `--org-id` (optional; defaults to token’s single org)
@@ -255,7 +255,7 @@ powersync stop --confirm=yes \
 **Self-hosted:** Set `PS_ADMIN_TOKEN` (or use a linked project with API key in cli.yaml), then:
 
 ```bash
-powersync fetch status --api-url=https://powersync.example.com
+powersync status --api-url=https://powersync.example.com
 ```
 
 You can use a different project directory with `--directory`:
@@ -265,7 +265,7 @@ You can use a different project directory with `--directory`:
 powersync stop --confirm=yes --directory=my-powersync --instance-id=... --project-id=...
 
 # Self-hosted (API key from PS_ADMIN_TOKEN or cli.yaml)
-powersync fetch status --directory=my-powersync --api-url=https://...
+powersync status --directory=my-powersync --api-url=https://...
 ```
 
 ---
@@ -285,7 +285,7 @@ powersync link cloud \
 
 # No IDs needed on later commands
 powersync stop --confirm=yes
-powersync fetch status
+powersync status
 ```
 
 If the project lives in a non-default directory:
@@ -318,7 +318,7 @@ powersync fetch config --output=json
 export API_URL=https://powersync.example.com
 export PS_ADMIN_TOKEN=your-api-key
 
-powersync fetch status --output=json
+powersync status --output=json
 ```
 
 Inline for a single command:
@@ -328,7 +328,7 @@ Inline for a single command:
 INSTANCE_ID=... PROJECT_ID=... powersync stop --confirm=yes
 
 # Self-hosted
-API_URL=https://... PS_ADMIN_TOKEN=... powersync fetch status --output=json
+API_URL=https://... PS_ADMIN_TOKEN=... powersync status --output=json
 ```
 
 **Note:** Environment variables are only used when neither flags nor `cli.yaml` provide linking information.
diff --git a/examples/cloud/basic-cloud-pull/README.md b/examples/cloud/basic-cloud-pull/README.md
@@ -21,6 +21,6 @@ powersync deploy
 This project can be used with any of the cloud cli commands e.g.
 
 ```bash
-powersync fetch status
+powersync status
 powersync generate schema --output-path=schema.ts --output=ts
 ```
diff --git a/examples/self-hosted/local-basic-supabase/README.md b/examples/self-hosted/local-basic-supabase/README.md
@@ -89,6 +89,6 @@ powersync docker start
 This project can be used with any self-hosted CLI commands:
 
 ```bash
-powersync fetch status
+powersync status
 powersync generate schema --output-path=schema.ts --output=ts
 ```
diff --git a/examples/self-hosted/local-postgres/README.md b/examples/self-hosted/local-postgres/README.md
@@ -64,6 +64,6 @@ powersync docker start
 This project can be used with any self-hosted CLI commands:
 
 ```bash
-powersync fetch status
+powersync status
 powersync generate schema --output-path=schema.ts --output=ts
 ```
diff --git a/packages/cli-core/src/command-types/CloudInstanceCommand.ts b/packages/cli-core/src/command-types/CloudInstanceCommand.ts
@@ -200,7 +200,7 @@ export abstract class CloudInstanceCommand extends InstanceCommand {
     }
 
     this._project = {
-      linked: linked!,
+      linked,
       projectDirectory: projectDir,
       syncRulesContent
     };
diff --git a/packages/cli-core/src/command-types/SelfHostedInstanceCommand.ts b/packages/cli-core/src/command-types/SelfHostedInstanceCommand.ts
@@ -107,7 +107,7 @@ export abstract class SelfHostedInstanceCommand extends InstanceCommand {
     }
 
     this._project = {
-      linked: linked!,
+      linked,
       projectDirectory: projectDir
     };
     return this._project;
diff --git a/packages/cli-core/src/services/storage/KeychainSecureStorage.ts b/packages/cli-core/src/services/storage/KeychainSecureStorage.ts
@@ -41,8 +41,20 @@ export function createKeychainSecureStorage(): BaseStorage {
       const keychain = await keychainPromise;
       return new Promise((resolve, reject) => {
         keychain.deletePassword({ account: key, service: SERVICE_NAME }, (err: Error | null) => {
-          if (err) reject(err);
-          else resolve();
+          if (err) {
+            if (
+              err.message?.includes('could not be found') ||
+              (err as Error & { code?: string }).code === 'PasswordNotFound'
+            ) {
+              resolve();
+              return;
+            }
+
+            reject(err);
+            return;
+          }
+
+          resolve();
         });
       });
     },
diff --git a/plugins/docker/src/api/docker.ts b/plugins/docker/src/api/docker.ts
diff --git a/plugins/docker/src/commands/docker/reset.ts b/plugins/docker/src/commands/docker/reset.ts
diff --git a/plugins/docker/src/commands/docker/start.ts b/plugins/docker/src/commands/docker/start.ts

Original file line number	Diff line number	Diff line change
`@@ -317,7 +317,7 @@ export default class DeployAll extends CloudInstanceCommand {`
`317`	`317`	`sync_rules: project.syncRulesContent ?? ''`
`318`	`318`	`})`
`319`	`319`	`.catch((error) => {`
`320`		`- if (retry === 9) {`
	`320`	`+ if (retry === 99) {`
`321`	`321`	`this.styledError({`
`322`	`322`	`error,`
`323`	`323`	message: `Failed to validate sync config for instance ${project.linked.instance_id} in project ${project.linked.project_id} in org ${project.linked.org_id}. Ensure the sync config is valid before deploying.`,
`@@ -342,6 +342,9 @@ export default class DeployAll extends CloudInstanceCommand {`
`342`	`342`	`suggestions: ['Check your sync config and try again.']`
`343`	`343`	`});`
`344`	`344`	`}`
	`345`	`+`
	`346`	`+ // Validation succeeded with no errors`
	`347`	`+ return;`
`345`	`348`	`}`
`346`	`349`	`}`
`347`	`350`
`@@ -381,7 +384,7 @@ export default class DeployAll extends CloudInstanceCommand {`
`381`	`384`	`this.log(ux.colorize('green', 'Deployment operation completed successfully!'));`
`382`	`385`	`} else {`
`383`	`386`	`this.styledError({`
`384`		- message: `Deploy failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync fetch status')}`
	`387`	+ message: `Deploy failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync status')}`
`385`	`388`	`});`
`386`	`389`	`}`
`387`	`390`	`}`
Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,7 @@ export default class Destroy extends CloudInstanceCommand {`
`56`	`56`	`this.log(ux.colorize('green', 'Instance destroyed successfully.'));`
`57`	`57`	`} else {`
`58`	`58`	`this.styledError({`
`59`		- message: `Operation failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync fetch status')}`
	`59`	+ message: `Operation failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync status')}`
`60`	`60`	`});`
`61`	`61`	`}`
`62`	`62`	`} catch (error) {`
Original file line number	Diff line number	Diff line change
`@@ -58,7 +58,7 @@ export default class Stop extends CloudInstanceCommand {`
`58`	`58`	`this.log(ux.colorize('green', 'Instance stopped successfully.'));`
`59`	`59`	`} else {`
`60`	`60`	`this.styledError({`
`61`		- message: `Operation failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync fetch status')}`
	`61`	+ message: `Operation failed. Check instance diagnostics for details, for example: ${ux.colorize('blue', 'powersync status')}`
`62`	`62`	`});`
`63`	`63`	`}`
`64`	`64`	`} catch (error) {`