docs(cli): add cli.arguments annotations for connection get/update/delete/disable/enable/pause/unpause/upsert

Enables website generator to emit required positional placeholders in asides.

Made-with: Cursor

Author: leggetter

pkg/cmd/connection_delete.go

@@ -33,6 +33,9 @@ Examples:
 		PreRunE: cc.validateFlags,
 		RunE:    cc.runConnectionDeleteCmd,
 	}
+	cc.cmd.Annotations = map[string]string{
+		"cli.arguments": `[{"name":"connection-id","type":"string","description":"Connection ID","required":true}]`,
+	}
 
 	cc.cmd.Flags().BoolVar(&cc.force, "force", false, "Force delete without confirmation")
 

pkg/cmd/connection_disable.go

@@ -23,6 +23,9 @@ func newConnectionDisableCmd() *connectionDisableCmd {
 		Long:  LongDisableIntro(ResourceConnection),
 		RunE: cc.runConnectionDisableCmd,
 	}
+	cc.cmd.Annotations = map[string]string{
+		"cli.arguments": `[{"name":"connection-id","type":"string","description":"Connection ID","required":true}]`,
+	}
 
 	return cc
 }

pkg/cmd/connection_enable.go

@@ -23,6 +23,9 @@ func newConnectionEnableCmd() *connectionEnableCmd {
 		Long:  LongEnableIntro(ResourceConnection),
 		RunE: cc.runConnectionEnableCmd,
 	}
+	cc.cmd.Annotations = map[string]string{
+		"cli.arguments": `[{"name":"connection-id","type":"string","description":"Connection ID","required":true}]`,
+	}
 
 	return cc
 }

pkg/cmd/connection_get.go

@@ -39,6 +39,9 @@ Examples:
 	 hookdeck connection get my-connection`,
 		RunE: cc.runConnectionGetCmd,
 	}
+	cc.cmd.Annotations = map[string]string{
+		"cli.arguments": `[{"name":"connection-id-or-name","type":"string","description":"Connection ID or name","required":true}]`,
+	}
 
 	cc.cmd.Flags().StringVar(&cc.output, "output", "", "Output format (json)")
 	addIncludeSourceAuthFlagForConnection(cc.cmd, &cc.includeSourceAuth)

pkg/cmd/connection_pause.go

@@ -25,6 +25,9 @@ func newConnectionPauseCmd() *connectionPauseCmd {
 The connection will queue incoming events until unpaused.`,
 		RunE: cc.runConnectionPauseCmd,
 	}
+	cc.cmd.Annotations = map[string]string{
+		"cli.arguments": `[{"name":"connection-id","type":"string","description":"Connection ID","required":true}]`,
+	}
 
 	return cc
 }

pkg/cmd/connection_unpause.go

@@ -25,6 +25,9 @@ func newConnectionUnpauseCmd() *connectionUnpauseCmd {
 The connection will start processing queued events.`,
 		RunE: cc.runConnectionUnpauseCmd,
 	}
+	cc.cmd.Annotations = map[string]string{
+		"cli.arguments": `[{"name":"connection-id","type":"string","description":"Connection ID","required":true}]`,
+	}
 
 	return cc
 }

pkg/cmd/connection_update.go

@@ -58,6 +58,9 @@ Examples:
 		PreRunE: cu.validateFlags,
 		RunE:    cu.runConnectionUpdateCmd,
 	}
+	cu.cmd.Annotations = map[string]string{
+		"cli.arguments": `[{"name":"connection-id","type":"string","description":"Connection ID","required":true}]`,
+	}
 
 	// Connection fields
 	cu.cmd.Flags().StringVar(&cu.name, "name", "", "New connection name")

pkg/cmd/connection_upsert.go

@@ -63,6 +63,9 @@ func newConnectionUpsertCmd() *connectionUpsertCmd {
 		PreRunE: cu.validateUpsertFlags,
 		RunE:    cu.runConnectionUpsertCmd,
 	}
+	cu.cmd.Annotations = map[string]string{
+		"cli.arguments": `[{"name":"name","type":"string","description":"Connection name (create or update by name)","required":true}]`,
+	}
 
 	// Reuse all flags from create command (name is now a positional argument)
 	cu.cmd.Flags().StringVar(&cu.description, "description", "", "Connection description")

tools/generate-reference/main.go

@@ -282,7 +282,8 @@ func generateHelpOutput(root *cobra.Command, path string, wrap wrapConfig) strin
 	mainBuf.WriteString(globalFlagsTable(root))
 	mainStr := strings.TrimRight(mainBuf.String(), "\n")
 
-	// Examples: available commands (comes after flags, no heading to avoid layout issues)
+	// Examples: available commands (comes after flags, no heading to avoid layout issues).
+	// For leaf subcommands, append placeholders for required flags/args so the line is runnable.
 	var examplesBuf bytes.Buffer
 	if c.HasAvailableSubCommands() {
 		examplesBuf.WriteString("```bash\n")
@@ -292,6 +293,17 @@ func generateHelpOutput(root *cobra.Command, path string, wrap wrapConfig) strin
 			}
 			cmdPath := sub.CommandPath()
 			examplesBuf.WriteString(cmdPath)
