Context

Hyoka's CLI is built with Cobra, a popular Go CLI framework. Commands are organized in the cmd/ package with consistent flag naming and help text patterns.

Command Structure

Each command is a Cobra command object:

go
1// cmd/run.go
2var runCmd = &cobra.Command{
3    Use:   "run",
4    Short: "Run evaluation",
5    Long:  "Run an evaluation with prompts and configs.",
6    
7    Args: cobra.NoArgs,  // Positional arguments check
8    
9    RunE: func(cmd *cobra.Command, args []string) error {
10        // Retrieve flags
11        promptID, _ := cmd.Flags().GetString("prompt-id")
12        config, _ := cmd.Flags().GetString("config")
13        
14        // Validate
15        if promptID == "" && config == "" {
16            return fmt.Errorf("either --prompt-id or --config required")
17        }
18        
19        // Execute
20        return run(promptID, config)
21    },
22}
23
24func init() {
25    rootCmd.AddCommand(runCmd)
26    runCmd.Flags().StringP("prompt-id", "", "", "Single prompt ID")
27    runCmd.Flags().StringP("config", "", "", "Config (comma-sep for multiple)")
28}

Flag Naming Conventions

• Kebab-case: --log-level, --max-files, --prompt-id (not --logLevel, --maxfiles)
• Short flags: Single-letter for common flags (e.g., -v for --verbose)
• Suffixes:
  • --*-timeout for duration limits (e.g., --gen-timeout)
  • --skip-* for skipping phases (e.g., --skip-review)
  • --*-file for file paths (e.g., --log-file)

Flag Types and Patterns

String flags:

go
1cmd.Flags().StringP("config", "", "", "Config name")

Comma-separated lists:

go
1cmd.Flags().String("tags", "", "Comma-separated tags (must quote: \"auth,crud\")")
2// Parsed as: strings.Split(value, ",")

Boolean flags:

go
1cmd.Flags().Bool("dry-run", false, "Show what would run without executing")

Numeric flags:

go
1cmd.Flags().Int("max-files", 50, "Max files per eval")
2cmd.Flags().Duration("gen-timeout", 600*time.Second, "Generation timeout")

Help Text Guidelines

Keep help text brief but actionable:

// Good
--config          Config name or comma-sep list
--prompt-id       Single prompt ID (e.g., identity-dp-python-default-credential)
--service         Azure service (e.g., identity, key-vault)
--dry-run         List matching prompts without executing

// Bad (too verbose, no examples)
--prompt-id       The prompt identifier
--config          The configuration to use

Command Execution Pattern

go
1RunE: func(cmd *cobra.Command, args []string) error {
2    // 1. Get flags
3    promptID, _ := cmd.Flags().GetString("prompt-id")
4    config, _ := cmd.Flags().GetString("config")
5    
6    // 2. Validate
7    if promptID == "" {
8        return fmt.Errorf("--prompt-id required")
9    }
10    
11    // 3. Execute
12    ctx := context.Background()
13    return executeEval(ctx, promptID, config)
14}

Common Commands in Hyoka

• run — Execute evaluation
• list — List available prompts
• validate — Validate prompt schema
• check-env — Check environment (Copilot SDK, Go version)
• clean — Clean orphaned sessions
• serve — Start local web server for results

Error Handling in Commands

Return errors from RunE. Cobra catches them and prints with exit code 1:

go
1RunE: func(cmd *cobra.Command, args []string) error {
2    result, err := runEval(...)
3    if err != nil {
4        slog.Error("Evaluation failed", "error", err)
5        return err  // Cobra handles exit
6    }
7    return nil
8}

Output and Logging

• User output (results, progress): Write to stdout
• Diagnostic logs: Use slog with --log-level flag
• Errors: Return error from RunE, let Cobra print

Flag Validation Example

go
1RunE: func(cmd *cobra.Command, args []string) error {
2    config, _ := cmd.Flags().GetString("config")
3    allConfigs, _ := cmd.Flags().GetBool("all-configs")
4    
5    if config == "" && !allConfigs {
6        return fmt.Errorf("either --config or --all-configs required")
7    }
8    
9    if config != "" && allConfigs {
10        return fmt.Errorf("cannot use both --config and --all-configs")
11    }
12    
13    return runWithConfig(config, allConfigs)
14}

Related Code Locations

• Root command: hyoka/cmd/root.go
• Subcommands: hyoka/cmd/*.go
• Flag parsing utilities: hyoka/cmd/common.go (if shared parsing logic)

Anti-Patterns

• CamelCase flag names
• Positional arguments instead of flags
• Ambiguous short flags (avoid single -a if context unclear)
• Printing errors and returning them (let Cobra handle)
• Hardcoding defaults without CLI override