powersync-ja · stevensJourney · Mar 4, 2026 · Feb 2, 2026 · Feb 3, 2026 · Feb 3, 2026
diff --git a/cli/README.md b/cli/README.md
@@ -971,7 +971,7 @@ _See code: [src/commands/init/self-hosted.ts](https://github.com/powersync-ja/po
 
 ## `powersync link cloud`
 
-Link to a PowerSync Cloud instance (or create one with --create).
+[Cloud only] Link to a PowerSync Cloud instance (or create one with --create).
 
 ```
 USAGE
@@ -992,7 +992,7 @@ PROJECT FLAGS
                        directory.
 
 DESCRIPTION
-  Link to a PowerSync Cloud instance (or create one with --create).
+  [Cloud only] Link to a PowerSync Cloud instance (or create one with --create).
 
   Write or update cli.yaml with a Cloud instance (instance-id, org-id, project-id). Use --create to create a new
   instance from service.yaml name/region and link it; omit --instance-id when using --create. Org ID is optional when
@@ -1083,17 +1083,29 @@ Migrates Sync Rules to Sync Streams
 
 ```
 USAGE
-  $ powersync migrate sync-rules [--input-file <value>] [--output-file <value>] [--directory <value>]
+  $ powersync migrate sync-rules [--input-file <value>] [--output-file <value>] [--api-url <value> | --instance-id
+    <value> | --org-id <value> | --project-id <value>] [--directory <value>]
 
 FLAGS
   --input-file=<value>   Path to the input sync rules file. Defaults to the project sync-config.yaml file.
   --output-file=<value>  Path to the output sync streams file. Defaults to overwrite the input file.
 
+SELF_HOSTED_PROJECT FLAGS
+  --api-url=<value>  [Self-hosted] PowerSync API URL. When set, context is treated as self-hosted (exclusive with
+                     --instance-id). Resolved: flag → cli.yaml → API_URL.
+
 PROJECT FLAGS
   --directory=<value>  [default: powersync] Directory containing PowerSync config. Defaults to "powersync". This is
                        required if multiple powersync config files are present in subdirectories of the current working
                        directory.
 
+CLOUD_PROJECT FLAGS
+  --instance-id=<value>  [Cloud] PowerSync Cloud instance ID (BSON ObjectID). When set, context is treated as cloud
+                         (exclusive with --api-url). Resolved: flag → cli.yaml → INSTANCE_ID.
+  --org-id=<value>       [Cloud] Organization ID (optional). Defaults to the token’s single org when only one is
+                         available; pass explicitly if the token has multiple orgs. Resolved: flag → cli.yaml → ORG_ID.
+  --project-id=<value>   [Cloud] Project ID. Resolved: flag → cli.yaml → PROJECT_ID.
+
 DESCRIPTION
   Migrates Sync Rules to Sync Streams
 
@@ -1394,7 +1406,7 @@ _See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/
 
 ## `powersync pull instance`
 
-Pull an existing Cloud instance: link and download config into local service.yaml and sync-config.yaml.
+[Cloud only] Pull an existing Cloud instance: link and download config into local service.yaml and sync-config.yaml.
 
 ```
 USAGE
@@ -1412,7 +1424,7 @@ CLOUD_PROJECT FLAGS
   --project-id=<value>   Project ID. Manually passed if the current context has not been linked.
 
 DESCRIPTION
-  Pull an existing Cloud instance: link and download config into local service.yaml and sync-config.yaml.
+  [Cloud only] Pull an existing Cloud instance: link and download config into local service.yaml and sync-config.yaml.
 
   Fetch an existing Cloud instance by ID: create the config directory if needed, write cli.yaml, and download
   service.yaml and sync-config.yaml. Pass --instance-id and --project-id when the directory is not yet linked; --org-id

diff --git a/cli/package.json b/cli/package.json
@@ -72,6 +72,7 @@
     "bin": "powersync",
     "dirname": "powersync",
     "commands": "./dist/commands",
+    "helpClass": "./dist/help.js",
     "plugins": [
       "@oclif/plugin-help",
       "@oclif/plugin-plugins",

diff --git a/cli/src/commands/configure/ide.ts b/cli/src/commands/configure/ide.ts
@@ -1,6 +1,6 @@
 import { select } from '@inquirer/prompts';
 import { ux } from '@oclif/core';
-import { CLI_FILENAME, parseYamlFile, PowerSyncCommand } from '@powersync/cli-core';
+import { CLI_FILENAME, CommandHelpGroup, parseYamlFile, PowerSyncCommand } from '@powersync/cli-core';
 import { CLIConfig } from '@powersync/cli-schemas';
 import { readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
@@ -39,6 +39,7 @@ function findLinkedProjectDirs(cwd: string): string[] {
 }
 
 export default class ConfigureIde extends PowerSyncCommand {
+  static commandHelpGroup = CommandHelpGroup.PROJECT_SETUP;
   static description =
     'Configure or guide your IDE setup for the best PowerSync CLI developer experience. Enables YAML schema validation and autocompletion, sets up !env custom tag support, and patches existing config files with language server directives.';
   static examples = ['<%= config.bin %> <%= command.id %>'];

diff --git a/cli/src/commands/fetch/instances.ts b/cli/src/commands/fetch/instances.ts
@@ -1,5 +1,11 @@
 import { Command, Flags, ux } from '@oclif/core';
-import { CLI_FILENAME, createAccountsHubClient, createCloudClient, parseYamlFile } from '@powersync/cli-core';
+import {
+  CLI_FILENAME,
+  CommandHelpGroup,
+  createAccountsHubClient,
+  createCloudClient,
+  parseYamlFile
+} from '@powersync/cli-core';
 import { CLIConfig } from '@powersync/cli-schemas';
 import sortBy from 'lodash/sortBy.js';
 import fs, { readdir } from 'node:fs/promises';
@@ -34,6 +40,7 @@ type OrganizationMap = {
 };
 
 export default class FetchInstances extends Command {
+  static commandHelpGroup = CommandHelpGroup.CLOUD;
   static description =
     'List PowerSync Cloud and linked instances, Cloud instances are grouped by organization and project.';
   static examples = [

diff --git a/cli/src/commands/init/cloud.ts b/cli/src/commands/init/cloud.ts
@@ -1,6 +1,7 @@
 import { ux } from '@oclif/core';
 import {
   CLI_FILENAME,
+  CommandHelpGroup,
   InstanceCommand,
   SERVICE_FILENAME,
   SYNC_FILENAME,
@@ -16,6 +17,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '..', '..', '..', 'templates');
 
 export default class InitCloud extends InstanceCommand {
+  static commandHelpGroup = CommandHelpGroup.PROJECT_SETUP;
   static description =
     'Copy a Cloud template into a config directory (default powersync/). Edit service.yaml then run link cloud and deploy.';
   static examples = [

diff --git a/cli/src/commands/init/self-hosted.ts b/cli/src/commands/init/self-hosted.ts
@@ -1,6 +1,7 @@
 import { ux } from '@oclif/core';
 import {
   CLI_FILENAME,
+  CommandHelpGroup,
   InstanceCommand,
   SERVICE_FILENAME,
   SYNC_FILENAME,
@@ -16,6 +17,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '..', '..', '..', 'templates');
 
 export default class InitSelfHosted extends InstanceCommand {
+  static commandHelpGroup = CommandHelpGroup.PROJECT_SETUP;
   static description =
     'Copy a self-hosted template into a config directory (default powersync/). Configure service.yaml with your self-hosted instance details.';
   static examples = [

diff --git a/cli/src/commands/link/cloud.ts b/cli/src/commands/link/cloud.ts
@@ -2,6 +2,7 @@ import { Flags, ux } from '@oclif/core';
 import {
   CLI_FILENAME,
   CloudInstanceCommand,
+  CommandHelpGroup,
   ensureServiceTypeMatches,
   env,
   getDefaultOrgId,
@@ -14,6 +15,7 @@ import { validateCloudLinkConfig } from '../../api/cloud/validate-cloud-link-con
 import { writeCloudLink } from '../../api/cloud/write-cloud-link.js';
 
 export default class LinkCloud extends CloudInstanceCommand {
+  static commandHelpGroup = CommandHelpGroup.PROJECT_SETUP;
   static description =
     'Write or update cli.yaml with a Cloud instance (instance-id, org-id, project-id). Use --create to create a new instance from service.yaml name/region and link it; omit --instance-id when using --create. Org ID is optional when the token has a single organization.';
   static examples = [
@@ -45,7 +47,7 @@ export default class LinkCloud extends CloudInstanceCommand {
     }),
     ...InstanceCommand.flags
   };
-  static summary = 'Link to a PowerSync Cloud instance (or create one with --create).';
+  static summary = '[Cloud only] Link to a PowerSync Cloud instance (or create one with --create).';
 
   async run(): Promise<void> {
     const { flags } = await this.parse(LinkCloud);

diff --git a/cli/src/commands/link/self-hosted.ts b/cli/src/commands/link/self-hosted.ts
@@ -2,6 +2,7 @@ import { input } from '@inquirer/prompts';
 import { Flags, ux } from '@oclif/core';
 import {
   CLI_FILENAME,
+  CommandHelpGroup,
   ensureServiceTypeMatches,
   env,
   InstanceCommand,
@@ -14,6 +15,7 @@ import { join } from 'node:path';
 import { Document } from 'yaml';
 
 export default class LinkSelfHosted extends SelfHostedInstanceCommand {
+  static commandHelpGroup = CommandHelpGroup.PROJECT_SETUP;
   static description = [
     `Links a self hosted PowerSync instance by API URL.`,
     `API Keys can be specified via input or specified in the PS_ADMIN_TOKEN environment variable.`

diff --git a/cli/src/commands/login.ts b/cli/src/commands/login.ts
@@ -1,10 +1,11 @@
 import { confirm, password } from '@inquirer/prompts';
 import { ux } from '@oclif/core';
-import { createAccountsHubClient, PowerSyncCommand, Services } from '@powersync/cli-core';
+import { CommandHelpGroup, createAccountsHubClient, PowerSyncCommand, Services } from '@powersync/cli-core';
 
 import { startPATLoginServer } from '../api/login-server.js';
 
 export default class Login extends PowerSyncCommand {
+  static commandHelpGroup = CommandHelpGroup.AUTHENTICATION;
   static description =
     'Store a PowerSync auth token (PAT) in secure storage so later Cloud commands run without passing a token. If secure storage is unavailable, login can optionally store it in a local config file. Use PS_ADMIN_TOKEN env var for CI or scripts instead.';
   static examples = ['<%= config.bin %> <%= command.id %>'];

diff --git a/cli/src/commands/logout.ts b/cli/src/commands/logout.ts
@@ -1,7 +1,8 @@
 import { ux } from '@oclif/core';
-import { PowerSyncCommand, Services } from '@powersync/cli-core';
+import { CommandHelpGroup, PowerSyncCommand, Services } from '@powersync/cli-core';
 
 export default class Logout extends PowerSyncCommand {
+  static commandHelpGroup = CommandHelpGroup.AUTHENTICATION;
   static description =
     'Remove the stored PowerSync auth token from secure storage or local fallback config storage. Cloud commands will no longer use stored credentials until you run login again.';
   static examples = ['<%= config.bin %> <%= command.id %>'];

diff --git a/cli/src/commands/migrate/sync-rules.ts b/cli/src/commands/migrate/sync-rules.ts
@@ -1,11 +1,11 @@
 import { Flags, ux } from '@oclif/core';
 import { instantiate } from '@powersync-community/sync-config-rewriter';
-import { InstanceCommand, SYNC_FILENAME, YAML_SYNC_RULES_SCHEMA } from '@powersync/cli-core';
+import { SharedInstanceCommand, SYNC_FILENAME, YAML_SYNC_RULES_SCHEMA } from '@powersync/cli-core';
 import { access, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-export default class MigrateSyncRules extends InstanceCommand {
+export default class MigrateSyncRules extends SharedInstanceCommand {
   static description = 'Migrates Sync Rules to Sync Streams';
   static flags = {
     'input-file': Flags.string({
@@ -16,7 +16,7 @@ export default class MigrateSyncRules extends InstanceCommand {
       description: 'Path to the output sync streams file. Defaults to overwrite the input file.',
       required: false
     }),
-    ...InstanceCommand.flags
+    ...SharedInstanceCommand.flags
   };
   static summary = 'Migrates Sync Rules to Sync Streams';
 

diff --git a/cli/src/commands/pull/instance.ts b/cli/src/commands/pull/instance.ts
@@ -2,6 +2,7 @@ import { ux } from '@oclif/core';
 import {
   CLI_FILENAME,
   CloudInstanceCommand,
+  CommandHelpGroup,
   ensureServiceTypeMatches,
   getDefaultOrgId,
   SERVICE_FILENAME,
@@ -26,6 +27,7 @@ const PULL_CONFIG_HEADER = `# PowerSync Cloud config (fetched from cloud)
 `;
 
 export default class PullInstance extends CloudInstanceCommand {
+  static commandHelpGroup = CommandHelpGroup.PROJECT_SETUP;
   static description =
     'Fetch an existing Cloud instance by ID: create the config directory if needed, write cli.yaml, and download service.yaml and sync-config.yaml. Pass --instance-id and --project-id when the directory is not yet linked; --org-id is optional when the token has a single organization. Cloud only.';
   static examples = [
@@ -37,7 +39,7 @@ export default class PullInstance extends CloudInstanceCommand {
     ...CloudInstanceCommand.flags
   };
   static summary =
-    'Pull an existing Cloud instance: link and download config into local service.yaml and sync-config.yaml.';
+    '[Cloud only] Pull an existing Cloud instance: link and download config into local service.yaml and sync-config.yaml.';
 
   async run(): Promise<void> {
     const { flags } = await this.parse(PullInstance);