feat: enrich help text

kevzzsk · kevzzsk · commit eb14415fa0d3 · 2026-03-24T12:24:51.000+08:00
diff --git a/packages/use-agently/src/cli.ts b/packages/use-agently/src/cli.ts
@@ -51,6 +51,32 @@ cli.addCommand(initCommand.helpGroup("Lifecycle"));
 cli.addCommand(walletCommand.helpGroup("Lifecycle"));
 cli.addCommand(updateCommand.helpGroup("Lifecycle"));
 
+cli.addHelpText(
+  "after",
+  `
+Protocol Quick Reference:
+
+  a2a send  -u <uri> -m <message> [--pay]    Send a message via A2A
+  a2a card  -u <uri>                          Fetch an agent's A2A card
+
+  mcp tools -u <uri>                          List tools on an MCP server
+  mcp call  -u <uri> --tool <name> [--args <json>] [--pay]
+                                              Call a tool on an MCP server
+
+  web get|post|put|patch|delete <url> [options]
+            [-d <body>] [-H <header>] [-v] [--pay]
+                                              HTTP requests with x402 support
+
+  wallet spend                                View current spend limit
+  wallet spend set-max <value>                Set max USD spend per call (0–1)
+
+  <uri> can be an HTTP URL or a CAIP-19 ID (e.g. eip155:8453/erc8004:0x…/1)
+
+  Getting started: use-agently init → use-agently doctor → use-agently search
+
+  Run "use-agently <command> -h" for full option details.`,
+);
+
 // Propagate showGlobalOptions to all subcommands added via addCommand(),
 // which does not inherit configureHelp from the parent.
 function enableGlobalOptionsInHelp(cmd: Command) {
diff --git a/packages/use-agently/src/commands/a2a.ts b/packages/use-agently/src/commands/a2a.ts
@@ -36,6 +36,10 @@ async function resolveTransactionMode(pay?: boolean): Promise<{ client: unstable
 
 export const a2aCommand = new Command("a2a")
   .description("Send messages and fetch agent cards via the A2A protocol")
+  .addHelpText(
+    "after",
+    '\nExamples:\n  use-agently a2a send --uri <uri> -m "Hello!"\n  use-agently a2a card --uri <uri>',
+  )
   .action(function () {
     (this as Command).outputHelp();
   });
diff --git a/packages/use-agently/src/commands/balance.ts b/packages/use-agently/src/commands/balance.ts
@@ -7,6 +7,7 @@ export const balanceCommand = new Command("balance")
   .description("Check wallet balance on-chain")
   .option("--rpc <url>", "Custom RPC URL")
   .showHelpAfterError(true)
+  .addHelpText("after", "\nExamples:\n  use-agently balance")
   .action(async (options: { rpc?: string }, command: Command) => {
     const config = await getConfigOrThrow();
     const wallet = loadWallet(config.wallet);
diff --git a/packages/use-agently/src/commands/doctor.ts b/packages/use-agently/src/commands/doctor.ts
@@ -15,7 +15,10 @@ export const doctorCommand = new Command("doctor")
   .description("Run environment checks and report any issues")
   .option("--rpc <url>", "Custom RPC URL to use for network check")
   .showHelpAfterError(true)
-  .addHelpText("after", "\nConfig: ~/.use-agently/config.json (global), .use-agently/config.json (local)")
+  .addHelpText(
+    "after",
+    "\nExamples:\n  use-agently doctor\n\nConfig: ~/.use-agently/config.json (global), .use-agently/config.json (local)",
+  )
   .action(async (options: { rpc?: string }, command: Command) => {
     const checks: Check[] = [];
 
diff --git a/packages/use-agently/src/commands/mcp.ts b/packages/use-agently/src/commands/mcp.ts
@@ -39,6 +39,10 @@ function checkSpendLimit(err: DryRunPaymentRequired, maxSpendPerCall: number): v
 
 export const mcpCommand = new Command("mcp")
   .description("Discover and call tools on MCP servers (always list tools before calling)")
+  .addHelpText(
+    "after",
+    '\nExamples:\n  use-agently mcp tools --uri <uri>\n  use-agently mcp call --uri <uri> --tool <name> --args \'{"key":"value"}\'',
+  )
   .action(function () {
     (this as Command).outputHelp();
   });
diff --git a/packages/use-agently/src/commands/wallet.ts b/packages/use-agently/src/commands/wallet.ts
@@ -4,6 +4,7 @@ import { output } from "../output";
 
 export const walletCommand = new Command("wallet")
   .description("Manage wallet settings (spend limits)")
+  .addHelpText("after", "\nExamples:\n  use-agently wallet spend\n  use-agently wallet spend set-max 0.5")
   .action(function () {
     (this as Command).outputHelp();
   });
diff --git a/packages/use-agently/src/commands/web.ts b/packages/use-agently/src/commands/web.ts
@@ -332,7 +332,11 @@ function createMethodSubcommand(method: string, description: string, hasBody: bo
   addSharedOptions(cmd, hasBody);
 
   const bodyExample = hasBody ? ' -d \'{"key":"value"}\' -H "Content-Type: application/json"' : "";
-  cmd.addHelpText("after", `\nExamples:\n  use-agently web ${method} https://api.example.com/data${bodyExample} -v`);
+  const payExample = !hasBody ? `\n  use-agently web ${method} https://api.example.com/paid-endpoint --pay` : "";
+  cmd.addHelpText(
+    "after",
+    `\nExamples:\n  use-agently web ${method} https://api.example.com/data${bodyExample} -v${payExample}`,
+  );
 
   cmd.action(async (url: string, options: WebOptions, command: Command) => {
     await executeHttpRequest(method, url, options, command);
@@ -343,6 +347,10 @@ function createMethodSubcommand(method: string, description: string, hasBody: bo
 
 export const webCommand = new Command("web")
   .description("Make HTTP requests with automatic x402 payment support (GET, POST, PUT, PATCH, DELETE)")
+  .addHelpText(
+    "after",
+    '\nExamples:\n  use-agently web get https://api.example.com/data\n  use-agently web post https://api.example.com/data -d \'{"key":"value"}\' --pay',
+  )
   .action(function () {
     (this as Command).outputHelp();
   });
diff --git a/packages/use-agently/src/commands/whoami.ts b/packages/use-agently/src/commands/whoami.ts
@@ -6,6 +6,7 @@ import { getConfigOrThrow } from "../config";
 export const whoamiCommand = new Command("whoami")
   .description("Show current wallet info")
   .showHelpAfterError(true)
+  .addHelpText("after", "\nExamples:\n  use-agently whoami")
   .action(async (_options: Record<string, never>, command: Command) => {
     const config = await getConfigOrThrow();
     const wallet = loadWallet(config.wallet);