+			// Append required flags/args placeholders for leaf commands so aside lines are runnable.
+			if !sub.HasAvailableSubCommands() {
+				suffix := exampleSuffixForRequired(sub)
+				// Metrics subcommands always need --start/--end and --measures; ensure we never emit a bare line.
+				if suffix == "" && strings.Contains(cmdPath, " metrics ") {
+					suffix = "--start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z --measures count"
+				}
+				if suffix != "" {
+					examplesBuf.WriteString(" " + suffix)
+				}
+			}
 			if sub.Short != "" {
 				examplesBuf.WriteString("  # " + sub.Short)
 			}
@@ -633,6 +645,126 @@ type argSpec struct {
 	Required    bool   `json:"required"`
 }
 
+// bashCompOneRequiredFlag is the pflag annotation key Cobra sets for required flags.
+// Cobra uses this in ValidateRequiredFlags; we use it to discover required flags for example placeholders.
+const bashCompOneRequiredFlag = "cobra_annotation_bash_completion_one_required_flag"
+
+// requiredFlags returns the list of required flag names for c (local flags only), in visit order.
+func requiredFlags(c *cobra.Command) []string {
+	var names []string
+	c.Flags().VisitAll(func(f *pflag.Flag) {
+		if f.Hidden {
+			return
+		}
+		ann, ok := f.Annotations[bashCompOneRequiredFlag]
+		if !ok || len(ann) == 0 || ann[0] != "true" {
+			return
+		}
+		names = append(names, f.Name)
+	})
+	return names
+}
+
+// requiredArgsFromAnnotations returns required positional args from c.Annotations["cli.arguments"] in order.
+func requiredArgsFromAnnotations(c *cobra.Command) []argSpec {
+	if c.Annotations == nil {
+		return nil
+	}
+	raw, ok := c.Annotations["cli.arguments"]
+	if !ok || raw == "" {
+		return nil
+	}
+	var args []argSpec
+	if err := json.Unmarshal([]byte(raw), &args); err != nil {
+		return nil
+	}
+	var out []argSpec
+	for _, a := range args {
+		if a.Required {
+			out = append(out, a)
+		}
+	}
+	return out
+}
+
+// exampleSuffixForRequired returns a placeholder string for required flags and args for use in example lines.
+// Used by the command-group aside and (optionally) per-command examples. Returns empty if no required flags/args.
+func exampleSuffixForRequired(c *cobra.Command) string {
+	flags := requiredFlags(c)
+	args := requiredArgsFromAnnotations(c)
+	path := c.CommandPath()
+	isMetrics := strings.Contains(path, " metrics ")
+	// Metrics subcommands always require --start, --end, and --measures (CLI/API enforce this). If annotation wasn't found, still add them.
+	if isMetrics && len(flags) == 0 && len(args) == 0 {
+		return "--start 2025-01-01T00:00:00Z --end 2025-01-02T00:00:00Z --measures count"
+	}
+	if len(flags) == 0 && len(args) == 0 {
+		return ""
+	}
+	var parts []string
+
+	// Time range: start and end (metrics subcommands)
+	hasStart := false
+	hasEnd := false
+	for _, n := range flags {
+		if n == "start" {
+			hasStart = true
+		}
+		if n == "end" {
+			hasEnd = true
+		}
+	}
+	if hasStart && hasEnd && isMetrics {
+		parts = append(parts, "--start 2025-01-01T00:00:00Z", "--end 2025-01-02T00:00:00Z")
+	}
+	// measures (metrics)
+	for _, n := range flags {
+		if n == "measures" && isMetrics {
+			parts = append(parts, "--measures count")
+			break
+		}
+	}
+	// Other required flags not yet added
+	for _, n := range flags {
+		if (n == "start" || n == "end") && isMetrics {
+			continue
+		}
+		if n == "measures" && isMetrics {
+			continue
+		}
+		switch n {
+		case "name":
+			if !sliceContains(parts, "--name") {
+				parts = append(parts, "--name <name>")
+			}
+		case "type":
+			if !sliceContains(parts, "--type") {
+				parts = append(parts, "--type <type>")
+			}
+		case "status":
+			if !sliceContains(parts, "--status") {
+				parts = append(parts, "--status acknowledged")
+			}
+		default:
+			parts = append(parts, "--"+n+" <value>")
+		}
+	}
+	// Required positionals
+	for _, a := range args {
+		parts = append(parts, "<"+a.Name+">")
+	}
+	return strings.Join(parts, " ")
+}
+
+func sliceContains(parts []string, s string) bool {
+	for _, p := range parts {
+		if strings.HasPrefix(p, s+" ") || p == s {
+			return true
+		}
+	}
+	return false
+}
+
 // renderArgumentsTable returns a markdown Arguments table if c.Annotations["cli.arguments"] contains
 // valid JSON array of argSpec. Used to document positional args before the Flags table.
 func renderArgumentsTable(c *cobra.Command) string {