update commands' descriptions

stevensJourney · stevensJourney · commit 321591cf9224 · 2026-02-06T13:59:58.000+02:00
diff --git a/packages/cli/README.md b/packages/cli/README.md
diff --git a/packages/cli/src/commands/deploy.ts b/packages/cli/src/commands/deploy.ts
@@ -31,8 +31,9 @@ async function waitForStatusChange(
 }
 
 export default class Deploy extends CloudInstanceCommand {
-  static description = 'Deploys changes to the PowerSync management service. Cloud only.';
-  static summary = 'Deploy sync rules and configuration changes.';
+  static description =
+    'Push local config (service.yaml, sync rules) to the linked PowerSync Cloud instance. Tests connections and sync rules first; requires a linked project. Cloud only.';
+  static summary = 'Push local config to the linked Cloud instance (connections + sync rules).';
 
   static flags = {
     ...CloudInstanceCommand.flags
diff --git a/packages/cli/src/commands/destroy.ts b/packages/cli/src/commands/destroy.ts
@@ -3,8 +3,9 @@ import { Flags } from '@oclif/core';
 import { CloudInstanceCommand } from '../command-types/CloudInstanceCommand.js';
 
 export default class Destroy extends CloudInstanceCommand {
-  static description = 'Destroys the linked PowerSync Cloud instance. Cloud only.';
-  static summary = 'Destroy a PowerSync instance.';
+  static description =
+    'Permanently delete the linked PowerSync Cloud instance and its data. Requires --confirm=yes. Cloud only.';
+  static summary = 'Permanently destroy the linked Cloud instance.';
 
   static flags = {
     confirm: Flags.string({
diff --git a/packages/cli/src/commands/fetch/config.ts b/packages/cli/src/commands/fetch/config.ts
@@ -5,8 +5,9 @@ import { fetchCloudConfig } from '../../api/cloud/fetch-cloud-config.js';
 import { CloudInstanceCommand } from '../../command-types/CloudInstanceCommand.js';
 
 export default class FetchConfig extends CloudInstanceCommand {
-  static description = 'Fetches instance config from PowerSync Cloud. Requires a linked project. Cloud only.';
-  static summary = 'Fetch config from cloud (output as yaml or json).';
+  static description =
+    'Retrieve the current instance config from PowerSync Cloud and print as YAML or JSON. Uses linked project or --instance-id, --org-id, --project-id. Cloud only.';
+  static summary = 'Print linked Cloud instance config (YAML or JSON).';
 
   static flags = {
     output: Flags.string({
diff --git a/packages/cli/src/commands/fetch/index.ts b/packages/cli/src/commands/fetch/index.ts
@@ -1,8 +1,9 @@
 import { Command } from '@oclif/core';
 
 export default class Fetch extends Command {
-  static description = 'Commands to list instances, fetch config, or get diagnostics status.';
-  static summary = 'Fetch data from PowerSync (instances, config, status).';
+  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 summary = 'List instances, fetch config, or fetch instance diagnostics.';
 
   async run(): Promise<void> {
     await this.parse(Fetch);
diff --git a/packages/cli/src/commands/fetch/instances.ts b/packages/cli/src/commands/fetch/instances.ts
@@ -1,10 +1,11 @@
-import {Command} from '@oclif/core'
+import { Command } from '@oclif/core';
 
 export default class FetchInstances extends Command {
-  static description = 'Lists instances in the current org/project. Cloud only.'
-  static summary = 'List PowerSync Cloud instances.'
+  static description =
+    'List PowerSync Cloud instances in the current org and project. Use with a linked directory or pass --org-id and --project-id. Cloud only.';
+  static summary = 'List Cloud instances in the current org/project.';
 
   async run(): Promise<void> {
-    this.log('fetch instances: not yet implemented')
+    this.log('fetch instances: not yet implemented');
   }
 }
diff --git a/packages/cli/src/commands/fetch/status.ts b/packages/cli/src/commands/fetch/status.ts
@@ -115,8 +115,8 @@ function formatDiagnosticsHuman(diagnostics: DiagnosticsResponse): string {
 
 export default class FetchStatus extends SharedInstanceCommand {
   static description =
-    'Fetches diagnostics (connections, sync rules state, etc.). Routes to Management service (Cloud) or linked instance (self-hosted).';
-  static summary = 'Fetch diagnostics status for an instance.';
+    'Fetch instance diagnostics: connection status, active and deploying sync rules, replication state. Output as human-readable, JSON, or YAML. Cloud and self-hosted.';
+  static summary = 'Show instance diagnostics (connections, sync rules, replication).';
 
   static flags = {
     output: Flags.string({
diff --git a/packages/cli/src/commands/generate/index.ts b/packages/cli/src/commands/generate/index.ts
@@ -1,11 +1,12 @@
-import {Command} from '@oclif/core'
+import { Command } from '@oclif/core';
 
 export default class Generate extends Command {
-  static description = 'Commands to generate client-side schema or development tokens.'
-  static summary = 'Generate artifacts (schema, token).'
+  static description =
+    'Generate client artifacts: schema (from instance schema + sync rules) or a development token for connecting clients. Cloud and self-hosted where supported.';
+  static summary = 'Generate client schema or development token.';
 
   async run(): Promise<void> {
-    await this.parse(Generate)
-    this.log('Use a subcommand: generate schema | generate token')
+    await this.parse(Generate);
+    this.log('Use a subcommand: generate schema | generate token');
   }
 }
diff --git a/packages/cli/src/commands/generate/schema.ts b/packages/cli/src/commands/generate/schema.ts
@@ -12,8 +12,8 @@ import { SharedInstanceCommand } from '../../command-types/SharedInstanceCommand
 
 export default class GenerateSchema extends SharedInstanceCommand {
   static description =
-    'Generates client-side schema from instance schema and sync rules. Supported for Cloud and self-hosted.';
-  static summary = 'Create client-side schemas.';
+    'Generate a client-side schema file from the instance database schema and sync rules. Supports multiple output types (e.g. type, dart). Requires a linked instance. Cloud and self-hosted.';
+  static summary = 'Generate client schema file from instance schema and sync rules.';
 
   static flags = {
     output: Flags.string({
diff --git a/packages/cli/src/commands/generate/token.ts b/packages/cli/src/commands/generate/token.ts
@@ -13,8 +13,8 @@ type TokenConfig = {
 
 export default class GenerateToken extends SharedInstanceCommand {
   static description =
-    'Generates a development token for connecting clients. Cloud and self-hosted (when shared secret is in config).';
-  static summary = 'Create a client token for the PowerSync service.';
+    'Generate a JWT for development clients to connect to PowerSync. Cloud: uses instance dev-token API (allow_temporary_tokens must be enabled). Self-hosted: signs with shared secret from config. Requires --subject; optional --expires-in-seconds.';
+  static summary = 'Generate a development JWT for client connections.';
 
   static flags = {
     subject: Flags.string({
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
@@ -13,16 +13,16 @@ const TEMPLATES_DIR = join(__dirname, '..', '..', 'templates');
 
 export default class Init extends PowerSyncCommand {
   static description =
-    'Creates a new PowerSync project in the current directory. Supports --type=cloud or self-hosted.';
+    'Copy a template into a config directory (default powersync/). Use --type=cloud or --type=self-hosted. For Cloud, edit service.yaml then run link cloud and deploy.';
   static flags = {
     type: Flags.string({
       default: 'cloud',
-      description: 'Type of PowerSync instance to scaffold.',
+      description: 'Type of PowerSync instance to scaffold (cloud or self-hosted).',
       options: ['cloud', 'self-hosted']
     }),
     ...InstanceCommand.flags
   };
-  static summary = 'Create a new PowerSync project.';
+  static summary = 'Scaffold a PowerSync config directory from a template.';
 
   async run(): Promise<void> {
     const { flags } = await this.parse(Init);
diff --git a/packages/cli/src/commands/link/cloud.ts b/packages/cli/src/commands/link/cloud.ts
@@ -9,26 +9,27 @@ import { env } from '../../utils/env.js';
 import { LINK_FILENAME } from '../../utils/project-config.js';
 
 export default class LinkCloud extends CloudInstanceCommand {
-  static description = 'Link this directory to a PowerSync Cloud instance.';
-  static summary = 'Link to PowerSync Cloud (instance ID, org, project).';
+  static description =
+    'Write or update link.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.';
+  static summary = 'Link to a PowerSync Cloud instance (or create one with --create).';
   static flags = {
     create: Flags.boolean({
       description:
         'Create a new Cloud instance in the given org and project, then link. Do not supply --instance-id when using --create.',
       default: false
     }),
     'instance-id': Flags.string({
-      description: 'PowerSync Cloud instance ID. Omit when using --create.',
+      description: 'PowerSync Cloud instance ID. Omit when using --create. Resolved: flag → INSTANCE_ID → link.yaml.',
       default: env.INSTANCE_ID,
       required: false
     }),
     'org-id': Flags.string({
-      description: 'Organization ID.',
+      description: 'Organization ID. Resolved: flag → ORG_ID → link.yaml.',
       default: env.ORG_ID,
       required: true
     }),
     'project-id': Flags.string({
-      description: 'Project ID.',
+      description: 'Project ID. Resolved: flag → PROJECT_ID → link.yaml.',
       default: env.PROJECT_ID,
       required: true
     }),
diff --git a/packages/cli/src/commands/link/index.ts b/packages/cli/src/commands/link/index.ts
@@ -2,8 +2,8 @@ import { Command } from '@oclif/core';
 
 export default class Link extends Command {
   static description =
-    "Associates a PowerSync instance with this directory's config. Use a subcommand for cloud or self-hosted.";
-  static summary = 'Link configuration to a PowerSync instance.';
+    "Write link.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 summary = 'Bind this directory to a Cloud or self-hosted instance (writes link.yaml).';
   async run(): Promise<void> {
     await this.parse(Link);
     this.log('Use a subcommand: link cloud | link self-hosted');
diff --git a/packages/cli/src/commands/link/self-hosted.ts b/packages/cli/src/commands/link/self-hosted.ts
@@ -9,8 +9,9 @@ import { ensureServiceTypeMatches } from '../../utils/ensureServiceType.js';
 import { LINK_FILENAME, loadLinkDocument } from '../../utils/project-config.js';
 
 export default class LinkSelfHosted extends SelfHostedInstanceCommand {
-  static description = 'Link this directory to a self-hosted PowerSync instance.';
-  static summary = 'Link to self-hosted PowerSync (API URL; API key from PS_TOKEN env).';
+  static description =
+    'Write or update link.yaml with a self-hosted instance (API URL). You will be prompted for API key; use !env PS_TOKEN so commands read the key from the environment.';
+  static summary = 'Link to a self-hosted PowerSync instance by API URL.';
   static flags = {
     'api-url': Flags.string({
       description: 'Self-hosted PowerSync API base URL (e.g. https://powersync.example.com).',
diff --git a/packages/cli/src/commands/login.ts b/packages/cli/src/commands/login.ts
@@ -4,8 +4,9 @@ import { Command } from '@oclif/core';
 import { getSecureStorage } from '../services/SecureStorage.js';
 
 export default class Login extends Command {
-  static description = 'Authenticate the CLI with PowerSync (e.g. PAT token).';
-  static summary = 'Authenticate the CLI with PowerSync (e.g. PAT token).';
+  static description =
+    'Store a PowerSync auth token (PAT) in secure storage so later Cloud commands run without passing a token. Use PS_TOKEN env var for CI or scripts instead.';
+  static summary = 'Store auth token in secure storage for Cloud commands.';
 
   async run(): Promise<void> {
     const token = await password({
diff --git a/packages/cli/src/commands/migrate.ts b/packages/cli/src/commands/migrate.ts
@@ -1,8 +1,9 @@
 import { SelfHostedInstanceCommand } from '../command-types/SelfHostedInstanceCommand.js';
 
 export default class Migrate extends SelfHostedInstanceCommand {
-  static description = 'Migrates a self-hosted instance configuration to PowerSync Cloud format. Self-hosted only.';
-  static summary = 'Migrate a self-hosted config to a cloud config.';
+  static description =
+    'Convert a self-hosted service.yaml to PowerSync Cloud format. Self-hosted only. (Not yet implemented.)';
+  static summary = 'Convert self-hosted config to Cloud format (not yet implemented).';
 
   async run(): Promise<void> {
     this.log('migrate: not yet implemented');
diff --git a/packages/cli/src/commands/pull/config.ts b/packages/cli/src/commands/pull/config.ts
@@ -79,8 +79,8 @@ function formatServiceYamlWithComments(config: t.Decoded<typeof CLICloudConfig>)
 
 export default class PullConfig extends CloudInstanceCommand {
   static description =
-    'Pulls instance config from PowerSync Cloud and writes to local files. If not already linked, use --instance-id, --org-id, --project-id to link first. Cloud only.';
-  static summary = 'Pull config from cloud (link first if needed).';
+    'Fetch instance config and sync rules from PowerSync Cloud and write to service.yaml and sync.yaml in the config directory. Writes link.yaml if you pass --instance-id, --org-id, --project-id. Cloud only.';
+  static summary = 'Download Cloud config and sync rules into local service.yaml and sync.yaml.';
 
   static flags = {
     ...CloudInstanceCommand.flags
diff --git a/packages/cli/src/commands/pull/index.ts b/packages/cli/src/commands/pull/index.ts
@@ -1,8 +1,9 @@
 import { Command } from '@oclif/core';
 
 export default class Pull extends Command {
-  static description = 'Pull config from PowerSync Cloud (optionally link first if not already linked).';
-  static summary = 'Pull config; link if needed.';
+  static description =
+    'Download current config from PowerSync Cloud into local YAML files. Use pull config; pass --instance-id, --org-id, --project-id to link first if not already linked.';
+  static summary = 'Download Cloud config into local service.yaml and sync.yaml.';
 
   async run(): Promise<void> {
     await this.parse(Pull);
diff --git a/packages/cli/src/commands/stop.ts b/packages/cli/src/commands/stop.ts
@@ -4,8 +4,8 @@ import { CloudInstanceCommand } from '../command-types/CloudInstanceCommand.js';
 
 export default class Stop extends CloudInstanceCommand {
   static description =
-    'Stops the linked PowerSync Cloud instance. Cloud only. The instance can be started again by running `powersync deploy`.';
-  static summary = 'Stop a PowerSync instance.';
+    'Deactivate the linked PowerSync Cloud instance. Requires --confirm=yes. Restart later with powersync deploy. Cloud only.';
+  static summary = 'Stop the linked Cloud instance (restart with deploy).';
 
   static flags = {
     confirm: Flags.string({
diff --git a/packages/cli/src/commands/validate.ts b/packages/cli/src/commands/validate.ts
@@ -160,8 +160,9 @@ async function runSyncRulesTestSelfHosted(project: SelfHostedProject): Promise<V
 }
 
 export default class Validate extends SharedInstanceCommand {
-  static description = 'Validates configuration. Supported for both Cloud and self-hosted.';
-  static summary = 'Validate configuration (sync rules, connection, etc.).';
+  static description =
+    'Run validation checks on local config: config schema, database connections, and sync rules. Requires a linked instance. Works with Cloud and self-hosted.';
+  static summary = 'Validate config schema, connections, and sync rules before deploy.';
 
   static flags = {
     output: Flags.string({
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -1,10 +1,11 @@`
`1`		`-import {Command} from '@oclif/core'`
	`1`	`+import { Command } from '@oclif/core';`
`2`	`2`
`3`	`3`	`export default class FetchInstances extends Command {`
`4`		`- static description = 'Lists instances in the current org/project. Cloud only.'`
`5`		`- static summary = 'List PowerSync Cloud instances.'`
	`4`	`+ static description =`
	`5`	`+ 'List PowerSync Cloud instances in the current org and project. Use with a linked directory or pass --org-id and --project-id. Cloud only.';`
	`6`	`+ static summary = 'List Cloud instances in the current org/project.';`
`6`	`7`
`7`	`8`	`async run(): Promise<void> {`
`8`		`- this.log('fetch instances: not yet implemented')`
	`9`	`+ this.log('fetch instances: not yet implemented');`
`9`	`10`	`}`
`10`	`11`	`}`