wip: cleanup commands and topics

Author: stevensJourney

cli/README.md

@@ -75,20 +75,26 @@
     ],
     "topicSeparator": " ",
     "topics": {
+      "deploy": {
+        "description": "[Cloud only] Deploy local config changes to the Cloud instance. Run \"powersync deploy --help\" to list subcommands."
+      },
       "fetch": {
-        "description": "run \"powersync fetch\" to see a list of subcommands"
+        "description": "Inspect Cloud instances and configuration (instances, config, status). Run \"powersync fetch --help\" to list subcommands."
       },
       "generate": {
-        "description": "run \"powersync generate\" to see a list of subcommands"
+        "description": "Generate client artifacts from instance/config data (schema, token). Run \"powersync generate --help\" to list subcommands."
       },
       "init": {
-        "description": "run \"powersync init\" to see a list of subcommands"
+        "description": "Scaffold a new PowerSync project configuration from templates. Run \"powersync init --help\" to list subcommands."
       },
       "link": {
-        "description": "run \"powersync link\" to see a list of subcommands"
+        "description": "Bind this directory to a Cloud or self-hosted instance (writes cli.yaml). Run \"powersync link --help\" to list subcommands."
+      },
+      "migrate": {
+        "description": "Migrate config to newer formats (for example Sync Rules to Sync Streams). Run \"powersync migrate --help\" to list subcommands."
       },
       "pull": {
-        "description": "run \"powersync pull\" to see a list of subcommands"
+        "description": "[Cloud only] Download Cloud instance configuration into local files. Run \"powersync pull --help\" to list subcommands."
       }
     }
   },

cli/package.json

@@ -12,7 +12,7 @@ export class DeploySyncConfig extends DeployAll {
   static flags = {
     ...DeployAll.flags
   };
-  static summary = '[Cloud only] Deploy local sync config to the linked Cloud instance.';
+  static summary = '[Cloud only] Deploy only local sync config to the linked Cloud instance.';
 
   /**
    * Deploys only the sync config.

cli/src/commands/deploy/sync-config.ts

@@ -10,6 +10,7 @@ export default class Fetch extends Command {
   static description =
     'Subcommands: list Cloud instances in org/project (fetch instances), print instance config as YAML/JSON (fetch config), or show instance diagnostics (fetch status).';
   static examples = ['<%= config.bin %> <%= command.id %>'];
+  static hidden = true;
   static summary = 'List instances, fetch config, or fetch instance diagnostics.';
 
   async run(): Promise<void> {

cli/src/commands/fetch/index.ts

@@ -4,6 +4,7 @@ export default class Generate extends Command {
   static description =
     'Generate client artifacts: schema (from instance schema + sync config) or a development token for connecting clients. Cloud and self-hosted where supported.';
   static examples = ['<%= config.bin %> <%= command.id %>'];
+  static hidden = true;
   static summary = 'Generate client schema or development token.';
 
   async run(): Promise<void> {

cli/src/commands/generate/index.ts

@@ -4,6 +4,7 @@ export default class Init extends Command {
   static description =
     'Scaffold a PowerSync config directory from a template. Use init cloud or init self-hosted. For Cloud, edit service.yaml then run link cloud and deploy.';
   static examples = ['<%= config.bin %> <%= command.id %>'];
+  static hidden = true;
   static summary = 'Scaffold a PowerSync config directory from a template.';
 
   async run(): Promise<void> {

cli/src/commands/init/index.ts

@@ -4,6 +4,7 @@ export default class Link extends Command {
   static description =
     "Write cli.yaml so this directory's config is bound to a PowerSync instance. Once linked, commands use that instance without passing IDs. Use link cloud or link self-hosted.";
   static examples = ['<%= config.bin %> <%= command.id %>'];
+  static hidden = true;
   static summary = 'Bind this directory to a Cloud or self-hosted instance (writes cli.yaml).';
 
   async run(): Promise<void> {

cli/src/commands/link/index.ts

@@ -3,6 +3,7 @@ import { Command, ux } from '@oclif/core';
 export default class Migrate extends Command {
   static description =
     'Migrate PowerSync config to newer formats. Use migrate sync-rules to convert Sync Rules to Sync Streams.';
+  static hidden = true;
   static summary = 'Migrate config to newer formats (e.g. Sync Rules → Sync Streams).';
 
   async run(): Promise<void> {

cli/src/commands/migrate/index.ts

@@ -4,6 +4,7 @@ export default class Pull extends Command {
   static description =
     'Download current config from PowerSync Cloud into local YAML files. Use pull instance; pass --instance-id and --project-id when the directory is not yet linked (--org-id is optional when the token has a single organization).';
   static examples = ['<%= config.bin %> <%= command.id %>'];
+  static hidden = true;
   static summary = '[Cloud only] Download Cloud config into local service.yaml and sync.yaml.';
 
   async run(): Promise<void> {

cli/src/commands/pull/index.ts

@@ -17,13 +17,12 @@ This document describes how we document commands and help text in the PowerSync
 - Use sentence case (e.g. "Optionally write instance information to a file." not "Optionally Write...").
 - For optional/override flags, mention resolution order when helpful (e.g. "Resolved: flag → INSTANCE_ID → cli.yaml.").
 
-## Topics (package.json)
+## Topic index commands
 
-In `cli/package.json`, under `oclif.topics`, add an entry for each topic (e.g. `fetch`, `generate`, `init`, `link`, `pull`, `deploy`) with a description that directs users to run the topic command to see subcommands, e.g.:
+For grouped commands (e.g. `fetch`, `generate`, `init`, `link`, `pull`, `migrate`), use an `index.ts` command that prints available subcommands when run directly.
 
-```json
-"fetch": { "description": "run \"powersync fetch\" to see a list of subcommands" }
-```
+- Mark these index commands as hidden (`static hidden = true`) so they do not appear as separate entries in generated command lists.
+- Add matching `oclif.topics` entries in `cli/package.json` with a short purpose summary plus guidance in this form: `... Run "powersync <topic> --help" to list subcommands.`
 
 ## README