feat: custom help

[stevensJourney]

This add a custom help parser, which allows displaying better tailored command help.

Sample output

❯ powersync help
A CLI for managing PowerSync instances

VERSION
  powersync/0.0.0 darwin-arm64 node-v24.13.0

USAGE
  $ powersync [COMMAND]

GENERAL COMMANDS
  fetch instances   List Cloud and linked instances.

  init cloud        Scaffold a PowerSync Cloud config directory from a template.
  init self-hosted  Scaffold a PowerSync self-hosted config directory from a template.

  login             Store auth token for Cloud commands.

  logout            Remove stored auth token.

CLOUD COMMANDS
  deploy                 Deploy local config to the linked Cloud instance (connections + auth + sync config).
  deploy service-config  Deploy only local service config to the linked Cloud instance.
  deploy sync-config     Deploy only local sync config to the linked Cloud instance.

  destroy                Permanently destroy the linked Cloud instance.

  fetch config           Print linked Cloud instance config (YAML or JSON).

  link cloud             Link to a PowerSync Cloud instance (or create one with --create).

  pull instance          Pull an existing Cloud instance: link and download config into local service.yaml and sync-config.yaml.

  stop                   Stop the linked Cloud instance (restart with deploy).

SHARED COMMANDS
  fetch status        Show instance diagnostics (connections, sync config, replication).

  generate schema     Generate client schema file from instance schema and sync config.
  generate token      Generate a development JWT for client connections.

  migrate sync-rules  Migrates Sync Rules to Sync Streams

  status              Show instance diagnostics (connections, sync config, replication).

  validate            Validate config schema, connections, and sync config before deploy.

SELF-HOSTED COMMANDS
  docker configure  Configures a self hosted project with Docker Compose services.
  docker reset      Reset the self-hosted PowerSync stack (stop and remove, then start).
  docker start      Start the self-hosted PowerSync stack via Docker Compose.
  docker stop       Stop a PowerSync Docker Compose project by name.

  link self-hosted  Link to a self-hosted PowerSync instance by API URL.

OTHER COMMANDS
  autocomplete       Display autocomplete installation instructions.

  commands           List all powersync commands.

  help               Display help for powersync.

  plugins            List installed plugins.
  plugins add        Installs a plugin into powersync.
  plugins inspect    Displays installation properties of a plugin.
  plugins install    Installs a plugin into powersync.
  plugins link       Links a plugin into the CLI for development.
  plugins remove     Removes a plugin from the CLI.
  plugins reset      Remove all user-installed and linked plugins.
  plugins uninstall  Removes a plugin from the CLI.
  plugins unlink     Removes a plugin from the CLI.
  plugins update     Update installed plugins.

[Copilot]

Pull request overview

Adds a custom Oclif help implementation to improve root (powersync --help) output by presenting a flatter, more tailored command list and separating first-party commands from plugin/other commands.

Changes:

• Introduces a custom Help subclass (PowerSyncHelp) to override root help rendering.
• Adds a Vitest test validating the new root help layout/sections.
• Wires the custom help class into Oclif via oclif.helpClass in cli/package.json.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
cli/src/help.ts	New custom help renderer for root help output (grouping + sectioning).
cli/test/commands/help.test.ts	New test asserting root help shows flattened commands and expected sections.
cli/package.json	Configures Oclif to use the compiled custom help class via helpClass.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[benitav]

This is great overall!

I want to propose this grouping that mainly has more use-case based headings (shared, general, other all seemed a bit vague):

AUTHENTICATION
  login               Store auth token for Cloud commands.
  logout              Remove stored auth token.

PROJECT SETUP
  init cloud          Scaffold a PowerSync Cloud config directory from a template.
  init self-hosted    Scaffold a PowerSync self-hosted config directory from a template.
  link cloud          Link to a PowerSync Cloud instance (or create one with --create).
  link self-hosted    Link to a self-hosted PowerSync instance by API URL.
  pull instance       Pull an existing Cloud instance: link and download config into local service.yaml and sync-config.yaml.

CLOUD COMMANDS
  deploy              Deploy local config to the linked Cloud instance (connections + auth + sync config).
  deploy service-config  Deploy only local service config to the linked Cloud instance.
  deploy sync-config  Deploy only local sync config to the linked Cloud instance.

  destroy             Permanently destroy the linked Cloud instance.

  fetch config        Print linked Cloud instance config (YAML or JSON).
  fetch instances     List Cloud and linked instances.

  stop                Stop the linked Cloud instance (restart with deploy).

