feat: implement --verbose help flag to toggle visibility of built-in CLI options and add roff man page generation support

Author: tercel

CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to apcore-cli (Python SDK) will be documented in this file.
 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** — `build_program_man_page()` generates a complete roff man page covering all registered commands. `configure_man_help()` adds `--help --man` support to any Click CLI, enabling downstream projects to get man pages for free.
+- **Documentation URL support** — `set_docs_url()` 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
+- `build_module_command()` respects the global verbose help flag to control built-in option visibility.
+- `--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.
+
+---
+
 ## [0.3.1] - 2026-03-27
 
 ### Added

README.md

@@ -204,6 +204,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 hidden built-in options in `--help` output |
+| `--man` | | Print man page to stdout (use with `--help`) |
 
 ### Built-in Commands
 
@@ -216,15 +218,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; pass `--help --verbose` to display them):
 
 | 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)* |
 
 Schema-generated flags (e.g. `--a`, `--b`) are added automatically from the module's `input_schema`.
 
@@ -291,7 +293,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>` generates per-command man pages; `--help --man` prints a full-program man page via `configure_man_help()`
+- **Documentation URL** -- `set_docs_url()` sets a base URL; per-command help shows `Docs: {url}/commands/{name}`, man page SEE ALSO links to the full docs site
 - **Audit logging** -- all executions logged to `~/.apcore-cli/audit.jsonl` with SHA-256 input hashing
 
 ## How It Works
@@ -316,6 +319,10 @@ apcore-cli (the adapter)
     |
     +-- ConfigResolver       4-tier config precedence
     +-- LazyModuleGroup      Dynamic Click command generation
+    +-- set_verbose_help     Toggle built-in option visibility
+    +-- set_docs_url         Set base URL for online docs
+    +-- build_program_man_page  Full-program roff man page
+    +-- configure_man_help   Add --help --man support to any CLI
     +-- schema_parser        JSON Schema -> Click options
     +-- ref_resolver         $ref / allOf / anyOf / oneOf
     +-- approval             TTY-aware HITL approval

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-cli"
-version = "0.3.1"
+version = "0.4.0"
 description = "Terminal adapter for apcore — execute AI-Perceivable modules from the command line"
 readme = "README.md"
 license = "Apache-2.0"

src/apcore_cli/__main__.py

@@ -9,7 +9,7 @@
 import click
 
 from apcore_cli import __version__
-from apcore_cli.cli import GroupedModuleGroup, set_audit_logger
+from apcore_cli.cli import GroupedModuleGroup, set_audit_logger, set_verbose_help
 from apcore_cli.config import ConfigResolver
 from apcore_cli.discovery import register_discovery_commands
 from apcore_cli.security.audit import AuditLogger
@@ -50,6 +50,12 @@ def _extract_binding_path(argv: list[str] | None = None) -> str | None:
     return _extract_argv_option(argv, "--binding")
 
 
