diff --git a/src/handlers/gateway/connector/create/index.tsx b/src/handlers/gateway/connector/create/index.tsx
index c9ec39078..866b3d039 100644
--- a/src/handlers/gateway/connector/create/index.tsx
+++ b/src/handlers/gateway/connector/create/index.tsx
@@ -19,43 +19,53 @@ import {
 import type { CreateGatewayTargetInput } from "../../types";
 import { GatewayConnectorTarget } from "../gatewayConnectorTarget";
 
+const TARGET = "Target:";
+const CONNECTOR = "Connector:";
+const CREDENTIALS = "Credentials & networking:";
+
 export const createCreateGatewayConnectorHandler = (core: Core, io: AppIO) =>
   createHandler({
     name: "create",
     description: "create a connector-backed Gateway Target",
     flags: [
-      flag("gateway-id", "the parent Gateway ID", z.string().optional()),
-      flag("name", "Connector Target name", z.string().optional()),
-      flag("description", "Connector Target description", z.string().optional()),
+      flag("gateway-id", "the parent Gateway ID", z.string().optional(), { group: TARGET }),
+      flag("name", "Connector Target name", z.string().optional(), { group: TARGET }),
+      flag("description", "Connector Target description", z.string().optional(), { group: TARGET }),
       flag(
         "connector-configuration",
         "connector-backed Target configuration (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CONNECTOR },
       ),
       flag(
         "connector",
         "curated connector",
         z.enum(["web-search", "bedrock-knowledge-bases", "bedrock-mantle"]).optional(),
+        { group: CONNECTOR },
       ),
       flag(
         "knowledge-base-id",
         "Knowledge Base ID for the bedrock-knowledge-bases connector",
         z.string().optional(),
+        { group: CONNECTOR },
       ),
       flag(
         "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",
         z.string().optional(),
+        { group: CREDENTIALS },
       ),
       flag(
         "metadata-configuration",
         "metadata propagation (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CREDENTIALS },
       ),
       flag(
         "private-endpoint",
         "private endpoint (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CREDENTIALS },
       ),
     ],
     handle: async (ctx, flags) => {
diff --git a/src/handlers/gateway/connector/update/index.tsx b/src/handlers/gateway/connector/update/index.tsx
index f09ce1ba6..a3067cedd 100644
--- a/src/handlers/gateway/connector/update/index.tsx
+++ b/src/handlers/gateway/connector/update/index.tsx
@@ -19,49 +19,72 @@ import {
 import type { GatewayTargetUpdatePatch } from "../../types";
 import { GatewayConnectorTarget } from "../gatewayConnectorTarget";
 
+const TARGET = "Target:";
+const CONNECTOR = "Connector:";
+const CREDENTIALS = "Credentials & networking:";
+const CLEAR = "Clear (unset a field):";
+
 export const createUpdateGatewayConnectorHandler = (core: Core, io: AppIO) =>
   createHandler({
     name: "update",
     description: "update a connector-backed Gateway Target",
     flags: [
-      flag("gateway-id", "the parent Gateway ID", z.string().optional()),
-      flag("id", "the connector-backed Gateway Target ID", z.string().optional()),
-      flag("name", "updated Connector Target name", z.string().optional()),
-      flag("description", "updated Connector Target description", z.string().optional()),
+      flag("gateway-id", "the parent Gateway ID", z.string().optional(), { group: TARGET }),
+      flag("id", "the connector-backed Gateway Target ID", z.string().optional(), {
+        group: TARGET,
+      }),
+      flag("name", "updated Connector Target name", z.string().optional(), { group: TARGET }),
+      flag("description", "updated Connector Target description", z.string().optional(), {
+        group: TARGET,
+      }),
       flag(
         "connector-configuration",
         "complete connector-backed Target configuration (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CONNECTOR },
       ),
       flag(
         "connector",
         "curated connector",
         z.enum(["web-search", "bedrock-knowledge-bases", "bedrock-mantle"]).optional(),
+        { group: CONNECTOR },
       ),
       flag(
         "knowledge-base-id",
         "Knowledge Base ID for the bedrock-knowledge-bases connector",
         z.string().optional(),
+        { group: CONNECTOR },
       ),
       flag(
         "credential-provider-configurations",
         "replacement outbound credentials (JSON array; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CREDENTIALS },
       ),
       flag(
         "metadata-configuration",
         "replacement metadata propagation (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CREDENTIALS },
       ),
       flag(
         "private-endpoint",
         "replacement private endpoint (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CREDENTIALS },
       ),
-      flag("clear-description", "remove the Connector Target description", z.boolean()),
-      flag("clear-credential-provider-configurations", "remove outbound credentials", z.boolean()),
-      flag("clear-metadata-configuration", "remove metadata propagation", z.boolean()),
-      flag("clear-private-endpoint", "remove private endpoint configuration", z.boolean()),
+      flag("clear-description", "remove the Connector Target description", z.boolean(), {
+        group: CLEAR,
+      }),
+      flag("clear-credential-provider-configurations", "remove outbound credentials", z.boolean(), {
+        group: CLEAR,
+      }),
+      flag("clear-metadata-configuration", "remove metadata propagation", z.boolean(), {
+        group: CLEAR,
+      }),
+      flag("clear-private-endpoint", "remove private endpoint configuration", z.boolean(), {
+        group: CLEAR,
+      }),
     ],
     handle: async (ctx, flags) => {
       if (!flags["gateway-id"]) {
diff --git a/src/handlers/gateway/create/index.tsx b/src/handlers/gateway/create/index.tsx
index be0f56fa1..8d48d8aad 100644
--- a/src/handlers/gateway/create/index.tsx
+++ b/src/handlers/gateway/create/index.tsx
@@ -12,53 +12,71 @@ import type { Core } from "../../types";
 import { coreOptsFromCtx, parseJsonArrayFlag, parseJsonObjectFlag, parseTags } from "../../utils";
 import type { CreateGatewayInput } from "../types";
 
+const CONFIGURATION = "Configuration:";
+const PROTOCOL = "Protocol:";
+const AUTHORIZER = "Authorizer:";
+const POLICY_ENGINE = "Policy engine:";
+
 export const createCreateGatewayHandler = (core: Core, io: AppIO) =>
   createHandler({
     name: "create",
     description: "create an AgentCore Gateway",
     flags: [
-      flag("name", "the Gateway name", z.string().optional()),
-      flag("role-arn", "IAM role the Gateway assumes", z.string().optional()),
+      flag("name", "the Gateway name", z.string().optional(), { group: CONFIGURATION }),
+      flag("role-arn", "IAM role the Gateway assumes", z.string().optional(), {
+        group: CONFIGURATION,
+      }),
+      flag("description", "Gateway description", z.string().optional(), { group: CONFIGURATION }),
+      flag("kms-key-arn", "KMS key ARN", z.string().optional(), { group: CONFIGURATION }),
+      flag("exception-level", "exception detail level: debug", z.enum(["debug"]).optional(), {
+        group: CONFIGURATION,
+      }),
+      flag(
+        "tags",
+        "tags as repeated key=value or a JSON object (inline, file://<path>, or - for stdin)",
+        z.array(z.string()).optional(),
+        { group: CONFIGURATION },
+      ),
+      flag("client-token", "idempotency token", z.string().optional(), { group: CONFIGURATION }),
       flag(
         "protocol",
         "restrict Target protocols to MCP; omitted allows every Target protocol",
         z.enum(["mcp"]).optional(),
+        { group: PROTOCOL },
       ),
-      flag(
-        "authorizer-type",
-        "inbound authorizer: AWS_IAM, CUSTOM_JWT, NONE, or AUTHENTICATE_ONLY",
-        z.enum(["AWS_IAM", "CUSTOM_JWT", "NONE", "AUTHENTICATE_ONLY"]).optional(),
-      ),
-      flag("description", "Gateway description", z.string().optional()),
       flag(
         "protocol-configuration",
         "MCP protocol configuration (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: PROTOCOL },
+      ),
+      flag(
+        "authorizer-type",
+        "inbound authorizer: AWS_IAM, CUSTOM_JWT, NONE, or AUTHENTICATE_ONLY",
+        z.enum(["AWS_IAM", "CUSTOM_JWT", "NONE", "AUTHENTICATE_ONLY"]).optional(),
+        { group: AUTHORIZER },
       ),
       flag(
         "authorizer-configuration",
         "authorizer configuration (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: AUTHORIZER },
       ),
-      flag("kms-key-arn", "KMS key ARN", z.string().optional()),
       flag(
         "interceptor-configurations",
         "interceptor configurations (JSON array; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: "Interceptors:" },
       ),
-      flag("policy-engine-arn", "Policy Engine ARN", z.string().optional()),
+      flag("policy-engine-arn", "Policy Engine ARN", z.string().optional(), {
+        group: POLICY_ENGINE,
+      }),
       flag(
         "policy-engine-mode",
         "Policy Engine mode: log-only or enforce",
         z.enum(["log-only", "enforce"]).optional(),
+        { group: POLICY_ENGINE },
       ),
-      flag("exception-level", "exception detail level: debug", z.enum(["debug"]).optional()),
-      flag(
-        "tags",
-        "tags as repeated key=value or a JSON object (inline, file://<path>, or - for stdin)",
-        z.array(z.string()).optional(),
-      ),
-      flag("client-token", "idempotency token", z.string().optional()),
     ],
     handle: async (ctx, flags) => {
       if (!flags.name) {
diff --git a/src/handlers/gateway/invoke/index.tsx b/src/handlers/gateway/invoke/index.tsx
index 926fb98ab..245820196 100644
--- a/src/handlers/gateway/invoke/index.tsx
+++ b/src/handlers/gateway/invoke/index.tsx
@@ -18,6 +18,10 @@ import {
 import { writeGatewayInvokeResponse } from "./response";
 import { GatewayInvokeLaunchContextKey } from "./launchContext";
 
+const TARGET = "Target:";
+const PAYLOAD = "Payload:";
+const SESSION = "Session:";
+
 export const createInvokeGatewayHandler = (
   core: Core,
   io: AppIO,
@@ -27,31 +31,45 @@ export const createInvokeGatewayHandler = (
     name: "invoke",
     description: "invoke an AgentCore Gateway",
     flags: [
-      flag("id", "the ID of the Gateway", gatewayIdSchema.optional()),
+      flag("id", "the ID of the Gateway", gatewayIdSchema.optional(), { group: TARGET }),
       flag(
         "path",
         "the path relative to the Gateway origin",
         z.string().min(1, "requires a nonempty path").optional(),
-        { sensitive: true },
+        { sensitive: true, group: TARGET },
       ),
-      flag("method", "the HTTP request method", z.enum(["GET", "POST", "DELETE"]).optional()),
-      flag("payload", "the inline payload to send", z.string().optional(), { sensitive: true }),
-      flag("content-type", "the payload content type", z.string().optional()),
-      flag("accept", "the accepted response content type", z.string().optional()),
-      flag("header", "an ordered application header", z.array(z.string()).optional(), {
-        sensitive: true,
+      flag("method", "the HTTP request method", z.enum(["GET", "POST", "DELETE"]).optional(), {
+        group: TARGET,
       }),
-      flag("bearer-token", "the Gateway bearer token", z.string().optional(), {
+      flag("payload", "the inline payload to send", z.string().optional(), {
         sensitive: true,
+        group: PAYLOAD,
+      }),
+      flag("content-type", "the payload content type", z.string().optional(), { group: PAYLOAD }),
+      flag("accept", "the accepted response content type", z.string().optional(), {
+        group: PAYLOAD,
       }),
-      flag("session-id", "the Runtime target session ID", z.string().optional()),
-      flag("mcp-session-id", "the MCP session ID", z.string().optional()),
-      flag("mcp-protocol-version", "the MCP protocol version", z.string().optional()),
       flag(
         "output-file",
         "the response output file",
         z.string().min(1, "requires a nonempty path").optional(),
+        { group: PAYLOAD },
       ),
+      flag("bearer-token", "the Gateway bearer token", z.string().optional(), {
+        sensitive: true,
+        group: "Authentication:",
+      }),
+      flag("header", "an ordered application header", z.array(z.string()).optional(), {
+        sensitive: true,
+        group: "Application headers:",
+      }),
+      flag("session-id", "the Runtime target session ID", z.string().optional(), {
+        group: SESSION,
+      }),
+      flag("mcp-session-id", "the MCP session ID", z.string().optional(), { group: SESSION }),
+      flag("mcp-protocol-version", "the MCP protocol version", z.string().optional(), {
+        group: SESSION,
+      }),
     ],
     handle: async (ctx, flags) => {
       if (flags.id === undefined) {
diff --git a/src/handlers/gateway/target/create/index.tsx b/src/handlers/gateway/target/create/index.tsx
index e6eec4789..4abe540e9 100644
--- a/src/handlers/gateway/target/create/index.tsx
+++ b/src/handlers/gateway/target/create/index.tsx
@@ -19,45 +19,55 @@ import {
 } from "../../../utils";
 import type { CreateGatewayTargetInput } from "../../types";
 
+const TARGET = "Target:";
+const DEFINITION = "Definition:";
+const CREDENTIALS = "Credentials & networking:";
+
 export const createCreateGatewayTargetHandler = (core: Core, io: AppIO) =>
   createHandler({
     name: "create",
     description: "create a Gateway Target",
     flags: [
-      flag("gateway-id", "the parent Gateway ID", z.string().optional()),
+      flag("gateway-id", "the parent Gateway ID", z.string().optional(), { group: TARGET }),
       flag(
         "name",
         "Target name; optional only for AgentCore Runtime Targets",
         z.string().optional(),
+        { group: TARGET },
       ),
-      flag("description", "Target description", z.string().optional()),
-      flag("endpoint", "MCP server HTTPS endpoint", z.string().optional()),
+      flag("description", "Target description", z.string().optional(), { group: TARGET }),
+      flag("endpoint", "MCP server HTTPS endpoint", z.string().optional(), { group: DEFINITION }),
       flag(
         "target-configuration",
         "complete Target configuration (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: DEFINITION },
       ),
       flag(
         "tool-schema",
         "MCP tool schema (inline JSON, file://<path>, - for stdin, or s3:// URI)",
         z.string().optional(),
+        { group: DEFINITION },
       ),
       flag(
         "credential-provider-configurations",
         "outbound credentials (JSON array; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CREDENTIALS },
       ),
       flag(
         "metadata-configuration",
         "metadata propagation (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CREDENTIALS },
       ),
       flag(
         "private-endpoint",
         "private endpoint (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CREDENTIALS },
       ),
-      flag("client-token", "idempotency token", z.string().optional()),
+      flag("client-token", "idempotency token", z.string().optional(), { group: "Idempotency:" }),
     ],
     handle: async (ctx, flags) => {
       if (!flags["gateway-id"]) {
diff --git a/src/handlers/gateway/target/update/index.tsx b/src/handlers/gateway/target/update/index.tsx
index b9427a793..9ebb11e6c 100644
--- a/src/handlers/gateway/target/update/index.tsx
+++ b/src/handlers/gateway/target/update/index.tsx
@@ -18,40 +18,62 @@ import {
 } from "../../../utils";
 import type { GatewayTargetUpdatePatch } from "../../types";
 
+const TARGET = "Target:";
+const DEFINITION = "Definition:";
+const CREDENTIALS = "Credentials & networking:";
+const CLEAR = "Clear (unset a field):";
+
 export const createUpdateGatewayTargetHandler = (core: Core, io: AppIO) =>
   createHandler({
     name: "update",
     description: "update a Gateway Target",
     flags: [
-      flag("gateway-id", "the parent Gateway ID", z.string().optional()),
-      flag("target-id", "the Target ID", z.string().optional()),
-      flag("name", "updated Target name", z.string().optional()),
-      flag("description", "updated Target description", z.string().optional()),
-      flag("endpoint", "updated endpoint for an existing MCP server Target", z.string().optional()),
+      flag("gateway-id", "the parent Gateway ID", z.string().optional(), { group: TARGET }),
+      flag("target-id", "the Target ID", z.string().optional(), { group: TARGET }),
+      flag("name", "updated Target name", z.string().optional(), { group: TARGET }),
+      flag("description", "updated Target description", z.string().optional(), { group: TARGET }),
+      flag(
+        "endpoint",
+        "updated endpoint for an existing MCP server Target",
+        z.string().optional(),
+        {
+          group: DEFINITION,
+        },
+      ),
       flag(
         "target-configuration",
         "complete replacement Target configuration (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: DEFINITION },
       ),
       flag(
         "credential-provider-configurations",
         "replacement outbound credentials (JSON array; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CREDENTIALS },
       ),
       flag(
         "metadata-configuration",
         "replacement metadata propagation (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CREDENTIALS },
       ),
       flag(
         "private-endpoint",
         "replacement private endpoint (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: CREDENTIALS },
       ),
-      flag("clear-description", "remove the Target description", z.boolean()),
-      flag("clear-credential-provider-configurations", "remove outbound credentials", z.boolean()),
-      flag("clear-metadata-configuration", "remove metadata propagation", z.boolean()),
-      flag("clear-private-endpoint", "remove private endpoint configuration", z.boolean()),
+      flag("clear-description", "remove the Target description", z.boolean(), { group: CLEAR }),
+      flag("clear-credential-provider-configurations", "remove outbound credentials", z.boolean(), {
+        group: CLEAR,
+      }),
+      flag("clear-metadata-configuration", "remove metadata propagation", z.boolean(), {
+        group: CLEAR,
+      }),
+      flag("clear-private-endpoint", "remove private endpoint configuration", z.boolean(), {
+        group: CLEAR,
+      }),
     ],
     handle: async (ctx, flags) => {
       if (!flags["gateway-id"]) {
diff --git a/src/handlers/gateway/update/index.tsx b/src/handlers/gateway/update/index.tsx
index 0714c8e10..ef8365f60 100644
--- a/src/handlers/gateway/update/index.tsx
+++ b/src/handlers/gateway/update/index.tsx
@@ -19,58 +19,87 @@ import {
 } from "../../utils";
 import type { GatewayUpdatePatch } from "../types";
 
+const CONFIGURATION = "Configuration:";
+const PROTOCOL_AUTHORIZER = "Protocol & authorizer:";
+const TRANSFORM = "Transform & interceptors:";
+const POLICY_ENGINE = "Policy engine:";
+const CLEAR = "Clear (unset a field):";
+
 export const createUpdateGatewayHandler = (core: Core, io: AppIO) =>
   createHandler({
     name: "update",
     description: "update an AgentCore Gateway",
     flags: [
-      flag("id", "the Gateway ID", z.string().optional()),
-      flag("role-arn", "updated IAM role ARN", z.string().optional()),
-      flag("description", "updated Gateway description", z.string().optional()),
+      flag("id", "the Gateway ID", z.string().optional(), { group: "Target:" }),
+      flag("role-arn", "updated IAM role ARN", z.string().optional(), { group: CONFIGURATION }),
+      flag("description", "updated Gateway description", z.string().optional(), {
+        group: CONFIGURATION,
+      }),
+      flag("exception-level", "exception detail level: debug", z.enum(["debug"]).optional(), {
+        group: CONFIGURATION,
+      }),
       flag(
         "protocol-configuration",
         "replacement MCP protocol configuration (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: PROTOCOL_AUTHORIZER },
       ),
       flag(
         "authorizer-configuration",
         "replacement CUSTOM_JWT configuration (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: PROTOCOL_AUTHORIZER },
       ),
       flag(
         "custom-transform-configuration",
         "replacement custom transform configuration (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: TRANSFORM },
       ),
       flag(
         "interceptor-configurations",
         "replacement interceptors (JSON array; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: TRANSFORM },
       ),
-      flag("policy-engine-arn", "Policy Engine ARN", z.string().optional()),
+      flag("policy-engine-arn", "Policy Engine ARN", z.string().optional(), {
+        group: POLICY_ENGINE,
+      }),
       flag(
         "policy-engine-mode",
         "Policy Engine mode: log-only or enforce",
         z.enum(["log-only", "enforce"]).optional(),
+        { group: POLICY_ENGINE },
       ),
-      flag("exception-level", "exception detail level: debug", z.enum(["debug"]).optional()),
       flag(
         "waf-configuration",
         "replacement WAF configuration (JSON; inline, file://<path>, or - for stdin)",
         z.string().optional(),
+        { group: "WAF:" },
       ),
-      flag("clear-protocol", "remove the MCP-only Target restriction", z.boolean()),
-      flag("clear-description", "remove the Gateway description", z.boolean()),
-      flag("clear-protocol-configuration", "remove MCP protocol overrides", z.boolean()),
+      flag("clear-protocol", "remove the MCP-only Target restriction", z.boolean(), {
+        group: CLEAR,
+      }),
+      flag("clear-description", "remove the Gateway description", z.boolean(), { group: CLEAR }),
+      flag("clear-protocol-configuration", "remove MCP protocol overrides", z.boolean(), {
+        group: CLEAR,
+      }),
       flag(
         "clear-custom-transform-configuration",
         "remove the custom transform configuration",
         z.boolean(),
+        { group: CLEAR },
       ),
-      flag("clear-interceptor-configurations", "remove every interceptor", z.boolean()),
-      flag("clear-policy-engine", "detach the Policy Engine", z.boolean()),
-      flag("clear-exception-level", "return to generic invocation errors", z.boolean()),
-      flag("clear-waf-configuration", "reset WAF failure mode to FAIL_CLOSE", z.boolean()),
+      flag("clear-interceptor-configurations", "remove every interceptor", z.boolean(), {
+        group: CLEAR,
+      }),
+      flag("clear-policy-engine", "detach the Policy Engine", z.boolean(), { group: CLEAR }),
+      flag("clear-exception-level", "return to generic invocation errors", z.boolean(), {
+        group: CLEAR,
+      }),
+      flag("clear-waf-configuration", "reset WAF failure mode to FAIL_CLOSE", z.boolean(), {
+        group: CLEAR,
+      }),
     ],
     handle: async (ctx, flags) => {
       if (!flags.id) {