cmd: fix help text and examples

Author: somanshreddy

cmd/heygen/builder.go

@@ -156,7 +156,7 @@ func buildCobraCommand(spec *command.Spec, ctx *cmdContext) *cobra.Command {
 	// Add -d/--data for commands with JSON request bodies
 	if spec.BodyEncoding == "json" {
 		cmd.Flags().StringVarP(&rawData, "data", "d", "",
-			"JSON request body (inline JSON, file path, or - for stdin)")
+			"JSON request body (inline JSON, file path, or - for stdin). When used with individual flags, flags override matching fields in the JSON.")
 	}
 
 	return cmd

cmd/heygen/generated_root_test.go

@@ -130,6 +130,23 @@ func TestGeneratedRoot_IntermediateHelp(t *testing.T) {
 	}
 }
 
+func TestGeneratedRoot_Help_ShowsExitCodesAndHidesCompletion(t *testing.T) {
+	srv := setupTestServer(t, map[string]testHandler{})
+	defer srv.Close()
+
+	res := runCommand(t, srv.URL, "test-key", "--help")
+
+	if res.ExitCode != 0 {
+		t.Errorf("ExitCode = %d, want 0\nstderr: %s", res.ExitCode, res.Stderr)
+	}
+	if !strings.Contains(res.Stdout, "Exit Codes:") || !strings.Contains(res.Stdout, "3   Authentication error") {
+		t.Errorf("root help missing documented exit codes\nstdout: %s", res.Stdout)
+	}
+	if strings.Contains(res.Stdout, "completion") {
+		t.Errorf("root help should hide completion command\nstdout: %s", res.Stdout)
+	}
+}
+
 func TestGeneratedRoot_VideoAgentHelp_FlattensNestedLeaves(t *testing.T) {
 	srv := setupTestServer(t, map[string]testHandler{})
 	defer srv.Close()

cmd/heygen/root.go

@@ -26,7 +26,13 @@ Environment Variables:
   HEYGEN_API_KEY     API key for authentication (overrides stored credentials)
   HEYGEN_OUTPUT      Output format: json, human (default: json)
 
-Use "heygen config list" to see all configuration settings and their sources.`,
+Use "heygen config list" to see all configuration settings and their sources.
+
+Exit Codes:
+  0   Success
+  1   General error (API error, network failure)
+  2   Usage error (invalid flags, missing arguments)
+  3   Authentication error (missing or invalid API key)`,
 		Version:       version,
 		SilenceUsage:  true, // we handle usage errors ourselves
 		SilenceErrors: true, // we handle error output ourselves
@@ -39,6 +45,7 @@ Use "heygen config list" to see all configuration settings and their sources.`,
 	root.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error {
 		return clierrors.NewUsage(err.Error())
 	})
+	root.CompletionOptions.HiddenDefaultCmd = true
 	root.PersistentFlags().Bool("human", false, "Display output as a formatted table instead of JSON")
 
 	root.AddCommand(newAuthCmd(ctx))
@@ -70,6 +77,7 @@ func newRootCmdWithSpecs(version string, formatter output.Formatter, groups map[
 	root.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error {
 		return clierrors.NewUsage(err.Error())
 	})
+	root.CompletionOptions.HiddenDefaultCmd = true
 	root.PersistentFlags().Bool("human", false, "Display output as a formatted table instead of JSON")
 
 	root.AddCommand(newAuthCmd(ctx))

codegen/examples/video-agent.yaml

@@ -1,5 +1,6 @@
 "POST /v3/video-agents":
-  - "heygen video-agent create --prompt 'Make a product demo' --style-id modern"
+  - "heygen video-agent create --prompt 'Make a product demo'"
+  - "heygen video-agent create -d '{\"prompt\":\"Make a product demo\"}'"
 "GET /v3/video-agents/styles":
   - "heygen video-agent styles list"
 "POST /v3/video-agents/sessions":
@@ -9,6 +10,6 @@
 "POST /v3/video-agents/sessions/{session_id}/messages":
   - "heygen video-agent sessions messages create <session-id> --message 'Add intro'"
 "GET /v3/video-agents/sessions/{session_id}/resources":
-  - "heygen video-agent sessions resources list <session-id>"
+  - "heygen video-agent sessions resources get <session-id>"
 "POST /v3/video-agents/sessions/{session_id}/stop":
   - "heygen video-agent sessions stop <session-id>"

codegen/examples/video-translate.yaml

@@ -4,6 +4,7 @@
   - "heygen video-translate get <video-translation-id>"
 "POST /v3/video-translations":
   - "cat request.json | heygen video-translate create -d -"
+  - "heygen video-translate create --output-languages es --mode precision"
 "PATCH /v3/video-translations/{video_translation_id}":
   - "heygen video-translate update <video-translation-id> --title 'New title'"
 "DELETE /v3/video-translations/{video_translation_id}":

codegen/examples/video.yaml

@@ -2,7 +2,7 @@
   - "heygen video list --limit 10"
   - "heygen video list --folder-id abc123"
 "POST /v3/videos":
-  - "heygen video create --avatar-id josh_lite --script 'Hello world' --voice-id en_male"
+  - "heygen video create -d '{\"video_inputs\":[{\"character\":{\"type\":\"avatar\",\"avatar_id\":\"josh_lite\"},\"voice\":{\"type\":\"text\",\"voice_id\":\"en_male\",\"input_text\":\"Hello world\"}}]}'"
 "GET /v3/videos/{video_id}":
   - "heygen video get <video-id>"
 "DELETE /v3/videos/{video_id}":

codegen/grouper.go

@@ -58,13 +58,22 @@ import (
 // Used by the builder for group command help text.
 type GroupDescriptions map[string]string
 
+var descriptionOverrides = GroupDescriptions{
+	"voice":   "Create speech audio and manage voices",
+	"webhook": "Create, list, and manage webhook endpoints and events",
+}
+
 func GroupEndpoints(doc *openapi3.T, examples Examples) (command.Groups, GroupDescriptions, error) {
 	groups := make(command.Groups)
 	descriptions := make(GroupDescriptions)
 
 	// Collect tag descriptions from the spec's top-level tags array
 	for _, tag := range doc.Tags {
 		groupName := deriveGroupName(tag.Name)
+		if override, ok := descriptionOverrides[groupName]; ok {
+			descriptions[groupName] = override
+			continue
+		}
 		if tag.Description != "" {
 			descriptions[groupName] = tag.Description
 		}