feat: add verbose help mode, universal man page generation, and documentation URL support

Author: tercel

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to apcore-cli (TypeScript SDK) will be documented in this fi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-03-29
+
+### Added
+- **Verbose help mode** — Built-in apcore options (`--input`, `--yes`, `--large-input`, `--format`, `--sandbox`) are now hidden from `--help` output by default. Pass `--help --verbose` to display the full option list including built-in options.
+- **Universal man page generation** — `buildProgramManPage()` generates a complete roff man page covering all registered commands. `configureManHelp()` adds `--help --man` support to any Commander program, enabling downstream projects to get man pages for free.
+- **Documentation URL support** — `setDocsUrl()` sets a base URL for online docs. Per-command help shows `Docs: {url}/commands/{name}`, man page SEE ALSO includes `Full documentation at {url}`. No default — disabled when not set.
+
+### Changed
+- `buildModuleCommand()` accepts optional `verboseHelp` parameter to control built-in option visibility in help.
+- `--sandbox` is now always hidden from help (not yet implemented). Only four built-in options (`--input`, `--yes`, `--large-input`, `--format`) toggle with `--verbose`.
+- Improved built-in option descriptions for clarity (e.g., `--input` now reads "Read JSON input from a file path, or use '-' to read from stdin pipe").
+
 ## [0.3.2] - 2026-03-28
 
 ### Fixed

README.md

@@ -148,6 +148,8 @@ apcore-cli [OPTIONS] COMMAND [ARGS]
 | `--log-level` | `WARNING` | Logging: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
 | `--version` | | Show version and exit |
 | `--help` | | Show help and exit |
+| `--verbose` | | Show all options in help (including built-in apcore options) |
+| `--man` | | Output man page in roff format (use with `--help`) |
 
 ### Built-in Commands
 
@@ -161,15 +163,15 @@ apcore-cli [OPTIONS] COMMAND [ARGS]
 
 ### Module Execution Options
 
-When executing a module (e.g. `apcore-cli math.add`), these built-in options are always available:
+When executing a module (e.g. `apcore-cli math.add`), these built-in options are available (hidden by default; use `--verbose` to show in `--help`):
 
 | Option | Description |
 |--------|-------------|
 | `--input -` | Read JSON input from STDIN |
 | `--yes` / `-y` | Bypass approval prompts |
 | `--large-input` | Allow STDIN input larger than 10MB |
 | `--format` | Output format: `json` or `table` |
-| `--sandbox` | Run module in subprocess sandbox |
+| `--sandbox` | Run module in subprocess sandbox (not yet implemented — always hidden) |
 
 Schema-generated flags (e.g. `--a`, `--b`) are added automatically from the module's `input_schema`.
 
@@ -234,7 +236,8 @@ cli:
 - **Schema validation** -- inputs validated against JSON Schema before execution, with `$ref`/`allOf`/`anyOf`/`oneOf` resolution
 - **Security** -- API key auth (keyring + AES-256-GCM), append-only audit logging, subprocess sandboxing
 - **Shell completions** -- `apcore-cli completion bash|zsh|fish` generates completion scripts with dynamic module ID completion
-- **Man pages** -- `apcore-cli man <command>` generates roff-formatted man pages
+- **Man pages** -- `apcore-cli man <command>` for single commands, or `--help --man` for a complete program man page. `configureManHelp()` provides one-line integration for downstream projects
+- **Documentation URL** -- `setDocsUrl()` adds doc links to help footers and man pages
 - **Audit logging** -- all executions logged to `~/.apcore-cli/audit.jsonl` with SHA-256 input hashing
 
 ## How It Works
@@ -274,7 +277,7 @@ apcore Registry + Executor (your modules, unchanged)
 
 **Classes:** `LazyModuleGroup`, `ConfigResolver`, `AuthProvider`, `ConfigEncryptor`, `AuditLogger`, `Sandbox`
 
