Thanks to visit codestin.com
Credit goes to github.com

Skip to content

feat(gateway): grouped help for the large-option commands - #2304

Draft
jariy17 wants to merge 1 commit into
refactorfrom
feat/gateway-grouped-help
Draft

feat(gateway): grouped help for the large-option commands#2304
jariy17 wants to merge 1 commit into
refactorfrom
feat/gateway-grouped-help

Conversation

@jariy17

@jariy17 jariy17 commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

Applies the router's help-group mechanism from #2262 to the seven gateway commands whose flat option lists had grown past skimming. Presentation only — no flag is added, removed, or renamed, and no request changes.

Command Options Headings
gateway connector create 9 Target · Connector · Credentials & networking
gateway connector update 14 Target · Connector · Credentials & networking · Clear (unset a field)
gateway create 14 Configuration · Protocol · Authorizer · Interceptors · Policy engine
gateway invoke 12 Target · Payload · Authentication · Application headers · Session
gateway target create 10 Target · Definition · Credentials & networking · Idempotency
gateway target update 13 Target · Definition · Credentials & networking · Clear (unset a field)
gateway update 19 Target · Configuration · Protocol & authorizer · Transform & interceptors · Policy engine · WAF · Clear (unset a field)

Notes

  • create, invoke, and update reorder their flags so each heading's flags declare contiguously (Commander orders headings by first-declared flag). update moves --exception-level up into Configuration.
  • The update commands collect their --clear-* flags under one Clear (unset a field): heading.
  • A command that groups its flags gets its generated -h/--help moved to Other options:.

Testing

  • bun run typecheck clean
  • bun run lint clean
  • bun test src/handlers/gateway — 226 pass

Proposed --help

agentcore gateway connector create --help 
Usage: agentcore gateway connector create [options]

create a connector-backed Gateway Target

Target:
  --gateway-id <gateway-id>                                                  the parent Gateway ID
  --name <name>                                                              Connector Target name
  --description <description>                                                Connector Target description

