feat: improve CLI help output (#4)

Adds example commands to help output, fixes usage line, corrects
subcommand ordering, and makes version dynamic from package.json.

Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>

Author: bensabic

README.md

@@ -31,7 +31,7 @@ memberstack whoami
 ## Usage
 
 ```bash
-memberstack <command> <subcommand> [options]
+memberstack <command> [subcommand] [params] [options]
 ```
 
 ## Install Agent Skill (Optional)

src/commands/apps.ts

@@ -37,7 +37,9 @@ const APP_FIELDS = `
   allowMemberSelfDelete
 `;
 
-export const appsCommand = new Command("apps").description("Manage apps");
+export const appsCommand = new Command("apps")
+  .usage("<command> [options]")
+  .description("Manage apps");
 
 appsCommand
   .command("current")

src/commands/auth.ts

@@ -110,9 +110,9 @@ const findAvailablePort = (): Promise<number> =>
     server.on("error", reject);
   });
 
-export const authCommand = new Command("auth").description(
-  "Manage OAuth authentication"
-);
+export const authCommand = new Command("auth")
+  .usage("<command> [options]")
+  .description("Manage OAuth authentication");
 
 authCommand
   .command("login")

src/commands/custom-fields.ts

@@ -32,9 +32,9 @@ const CUSTOM_FIELD_FIELDS = `
   tableOrder
 `;
 
-export const customFieldsCommand = new Command("custom-fields").description(
-  "Manage custom fields"
-);
+export const customFieldsCommand = new Command("custom-fields")
+  .usage("<command> [options]")
+  .description("Manage custom fields");
 
 customFieldsCommand
   .command("list")

src/commands/members.ts

@@ -194,9 +194,9 @@ const collect = (value: string, previous: string[]): string[] => [
   value,
 ];
 
-export const membersCommand = new Command("members").description(
-  "Manage members"
-);
+export const membersCommand = new Command("members")
+  .usage("<command> [options]")
+  .description("Manage members");
 
 membersCommand
   .command("list")

src/commands/plans.ts

@@ -140,7 +140,9 @@ const parseRedirects = (entries: string[]): Record<string, string> => {
   return redirects;
 };
 
-export const plansCommand = new Command("plans").description("Manage plans");
+export const plansCommand = new Command("plans")
+  .usage("<command> [options]")
+  .description("Manage plans");
 
 plansCommand
   .command("list")

src/commands/records.ts

@@ -72,9 +72,9 @@ const resolveTableId = async (tableKey: string): Promise<string> => {
   return result.dataTable.id;
 };
 
-export const recordsCommand = new Command("records").description(
-  "Manage data table records"
-);
+export const recordsCommand = new Command("records")
+  .usage("<command> [options]")
+  .description("Manage data table records");
 
 recordsCommand
   .command("create")

src/commands/skills.ts

@@ -12,9 +12,9 @@ const runSkillsCommand = async (args: string[]): Promise<void> => {
   await execAsync(`npx skills ${args.join(" ")}`);
 };
 
-export const skillsCommand = new Command("skills").description(
-  "Manage Memberstack skills"
-);
+export const skillsCommand = new Command("skills")
+  .usage("<command> [options]")
+  .description("Manage Memberstack skills");
 
 skillsCommand
   .command("add")

src/commands/tables.ts

@@ -61,9 +61,9 @@ const TABLE_FIELDS = `
   }
 `;
 
-export const tablesCommand = new Command("tables").description(
-  "Manage data tables"
-);
+export const tablesCommand = new Command("tables")
+  .usage("<command> [options]")
+  .description("Manage data tables");
 
 tablesCommand
   .command("list")

src/lib/program.ts

@@ -1,10 +1,24 @@
 import { Command } from "commander";
 
+declare const __VERSION__: string | undefined;
+const version = typeof __VERSION__ !== "undefined" ? __VERSION__ : "dev";
+
 export const program = new Command();
 
 program
-  .name("Memberstack CLI")
+  .name("memberstack")
+  .usage("<command> [subcommand] [params] [options]")
   .description("Manage your Memberstack account from the terminal.")
-  .version("0.0.0")
+  .version(version)
   .option("-j, --json", "Output raw JSON instead of formatted tables")
-  .option("--live", "Use live environment instead of sandbox");
+  .option("--live", "Use live environment instead of sandbox")
+  .addHelpText(
+    "after",
+    `
+Examples:
+  $ memberstack auth login
+  $ memberstack members list --json
+  $ memberstack plans create --name "Pro Plan"
+  $ memberstack records find users --where "status equals active"
+  $ memberstack skills add memberstack-cli`
+  );