-**Functions:** `createCli`, `main`, `buildModuleCommand`, `validateModuleId`, `collectInput`, `schemaToCliOptions`, `reconvertEnumValues`, `resolveRefs`, `checkApproval`, `resolveFormat`, `formatModuleList`, `formatModuleDetail`, `formatExecResult`, `registerDiscoveryCommands`, `registerShellCommands`, `setAuditLogger`, `getAuditLogger`, `exitCodeForError`, `mapType`, `extractHelp`, `truncate`
+**Functions:** `createCli`, `main`, `buildModuleCommand`, `validateModuleId`, `collectInput`, `schemaToCliOptions`, `reconvertEnumValues`, `resolveRefs`, `checkApproval`, `resolveFormat`, `formatModuleList`, `formatModuleDetail`, `formatExecResult`, `registerDiscoveryCommands`, `registerShellCommands`, `setAuditLogger`, `getAuditLogger`, `setVerboseHelp`, `setDocsUrl`, `buildProgramManPage`, `configureManHelp`, `exitCodeForError`, `mapType`, `extractHelp`, `truncate`
 
 **Errors:** `ApprovalTimeoutError`, `ApprovalDeniedError`, `AuthenticationError`, `ConfigDecryptionError`, `ModuleExecutionError`, `ModuleNotFoundError`, `SchemaValidationError`
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-cli",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "CLI wrapper for the apcore core SDK — exposes apcore modules as CLI commands",
   "type": "module",
   "main": "./dist/index.js",

src/index.ts

@@ -5,7 +5,7 @@
  */
 
 // Core CLI
-export { createCli, main, buildModuleCommand, validateModuleId, collectInput, reconvertEnumValues, applyToolkitIntegration } from "./main.js";
+export { createCli, main, buildModuleCommand, validateModuleId, collectInput, reconvertEnumValues, applyToolkitIntegration, verboseHelp, setVerboseHelp, docsUrl, setDocsUrl } from "./main.js";
 export type { OptionConfig } from "./main.js";
 
 // Lazy module loading
@@ -35,7 +35,7 @@ export { schemaToCliOptions, mapType, extractHelp } from "./schema-parser.js";
 export { checkApproval } from "./approval.js";
 
 // Shell integration
