fix(config): surface valid config keys in help text and invalid-key errors (#1453)

[aidandaly24]

Refs aws#1453

Issues

• feat: add a way to see valid options for the agentcore config command. aws/agentcore-cli#1453 — Nothing is broken — this is an enhancement request. Users running agentcore config [key] [value] have no in-CLI way to discover the valid keys: agentcore config --help shows only a generic "Config key in dot notation (e.g. telemetry.enabled)" hint, agentcore config (list) prints only keys already set so unset keys are invisible, and a bad config set reports Invalid value ... for key ... without listing valid keys. The only discoverable keys today are telemetry.enabled/telemetry.audit (surfaced by the separate agentcore telemetry command); the rest (uvDefaultIndex, uvIndex, disableTransactionSearch, transactionSearchIndexPercentage, telemetry.endpoint, installationId) exist only in the source Zod schema.

Root cause

Valid global-config keys live only in the internal Zod schema GlobalConfigSchemaStrict (src/lib/schemas/io/global-config.ts:15-31) and are never enumerated to users; registerConfig (src/cli/commands/config/command.ts:20-31) has no addHelpText, handleConfigList (src/cli/commands/config/actions.ts:10-16) prints only persisted keys, and the invalid-set error (actions.ts:37) lists no valid keys. Verified at HEAD e92c79a / v0.20.2.

The fix

Surface keys from the existing schema. Add program.addHelpText('after', ...) in registerConfig (command.ts) enumerating valid dot-notation keys with type hints and examples — mirroring the existing telemetry/command.ts:13-27 pattern. Enrich the actions.ts:37 invalid-set error to append the valid key list. Optionally add a --all flag or config keys action so handleConfigList shows every valid key (set and unset). Design decision: derive the key list by reflecting over the ZodObject shape of GlobalConfigSchemaStrict (recursing into nested telemetry) vs. maintaining a hand-written KEY_DESCRIPTIONS constant; a hand-written constant with descriptions is simpler and lets each key carry a human-readable hint, which the schema alone cannot provide.

Files touched: src/cli/commands/config/command.ts (registerConfig: add addHelpText/examples, mirror telemetry/command.ts pattern); src/cli/commands/config/actions.ts (handleConfigSet line 37 for richer invalid-key error; handleConfigList lines 10-16 for optional show-all); valid keys derived from GlobalConfigSchemaStrict in src/lib/schemas/io/global-config.ts:15-31; optionally a KEY_DESCRIPTIONS constant in src/cli/commands/config/ and/or update src/cli/constants.ts:41 config description; optionally add a config section to docs/commands.md

Validation evidence

The fix was verified by reproducing the original symptom and re-running after the change:

Reproduced original duplicate-guard symptom against pre-fix source (git show HEAD: command.ts had no addHelpText; actions.ts error was just Invalid value "x" for key "...".). The new unit test src/cli/commands/config/tests/config.test.ts goes RED against pre-fix code: both enumerates every valid config key in --help output and lists valid keys in the invalid-set error fail (AssertionError: expected 'Invalid value "x" for key "notARealKe…' to contain 'installationId'). POST-FIX, running the actual built binary /local/home/aidandal/workplace/issues/bugfix-run/clusters/1453/repo/dist/cli/index.mjs: (1) config --help now prints a 'Valid config keys:' section enumerating all 8 dot-notation keys derived from GlobalConfigSchemaStrict (installationId, uvDefaultIndex, uvIndex, disableTransactionSearch, transactionSearchIndexPercentage, telemetry.enabled, telemetry.endpoint, telemetry.audit) via addHelpText('after', ...) mirroring the telemetry command pattern; (2) config notARealKey x now errors with Invalid value "x" for key "notARealKey". Valid keys: installationId, uvDefaultIndex, uvIndex, disableTransactionSearch, transactionSearchIndexPercentage, telemetry.enabled, telemetry.endpoint, telemetry.audit.. The new test passes post-fix. CONFIG_KEYS in src/cli/commands/config/constants.ts matches GlobalConfigSchemaStrict exactly (verified against src/lib/schemas/io/global-config.ts lines 15-31).

Test suite: green.

---

Staged on the fork as a draft for human review. Promote to aws/agentcore-cli after vetting.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	37.21%	13614 / 36582
🔵	Statements	36.48%	14476 / 39675
🔵	Functions	31.89%	2341 / 7340
🔵	Branches	31.11%	9002 / 28932

Generated in workflow #103 for commit 7cf19a2 by the Vitest Coverage Report Action