feat: Make CLI help text truncation limit configurable via cli.help_text_max_length and increase its default from 200 to 1000 characters.

Author: tercel

CHANGELOG.md

@@ -5,6 +5,25 @@ 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.2.1] - 2026-03-19
+
+### Changed
+- Help text truncation limit increased from 200 to 1000 characters (configurable via `cli.help_text_max_length` config key)
+- `_extract_help`: added `max_length: int = 1000` parameter (`schema_parser.py`)
+- `schema_to_click_options`: added `max_help_length: int = 1000` parameter (`schema_parser.py`)
+- `build_module_command`: added `help_text_max_length: int = 1000` parameter, threaded through to schema parser (`cli.py`)
+- `LazyModuleGroup`: constructor accepts `help_text_max_length: int = 1000`, passes to `build_module_command` (`cli.py`)
+- `create_cli`: resolves `cli.help_text_max_length` from `ConfigResolver` and passes to `LazyModuleGroup` (`__main__.py`)
+- `format_exec_result`: nested dict/list values in table mode now rendered with `json.dumps` instead of `str()` (`output.py`)
+
+### Added
+- `cli.help_text_max_length` config key (default: 1000) in `ConfigResolver.DEFAULTS` (`config.py`)
+- `APCORE_CLI_HELP_TEXT_MAX_LENGTH` environment variable support for configuring help text max length
+- `test_help_truncation_default`: tests default 1000-char truncation
+- `test_help_no_truncation_within_limit`: tests no truncation at 999 chars
+- `test_help_truncation_custom_max`: tests custom max_length parameter
+- 263 tests (up from 261)
+
 ## [0.2.0] - 2026-03-16
 
 ### Added

README.md