-export { registerShellCommands } from "./shell.js";
+export { registerShellCommands, buildProgramManPage, configureManHelp } from "./shell.js";
 
 // Errors
 export {

src/main.ts

@@ -7,7 +7,7 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
-import { Command, CommanderError } from "commander";
+import { Command, CommanderError, Option } from "commander";
 import { EXIT_CODES, exitCodeForError } from "./errors.js";
 import { resolveRefs } from "./ref-resolver.js";
 import { schemaToCliOptions } from "./schema-parser.js";
@@ -19,6 +19,33 @@ import { getDisplay } from "./display-helpers.js";
 import type { Executor, ModuleDescriptor } from "./cli.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** Whether --verbose was passed (controls help detail level). */
+export let verboseHelp = false;
+
+/** Set the verbose help flag. When false, built-in options are hidden from help. */
+export function setVerboseHelp(verbose: boolean): void {
+  verboseHelp = verbose;
+}
+
+/** Base URL for online documentation. Null means no docs link shown. */
+export let docsUrl: string | null = null;
+
+/**
+ * Set the base URL for online documentation links shown in help and man pages.
+ * Pass null to disable. Command-level help appends `/commands/{name}` automatically.
+ *
+ * @example setDocsUrl("https://docs.apcore.dev/cli");
+ */
+export function setDocsUrl(url: string | null): void {
+  docsUrl = url;
+}
+
+/** Check if --verbose is present in process.argv (pre-parse, before Commander). */
+function hasVerboseFlag(): boolean {
+  return process.argv.includes("--verbose");
+}
+
 let VERSION = "0.0.0";
 try {
   const pkg = JSON.parse(readFileSync(path.resolve(__dirname, "../package.json"), "utf-8"));
@@ -66,7 +93,9 @@ export interface OptionConfig {
 export function createCli(
   extensionsDir?: string,
   progName?: string,
+  verbose = false,
 ): Command {
+  verboseHelp = verbose;
   // Resolve program name
   const resolvedProgName = progName ?? path.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
 
@@ -81,7 +110,8 @@ export function createCli(
     .option("--extensions-dir <path>", "Path to extensions directory")
     .option("--commands-dir <path>", "Path to convention-based commands directory")
     .option("--binding <path>", "Path to binding.yaml for display overlay")
-    .option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING");
+    .option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING")
+    .option("--verbose", "Show all options in help output (including built-in apcore options)");
 
   // NOTE: Full registry/executor wiring requires apcore-js to be available.
   // For now, extensions-dir is accepted but not wired to a real registry.
@@ -156,7 +186,8 @@ export async function applyToolkitIntegration(
  * Parse argv and run the CLI. Handles top-level error catching and exit codes.
  */
 export function main(progName?: string): void {
-  const program = createCli(undefined, progName);
+  verboseHelp = hasVerboseFlag();
+  const program = createCli(undefined, progName, verboseHelp);
 
   try {
     program.parse(process.argv);
@@ -185,6 +216,7 @@ export function buildModuleCommand(
   executor: Executor,
   helpTextMaxLength = 1000,
   cmdName?: string,
+  verbose = verboseHelp,
 ): Command {
   const moduleId = moduleDef.id;
   let resolvedSchema: Record<string, unknown> = {};
@@ -211,12 +243,38 @@ export function buildModuleCommand(
 
   const cmd = new Command(effectiveCmdName).description(cmdHelp);
 
-  // Built-in options
-  cmd.option("--input <source>", "Read input from STDIN ('-')");
-  cmd.option("-y, --yes", "Bypass approval prompts", false);
-  cmd.option("--large-input", "Allow STDIN input larger than 10MB", false);
-  cmd.option("--format <format>", "Output format (json|table)");
-  cmd.option("--sandbox", "Run module in subprocess sandbox", false);
+  // Built-in options (hidden unless --verbose)
+  const inputOpt = new Option("--input <source>", "Read JSON input from a file path, or use '-' to read from stdin pipe");
+  const yesOpt = new Option("-y, --yes", "Skip interactive approval prompts (for scripts and CI)").default(false);
+  const largeInputOpt = new Option("--large-input", "Allow stdin input larger than 10MB (default limit protects against accidental pipes)").default(false);
+  const formatOpt = new Option("--format <format>", "Set output format: 'json' for machine-readable, 'table' for human-readable");
+  // --sandbox is always hidden (not yet implemented)
+  const sandboxOpt = new Option("--sandbox", "Run module in an isolated subprocess with restricted filesystem and env access").default(false).hideHelp();
+
+  if (!verbose) {
+    inputOpt.hideHelp();
+    yesOpt.hideHelp();
+    largeInputOpt.hideHelp();
+    formatOpt.hideHelp();
+  }
+
+  cmd.addOption(inputOpt);
+  cmd.addOption(yesOpt);
+  cmd.addOption(largeInputOpt);
+  cmd.addOption(formatOpt);
+  cmd.addOption(sandboxOpt);
+
+  // Help footer: verbose hint + optional docs link
+  const footerParts: string[] = [];
+  if (!verbose) {
+    footerParts.push("Use --verbose to show all options (including built-in apcore options).");
+  }
+  if (docsUrl) {
+    footerParts.push(`Docs: ${docsUrl}/commands/${effectiveCmdName}`);
+  }
+  if (footerParts.length > 0) {
+    cmd.addHelpText("after", "\n" + footerParts.join("\n") + "\n");
+  }
 
   // Schema-generated options
   for (const opt of schemaOptions) {
@@ -238,7 +296,7 @@ export function buildModuleCommand(
 
     // Remove built-in keys from options to get schema kwargs
     const schemaKwargs: Record<string, unknown> = {};
-    const builtinKeys = new Set(["input", "yes", "largeInput", "format", "sandbox"]);
+    const builtinKeys = new Set(["input", "yes", "largeInput", "format", "sandbox", "verbose"]);
     for (const [k, v] of Object.entries(options)) {
       if (!builtinKeys.has(k)) {
         schemaKwargs[k] = v;