INSTANCE COMMANDS
  fetch status        Show instance diagnostics (connections, sync config, replication).

  generate schema     Generate client schema file from instance schema and sync config.
  generate token      Generate a development JWT for client connections.

  migrate sync-rules  Migrates Sync Rules to Sync Streams.

  status              Show instance diagnostics (connections, sync config, replication).

  validate            Validate config schema, connections, and sync config before deploy.

LOCAL DEVELOPMENT
  docker configure    Configures a self-hosted project with Docker Compose services.
  docker reset        Reset the self-hosted PowerSync stack (stop and remove, then start).
  docker start        Start the self-hosted PowerSync stack via Docker Compose.
  docker stop         Stop a PowerSync Docker Compose project by name.

ADDITIONAL COMMANDS
  autocomplete        Display autocomplete installation instructions.

  commands            List all powersync commands.

  help                Display help for powersync.

  plugins             List installed plugins.
  plugins add         Installs a plugin into powersync.
  plugins inspect     Displays installation properties of a plugin.
  plugins install     Installs a plugin into powersync.
  plugins link        Links a plugin into the CLI for development.
  plugins remove      Removes a plugin from the CLI.
  plugins reset       Remove all user-installed and linked plugins.
  plugins uninstall   Removes a plugin from the CLI.
  plugins unlink      Removes a plugin from the CLI.
  plugins update      Update installed plugins.

[stevensJourney]

This is great overall!

I want to propose this grouping that mainly has more use-case based headings (shared, general, other all seemed a bit vague):

@benitav That sounds like a good idea. I've implemented this.. Here is the new output

❯ powersync
A CLI for managing PowerSync instances

VERSION
  powersync/0.0.0 darwin-arm64 node-v24.13.0

USAGE
  $ powersync [COMMAND]

AUTHENTICATION COMMANDS
  login   Store auth token for Cloud commands.

  logout  Remove stored auth token.

PROJECT SETUP COMMANDS
  configure ide     Configure your IDE for the best PowerSync CLI developer experience.
  init cloud        Scaffold a PowerSync Cloud config directory from a template.
  init self-hosted  Scaffold a PowerSync self-hosted config directory from a template.

  link cloud        Link to a PowerSync Cloud instance (or create one with --create).
  link self-hosted  Link to a self-hosted PowerSync instance by API URL.

  pull instance     Pull an existing Cloud instance: link and download config into local service.yaml and sync-config.yaml.

CLOUD COMMANDS
  deploy                 Deploy local config to the linked Cloud instance (connections + auth + sync config).
  deploy service-config  Deploy only local service config to the linked Cloud instance.
  deploy sync-config     Deploy only local sync config to the linked Cloud instance.

  destroy                Permanently destroy the linked Cloud instance.

  fetch config           Print linked Cloud instance config (YAML or JSON).
  fetch instances        List Cloud and linked instances.

  stop                   Stop the linked Cloud instance (restart with deploy).

INSTANCE COMMANDS
  edit config         Open the PowerSync configuration editor (Nitro server).

  fetch status        Show instance diagnostics (connections, sync config, replication).

  generate schema     Generate client schema file from instance schema and sync config.
  generate token      Generate a development JWT for client connections.

  migrate sync-rules  Migrates Sync Rules to Sync Streams

  status              Show instance diagnostics (connections, sync config, replication).

  validate            Validate config schema, connections, and sync config before deploy.

LOCAL DEVELOPMENT COMMANDS
  docker configure  Configures a self hosted project with Docker Compose services.
  docker reset      Reset the self-hosted PowerSync stack (stop and remove, then start).
  docker start      Start the self-hosted PowerSync stack via Docker Compose.
  docker stop       Stop a PowerSync Docker Compose project by name.

ADDITIONAL COMMANDS
  autocomplete       Display autocomplete installation instructions.

  commands           List all powersync commands.

  help               Display help for powersync.

  plugins            List installed plugins.
  plugins add        Installs a plugin into powersync.
  plugins inspect    Displays installation properties of a plugin.
  plugins install    Installs a plugin into powersync.
  plugins link       Links a plugin into the CLI for development.
  plugins remove     Removes a plugin from the CLI.
  plugins reset      Remove all user-installed and linked plugins.
  plugins uninstall  Removes a plugin from the CLI.
  plugins unlink     Removes a plugin from the CLI.
  plugins update     Update installed plugins.