@@ -8,7 +8,7 @@ Terminal adapter for apcore. Execute AI-Perceivable modules from the command lin
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://python.org)
-[![Tests](https://img.shields.io/badge/tests-261%20passed-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-263%20passed-brightgreen.svg)]()
 
 | | |
 |---|---|
@@ -231,6 +231,7 @@ apcore-cli uses a 4-tier configuration precedence:
 | `APCORE_LOGGING_LEVEL` | Global apcore log level (fallback when `APCORE_CLI_LOGGING_LEVEL` is unset) | `WARNING` |
 | `APCORE_AUTH_API_KEY` | API key for remote registry authentication | *(unset)* |
 | `APCORE_CLI_SANDBOX` | Set to `1` to enable subprocess sandboxing | *(unset)* |
+| `APCORE_CLI_HELP_TEXT_MAX_LENGTH` | Maximum characters for CLI option help text before truncation | `1000` |
 
 ### Config File (`apcore.yaml`)
 
@@ -241,6 +242,8 @@ logging:
   level: DEBUG
 sandbox:
   enabled: false
+cli:
+  help_text_max_length: 1000
 ```
 
 ## Features
@@ -378,7 +381,7 @@ apcore-cli --extensions-dir ./extensions greet.hello --name Alice --greeting Hi
 git clone https://github.com/aipartnerup/apcore-cli-python.git
 cd apcore-cli-python
 pip install -e ".[dev]"
-pytest                           # 261 tests
+pytest                           # 263 tests
 pytest --cov                     # with coverage report
 bash examples/run_examples.sh   # run all examples
 ```

planning/schema-parser.md

@@ -83,7 +83,7 @@
 - `tests/test_schema_parser.py`:
   - `test_help_from_x_llm_description`: `x-llm-description` present → used over `description`.
   - `test_help_from_description`: Only `description` → used.
-  - `test_help_truncation`: Description > 200 chars → truncated to 197 + "...".
+  - `test_help_truncation_default`: Description > 1000 chars (default) → truncated to 997 + "...".
   - `test_help_none`: No description fields → `None`.
   - `test_flag_collision_detection`: Properties `foo_bar` and `foo-bar` both map to `--foo-bar` → exit 48.
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apcore-cli"
-version = "0.2.0"
+version = "0.2.1"
 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

@@ -65,16 +65,26 @@ def create_cli(extensions_dir: str | None = None, prog_name: str | None = None)
     apcore_level = _default_level if _default_level <= logging.INFO else logging.ERROR
     logging.getLogger("apcore").setLevel(apcore_level)
 
+    config = ConfigResolver()
+
     if extensions_dir is not None:
         ext_dir = extensions_dir
     else:
-        config = ConfigResolver()
         ext_dir = config.resolve(
             "extensions.root",
             cli_flag="--extensions-dir",
             env_var="APCORE_EXTENSIONS_ROOT",
         )
 
+    help_text_max_length = config.resolve(
+        "cli.help_text_max_length",
+        env_var="APCORE_CLI_HELP_TEXT_MAX_LENGTH",
+    )
+    try:
+        help_text_max_length = int(help_text_max_length)
+    except (TypeError, ValueError):
+        help_text_max_length = 1000
+
     ext_dir_missing = not os.path.exists(ext_dir)
     ext_dir_unreadable = not ext_dir_missing and not os.access(ext_dir, os.R_OK)
 
@@ -119,6 +129,7 @@ def create_cli(extensions_dir: str | None = None, prog_name: str | None = None)
         cls=LazyModuleGroup,
         registry=registry,
         executor=executor,
+        help_text_max_length=help_text_max_length,
         name=prog_name,
         help="CLI adapter for the apcore module ecosystem.",
     )

src/apcore_cli/cli.py

@@ -41,10 +41,17 @@ def set_audit_logger(audit_logger: AuditLogger | None) -> None:
 class LazyModuleGroup(click.Group):
     """Custom Click Group that lazily loads apcore modules as subcommands."""
 
-    def __init__(self, registry: Registry, executor: Executor, **kwargs: Any) -> None:
+    def __init__(
+        self,
+        registry: Registry,
+        executor: Executor,
+        help_text_max_length: int = 1000,
+        **kwargs: Any,
+    ) -> None:
         super().__init__(**kwargs)
         self._registry = registry
         self._executor = executor
+        self._help_text_max_length = help_text_max_length
         self._module_cache: dict[str, click.Command] = {}
 
     def list_commands(self, ctx: click.Context) -> list[str]:
@@ -70,7 +77,7 @@ def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None
         if module_def is None:
             return None
 
-        cmd = build_module_command(module_def, self._executor)
+        cmd = build_module_command(module_def, self._executor, help_text_max_length=self._help_text_max_length)
         self._module_cache[cmd_name] = cmd
         return cmd
 
@@ -101,7 +108,11 @@ def _get_module_id(module_def: ModuleDescriptor) -> str:
     return module_def.module_id
 
 
-def build_module_command(module_def: ModuleDescriptor, executor: Executor) -> click.Command:
+def build_module_command(
+    module_def: ModuleDescriptor,
+    executor: Executor,
+    help_text_max_length: int = 1000,
+) -> click.Command:
     """Build a Click command from an apcore module definition.
 
     Generates Click options from the module's input_schema, wires up
@@ -137,7 +148,7 @@ def build_module_command(module_def: ModuleDescriptor, executor: Executor) -> cl
     else:
         resolved_schema = input_schema
 
-    schema_options = schema_to_click_options(resolved_schema)
+    schema_options = schema_to_click_options(resolved_schema, max_help_length=help_text_max_length)
 
     def callback(**kwargs: Any) -> None:
         # Separate built-in options from schema-generated kwargs

src/apcore_cli/config.py

@@ -22,6 +22,7 @@ class ConfigResolver:
         "sandbox.enabled": False,
         "cli.stdin_buffer_limit": 10_485_760,  # 10 MB
         "cli.auto_approve": False,
+        "cli.help_text_max_length": 1000,
     }
 
     def __init__(

src/apcore_cli/schema_parser.py

@@ -50,19 +50,19 @@ def _map_type(prop_name: str, prop_schema: dict) -> Any:
     return result
 
 
-def _extract_help(prop_schema: dict) -> str | None:
+def _extract_help(prop_schema: dict, max_length: int = 1000) -> str | None:
     """Extract help text from schema property, preferring x-llm-description."""
     text = prop_schema.get("x-llm-description")
     if not text:
         text = prop_schema.get("description")
     if not text:
         return None
-    if len(text) > 200:
-        return text[:197] + "..."
+    if max_length > 0 and len(text) > max_length:
+        return text[: max_length - 3] + "..."
     return text
 
 
-def schema_to_click_options(schema: dict) -> list[click.Option]:
+def schema_to_click_options(schema: dict, max_help_length: int = 1000) -> list[click.Option]:
     """Convert JSON Schema properties to a list of Click options."""
     properties = schema.get("properties", {})
     required_list = schema.get("required", [])
@@ -93,7 +93,7 @@ def schema_to_click_options(schema: dict) -> list[click.Option]:
 
         click_type = _map_type(prop_name, prop_schema)
         is_required = prop_name in required_list
-        _help_base = _extract_help(prop_schema)
+        _help_base = _extract_help(prop_schema, max_length=max_help_length)
         # Append [required] to help text for user clarity; do NOT set required=True
         # at the Click level because that would block --input - (STDIN) from working.
         # Schema-level required validation happens in the callback via jsonschema.validate().

tests/test_config.py

@@ -26,6 +26,7 @@ def test_defaults_contains_expected_keys(self):
             "logging.level",
             "sandbox.enabled",
             "cli.stdin_buffer_limit",
+            "cli.help_text_max_length",
         ]
         for key in expected_keys:
             assert key in resolver.DEFAULTS, f"Missing default key: {key}"

tests/test_schema_parser.py

@@ -205,9 +205,20 @@ def test_help_from_description(self):
         result = _extract_help({"description": "Regular help"})
         assert result == "Regular help"
 
-    def test_help_truncation(self):
-        long_text = "x" * 250
+    def test_help_truncation_default(self):
+        long_text = "x" * 1100
         result = _extract_help({"description": long_text})
+        assert len(result) == 1000
+        assert result.endswith("...")
+
+    def test_help_no_truncation_within_limit(self):
+        text = "x" * 999
+        result = _extract_help({"description": text})
+        assert result == text
+
+    def test_help_truncation_custom_max(self):
+        long_text = "x" * 300
+        result = _extract_help({"description": long_text}, max_length=200)
         assert len(result) == 200
         assert result.endswith("...")