+def _has_verbose_flag(argv: list[str] | None = None) -> bool:
+    """Check if --verbose is present in argv (pre-parse, before Click)."""
+    args = argv if argv is not None else sys.argv[1:]
+    return "--verbose" in args
+
+
 def create_cli(
     extensions_dir: str | None = None,
     prog_name: str | None = None,
@@ -75,6 +81,11 @@ def create_cli(
     if prog_name is None:
         prog_name = os.path.basename(sys.argv[0]) or "apcore-cli"
 
+    # Pre-parse --verbose before Click runs so build_module_command knows
+    # whether to hide built-in options.
+    verbose = _has_verbose_flag()
+    set_verbose_help(verbose)
+
     # Resolve CLI log level (3-tier precedence, evaluated before Click runs):
     #   APCORE_CLI_LOGGING_LEVEL (CLI-specific) > APCORE_LOGGING_LEVEL (global) > WARNING
     # The --log-level flag (parsed later) can further override at runtime.
@@ -115,7 +126,7 @@ def create_cli(
 
     if ext_dir_missing:
         click.echo(
-            f"Error: Extensions directory not found: '{ext_dir}'. " "Set APCORE_EXTENSIONS_ROOT or verify the path.",
+            f"Error: Extensions directory not found: '{ext_dir}'. Set APCORE_EXTENSIONS_ROOT or verify the path.",
             err=True,
         )
         sys.exit(EXIT_CONFIG_NOT_FOUND)
@@ -212,13 +223,21 @@ def create_cli(
         type=click.Choice(["DEBUG", "INFO", "WARNING", "ERROR"], case_sensitive=False),
         help="Log verbosity. Overrides APCORE_CLI_LOGGING_LEVEL and APCORE_LOGGING_LEVEL env vars.",
     )
+    @click.option(
+        "--verbose",
+        "verbose_help",
+        is_flag=True,
+        default=False,
+        help="Show all options in help output (including built-in apcore options).",
+    )
     @click.pass_context
     def cli(
         ctx: click.Context,
         extensions_dir_opt: str | None = None,
         commands_dir_opt: str | None = None,
         binding_opt: str | None = None,
         log_level: str | None = None,
+        verbose_help: bool = False,
     ) -> None:
         if log_level is not None:
             # basicConfig() is a no-op once handlers exist; set level on the root logger directly.
@@ -229,6 +248,7 @@ def cli(
             logging.getLogger("apcore").setLevel(apcore_level)
         ctx.ensure_object(dict)
         ctx.obj["extensions_dir"] = ext_dir
+        ctx.obj["verbose_help"] = verbose_help
 
     # Register discovery commands
     register_discovery_commands(cli, registry)

src/apcore_cli/cli.py

@@ -32,6 +32,33 @@
 # Module-level audit logger, set during CLI init
 _audit_logger: AuditLogger | None = None
 
+# Module-level verbose help flag, set during CLI init
+_verbose_help: bool = False
+
+
+def set_verbose_help(verbose: bool) -> None:
+    """Set the verbose help flag. When False, built-in options are hidden."""
+    global _verbose_help
+    _verbose_help = verbose
+
+
+# Module-level docs URL, set by downstream projects
+_docs_url: str | None = None
+
+
+def set_docs_url(url: str | None) -> None:
+    """Set the base URL for online documentation links in help and man pages.
+
+    Pass None to disable. Command-level help appends ``/commands/{name}``
+    automatically.
+
+    Example::
+
+        set_docs_url("https://docs.apcore.dev/cli")
+    """
+    global _docs_url
+    _docs_url = url
+
 
 def set_audit_logger(audit_logger: AuditLogger | None) -> None:
     """Set the global audit logger instance. Pass None to clear."""
@@ -452,55 +479,69 @@ def callback(**kwargs: Any) -> None:
             sys.exit(exit_code)
 
     # Build the command with schema-generated options + built-in options
+    _epilog_parts: list[str] = []
+    if not _verbose_help:
+        _epilog_parts.append("Use --verbose to show all options (including built-in apcore options).")
+    if _docs_url:
+        _epilog_parts.append(f"Docs: {_docs_url}/commands/{effective_cmd_name}")
+    _epilog = "\n".join(_epilog_parts) if _epilog_parts else None
     cmd = click.Command(
         name=effective_cmd_name,
         help=cmd_help,
         callback=callback,
+        epilog=_epilog,
     )
 
-    # Add built-in options
+    # Add built-in options (hidden unless --verbose is passed with --help)
+    _hide = not _verbose_help
     cmd.params.append(
         click.Option(
             ["--input"],
             default=None,
-            help="Read input from file or STDIN ('-').",
+            help="Read JSON input from a file path, or use '-' to read from stdin pipe.",
+            hidden=_hide,
         )
     )
     cmd.params.append(
         click.Option(
             ["--yes", "-y"],
             is_flag=True,
             default=False,
-            help="Bypass approval prompts.",
+            help="Skip interactive approval prompts (for scripts and CI).",
+            hidden=_hide,
         )
     )
     cmd.params.append(
         click.Option(
             ["--large-input"],
             is_flag=True,
             default=False,
-            help="Allow STDIN input larger than 10MB.",
+            help="Allow stdin input larger than 10MB (default limit protects against accidental pipes).",
+            hidden=_hide,
         )
     )
     cmd.params.append(
         click.Option(
             ["--format"],
             type=click.Choice(["json", "table"]),
             default=None,
-            help="Output format.",
+            help="Set output format: 'json' for machine-readable, 'table' for human-readable.",
+            hidden=_hide,
         )
     )
+    # --sandbox is always hidden (not yet implemented)
     cmd.params.append(
         click.Option(
             ["--sandbox"],
             is_flag=True,
             default=False,
-            help="Run module in subprocess sandbox.",
+            help="Run module in an isolated subprocess with restricted filesystem and env access.",
+            hidden=True,
         )
     )
 
     # Guard: schema property names must not collide with built-in option names.
-    _reserved = {"input", "yes", "large_input", "format", "sandbox"}
+    _reserved = {"input", "yes", "large_input", "format", "sandbox", "verbose"}
     for opt in schema_options:
         if opt.name in _reserved:
             click.echo(