Connector:
  --connector-configuration <connector-configuration>                        connector-backed Target configuration (JSON; inline, file://<path>, or - for stdin)
  --connector <connector>                                                    curated connector
  --knowledge-base-id <knowledge-base-id>                                    Knowledge Base ID for the bedrock-knowledge-bases connector

Credentials & networking:
  --credential-provider-configurations <credential-provider-configurations>  one outbound credential configuration (JSON array; inline, file://<path>, or - for stdin); required with --connector-configuration and defaults to GATEWAY_IAM_ROLE with --connector
  --metadata-configuration <metadata-configuration>                          metadata propagation (JSON; inline, file://<path>, or - for stdin)
  --private-endpoint <private-endpoint>                                      private endpoint (JSON; inline, file://<path>, or - for stdin)

Other options:
  -h, --help                                                                 display help for command

Global Options:
  --region <region>                                                          AWS region
  --debug                                                                    debug logging (default: false)
  --json                                                                     JSON output (default: false)
  --endpoint-url <endpoint-url>                                              endpoint URL override
agentcore gateway connector update --help 
Usage: agentcore gateway connector update [options]

update a connector-backed Gateway Target

Target:
  --gateway-id <gateway-id>                                                  the parent Gateway ID
  --id <id>                                                                  the connector-backed Gateway Target ID
  --name <name>                                                              updated Connector Target name
  --description <description>                                                updated Connector Target description

Connector:
  --connector-configuration <connector-configuration>                        complete connector-backed Target configuration (JSON; inline, file://<path>, or - for stdin)
  --connector <connector>                                                    curated connector
  --knowledge-base-id <knowledge-base-id>                                    Knowledge Base ID for the bedrock-knowledge-bases connector

Credentials & networking:
  --credential-provider-configurations <credential-provider-configurations>  replacement outbound credentials (JSON array; inline, file://<path>, or - for stdin)
  --metadata-configuration <metadata-configuration>                          replacement metadata propagation (JSON; inline, file://<path>, or - for stdin)
  --private-endpoint <private-endpoint>                                      replacement private endpoint (JSON; inline, file://<path>, or - for stdin)

Clear (unset a field):
  --clear-description                                                        remove the Connector Target description (default: false)
  --clear-credential-provider-configurations                                 remove outbound credentials (default: false)
  --clear-metadata-configuration                                             remove metadata propagation (default: false)
  --clear-private-endpoint                                                   remove private endpoint configuration (default: false)

Other options:
  -h, --help                                                                 display help for command

Global Options:
  --region <region>                                                          AWS region
  --debug                                                                    debug logging (default: false)
  --json                                                                     JSON output (default: false)
  --endpoint-url <endpoint-url>                                              endpoint URL override
agentcore gateway create --help 
Usage: agentcore gateway create [options]

create an AgentCore Gateway

Configuration:
  --name <name>                                              the Gateway name
  --role-arn <role-arn>                                      IAM role the Gateway assumes
  --description <description>                                Gateway description
  --kms-key-arn <kms-key-arn>                                KMS key ARN
  --exception-level <exception-level>                        exception detail level: debug
  --tags <tags...>                                           tags as repeated key=value or a JSON object (inline, file://<path>, or - for stdin)
  --client-token <client-token>                              idempotency token

Protocol:
  --protocol <protocol>                                      restrict Target protocols to MCP; omitted allows every Target protocol
  --protocol-configuration <protocol-configuration>          MCP protocol configuration (JSON; inline, file://<path>, or - for stdin)

Authorizer:
  --authorizer-type <authorizer-type>                        inbound authorizer: AWS_IAM, CUSTOM_JWT, NONE, or AUTHENTICATE_ONLY
  --authorizer-configuration <authorizer-configuration>      authorizer configuration (JSON; inline, file://<path>, or - for stdin)

Interceptors:
  --interceptor-configurations <interceptor-configurations>  interceptor configurations (JSON array; inline, file://<path>, or - for stdin)

Policy engine:
  --policy-engine-arn <policy-engine-arn>                    Policy Engine ARN
  --policy-engine-mode <policy-engine-mode>                  Policy Engine mode: log-only or enforce

Other options:
  -h, --help                                                 display help for command

Global Options:
  --region <region>                                          AWS region
  --debug                                                    debug logging (default: false)
  --json                                                     JSON output (default: false)
  --endpoint-url <endpoint-url>                              endpoint URL override
agentcore gateway invoke --help 
Usage: agentcore gateway invoke [options]

invoke an AgentCore Gateway

Target:
  --id <id>                                      the ID of the Gateway
  --path <path>                                  the path relative to the Gateway origin
  --method <method>                              the HTTP request method

Payload:
  --payload <payload>                            the inline payload to send
  --content-type <content-type>                  the payload content type
  --accept <accept>                              the accepted response content type
  --output-file <output-file>                    the response output file

Authentication:
  --bearer-token <bearer-token>                  the Gateway bearer token

Application headers:
  --header <header...>                           an ordered application header

Session:
  --session-id <session-id>                      the Runtime target session ID
  --mcp-session-id <mcp-session-id>              the MCP session ID
  --mcp-protocol-version <mcp-protocol-version>  the MCP protocol version

Other options:
  -h, --help                                     display help for command

Global Options:
  --region <region>                              AWS region
  --debug                                        debug logging (default: false)
  --json                                         JSON output (default: false)
  --endpoint-url <endpoint-url>                  endpoint URL override
agentcore gateway target create --help 
Usage: agentcore gateway target create [options]

create a Gateway Target

Target:
  --gateway-id <gateway-id>                                                  the parent Gateway ID
  --name <name>                                                              Target name; optional only for AgentCore Runtime Targets
  --description <description>                                                Target description

Definition:
  --endpoint <endpoint>                                                      MCP server HTTPS endpoint
  --target-configuration <target-configuration>                              complete Target configuration (JSON; inline, file://<path>, or - for stdin)
  --tool-schema <tool-schema>                                                MCP tool schema (inline JSON, file://<path>, - for stdin, or s3:// URI)

Credentials & networking:
  --credential-provider-configurations <credential-provider-configurations>  outbound credentials (JSON array; inline, file://<path>, or - for stdin)
  --metadata-configuration <metadata-configuration>                          metadata propagation (JSON; inline, file://<path>, or - for stdin)
  --private-endpoint <private-endpoint>                                      private endpoint (JSON; inline, file://<path>, or - for stdin)

Idempotency:
  --client-token <client-token>                                              idempotency token

Other options:
  -h, --help                                                                 display help for command

Global Options:
  --region <region>                                                          AWS region
  --debug                                                                    debug logging (default: false)
  --json                                                                     JSON output (default: false)
  --endpoint-url <endpoint-url>                                              endpoint URL override
agentcore gateway target update --help 
Usage: agentcore gateway target update [options]

update a Gateway Target

Target:
  --gateway-id <gateway-id>                                                  the parent Gateway ID
  --target-id <target-id>                                                    the Target ID
  --name <name>                                                              updated Target name
  --description <description>                                                updated Target description

Definition:
  --endpoint <endpoint>                                                      updated endpoint for an existing MCP server Target
  --target-configuration <target-configuration>                              complete replacement Target configuration (JSON; inline, file://<path>, or - for stdin)

Credentials & networking:
  --credential-provider-configurations <credential-provider-configurations>  replacement outbound credentials (JSON array; inline, file://<path>, or - for stdin)
  --metadata-configuration <metadata-configuration>                          replacement metadata propagation (JSON; inline, file://<path>, or - for stdin)
  --private-endpoint <private-endpoint>                                      replacement private endpoint (JSON; inline, file://<path>, or - for stdin)

Clear (unset a field):
  --clear-description                                                        remove the Target description (default: false)
  --clear-credential-provider-configurations                                 remove outbound credentials (default: false)
  --clear-metadata-configuration                                             remove metadata propagation (default: false)
  --clear-private-endpoint                                                   remove private endpoint configuration (default: false)

Other options:
  -h, --help                                                                 display help for command

Global Options:
  --region <region>                                                          AWS region
  --debug                                                                    debug logging (default: false)
  --json                                                                     JSON output (default: false)
  --endpoint-url <endpoint-url>                                              endpoint URL override
agentcore gateway update --help 
Usage: agentcore gateway update [options]

update an AgentCore Gateway

Target:
  --id <id>                                                          the Gateway ID

Configuration:
  --role-arn <role-arn>                                              updated IAM role ARN
  --description <description>                                        updated Gateway description
  --exception-level <exception-level>                                exception detail level: debug

Protocol & authorizer:
  --protocol-configuration <protocol-configuration>                  replacement MCP protocol configuration (JSON; inline, file://<path>, or - for stdin)
  --authorizer-configuration <authorizer-configuration>              replacement CUSTOM_JWT configuration (JSON; inline, file://<path>, or - for stdin)

Transform & interceptors:
  --custom-transform-configuration <custom-transform-configuration>  replacement custom transform configuration (JSON; inline, file://<path>, or - for stdin)
  --interceptor-configurations <interceptor-configurations>          replacement interceptors (JSON array; inline, file://<path>, or - for stdin)

Policy engine:
  --policy-engine-arn <policy-engine-arn>                            Policy Engine ARN
  --policy-engine-mode <policy-engine-mode>                          Policy Engine mode: log-only or enforce

WAF:
  --waf-configuration <waf-configuration>                            replacement WAF configuration (JSON; inline, file://<path>, or - for stdin)

Clear (unset a field):
  --clear-protocol                                                   remove the MCP-only Target restriction (default: false)
  --clear-description                                                remove the Gateway description (default: false)
  --clear-protocol-configuration                                     remove MCP protocol overrides (default: false)
  --clear-custom-transform-configuration                             remove the custom transform configuration (default: false)
  --clear-interceptor-configurations                                 remove every interceptor (default: false)
  --clear-policy-engine                                              detach the Policy Engine (default: false)
  --clear-exception-level                                            return to generic invocation errors (default: false)
  --clear-waf-configuration                                          reset WAF failure mode to FAIL_CLOSE (default: false)

Other options:
  -h, --help                                                         display help for command

Global Options:
  --region <region>                                                  AWS region
  --debug                                                            debug logging (default: false)
  --json                                                             JSON output (default: false)
  --endpoint-url <endpoint-url>                                      endpoint URL override

jariy17
feat(gateway): grouped help for the large-option commands
8ccab31 
Applies the router's help-group mechanism (#2262) to the seven gateway commands
whose flat option lists had grown past skimming. Presentation only — no flag is
added, removed, or renamed, and no request changes.

- connector create: Target, Connector, Credentials & networking
- connector update: + Clear (unset a field) for the --clear-* flags
- create: Configuration, Protocol, Authorizer, Interceptors, Policy engine
- invoke: Target, Payload, Authentication, Application headers, Session
- target create: Target, Definition, Credentials & networking, Idempotency
- target update: Target, Definition, Credentials & networking, Clear (unset a field)
- update: Target, Configuration, Protocol & authorizer, Transform & interceptors,
  Policy engine, WAF, Clear (unset a field)

create, invoke, and update reorder their flags so each heading's flags declare
contiguously (Commander orders headings by first-declared flag); the update
commands collect their --clear-* flags under one heading. A command that groups
its flags gets its generated -h/--help moved to "Other options:".
@github-actions github-actions Bot added the size/m PR size: M label Sep 14, 2026
@agentcore-devx-automation agentcore-devx-automation Bot added agentcore-harness-reviewing AgentCore Harness review in progress claude-security-reviewing Claude Code /security-review in progress labels Sep 14, 2026
@agentcore-devx-automation

agentcore-devx-automation Bot commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

Claude Security Review: no high-confidence findings. (run)

@agentcore-devx-automation agentcore-devx-automation Bot removed the claude-security-reviewing Claude Code /security-review in progress label Sep 14, 2026
agentcore-devx-automation[bot]
agentcore-devx-automation Bot reviewed Sep 14, 2026
View reviewed changes

@agentcore-devx-automation agentcore-devx-automation Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AgentCore Harness Review

Verdict: Looks good

This is a pure UX refactor that assigns existing gateway-command flags to help groups via the flag() factory's existing group option. The plumbing (option.helpGroup in src/router/flags.tsx and the group rendering in src/components/CliOnlyScreen.tsx) already exists, so this just improves --help organization with no runtime behavior change.

Things I checked:

  • Every flag in each touched file has been assigned a group — no stragglers.
  • Group label strings are consistent across files: "Target:", "Configuration:", "Credentials & networking:", "Clear (unset a field):", "Policy engine:", "Connector:", "Definition:", etc. all agree wherever they appear.
  • No schema, handler logic, or I/O boundaries changed, so tests and telemetry are unaffected. Telemetry is not needed for a help-text-only change.

Minor style-only nits I'll flag but wouldn't block on:

  • In src/handlers/gateway/update/index.tsx, id uses inline "Target:" and interceptor-configurations uses inline "Interceptors:" while sibling flags use const labels (CONFIGURATION, POLICY_ENGINE, TRANSFORM, CLEAR). Same pattern in gateway/create/index.tsx ("Interceptors:") and gateway/target/create/index.tsx ("Idempotency:"). Optional to normalize on the const style for consistency.

LGTM to merge.

@agentcore-devx-automation agentcore-devx-automation Bot removed the agentcore-harness-reviewing AgentCore Harness review in progress label Sep 14, 2026
@codecov-commenter

codecov-commenter commented Sep 14, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.99%. Comparing base (25a7a82) to head (8ccab31).
⚠️ Report is 1 commits behind head on refactor.

Additional details and impacted files 
@@            Coverage Diff             @@
##           refactor    #2304    +/-   ##
==========================================
  Coverage     96.98%   96.99%            
==========================================
  Files           579      579            
  Lines         39442    39565   +123     
==========================================
+ Hits          38253    38376   +123     
  Misses         1189     1189

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@agentcore-devx-automation agentcore-devx-automation[bot] agentcore-devx-automation[bot] left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

size/m PR size: M

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@jariy17 @codecov-commenter