go-cli-flag-parity

Answer

Root cause. In cmd/root.go both flow run and flow create were built as inline &cobra.Command{...} literals. The inline flow run had triggerPayload = nil hardcoded (root.go:403), and flow create had no --name flag (positional-only) — while the engine/dashboard already supported both features.

Fix 1 — convert inline commands to named vars so flags can be registered (GAP-004/GAP-005):

var (
    // GAP-004: named var (was inline) so the --payload flag can be registered.
    flowRunCmd = &cobra.Command{
        Use:   "run",
        Short: "Run a flow via the dashboard",
        Args:  cobra.NoArgs,
        RunE: func(cmd *cobra.Command, args []string) error {
            payload, err := parsePayloadFlag(cmd)
            if err != nil {
                return err
            }
            return flowRunViaDashboard(cmd.Context(), payload, serverAddr)
        },
    }

    // GAP-005: named var (was inline); MaximumNArgs(1) + name resolution.
    flowCreateCmd = &cobra.Command{
        Use:   "create [name]",
        Short: "Create a flow",
        Args:  cobra.MaximumNArgs(1),
        RunE: func(cmd *cobra.Command, args []string) error {
            flagName, _ := cmd.Flags().GetString("name")
            name, err := resolveFlowName(flagName, args)
            if err != nil {
                return err
            }
            return createFlow(cmd.Context(), name, serverAddr)
        },
    }
)

func init() {
    // GAP-004: --payload string flag + json.Unmarshal.
    flowRunCmd.Flags().String("payload", "",
        "trigger payload as JSON, e.g. '{\"type\":\"webhook\",\"endpoint\":\"/cb\"}'")
    // GAP-005: --name flag (command was positional-only).
    flowCreateCmd.Flags().String("name", "", "flow name (alternative to the positional argument)")
    flowCmd.AddCommand(flowRunCmd, flowCreateCmd)
    rootCmd.AddCommand(flowCmd)
}

Fix 2 — --payload parsing replaces the hardcoded nil (no silent nil dispatch):

// parsePayloadFlag reads --payload and json.Unmarshal's it into a
// TriggerPayload. Previously hardcoded to nil at root.go:403.
func parsePayloadFlag(cmd *cobra.Command) (flow.TriggerPayload, error) {
    raw, err := cmd.Flags().GetString("payload")
    if err != nil {
        return flow.TriggerPayload{}, err
    }
    if raw == "" {
        return flow.TriggerPayload{}, errors.New("flag --payload is required (JSON trigger payload)")
    }
    var p flow.TriggerPayload
    if err := json.Unmarshal([]byte(raw), &p); err != nil {
        return flow.TriggerPayload{}, fmt.Errorf("invalid --payload JSON: %w", err)
    }
    return p, nil
}

Fix 3 — flowRunViaDashboard wraps the payload as {"trigger": {...}} to match server.go handleFlowRun:

// flowRunViaDashboard wraps the user payload as {"trigger": {...}} to match
// the schema documented in server.go handleFlowRun.
func flowRunViaDashboard(ctx context.Context, p flow.TriggerPayload, addr string) error {
    body := map[string]any{"trigger": p}
    return flow.Dispatch(ctx, addr+"/api/flows/run", body)
}

// server.go — documented decode schema the wrapper must match:
//
//  {
//    "trigger": { "type": "webhook", "endpoint": "/cb", "config": { ... } }
//  }
type FlowRunRequest struct {
    Trigger *flow.TriggerPayload `json:"trigger"`
}

func handleFlowRun(w http.ResponseWriter, r *http.Request) {
    var req FlowRunRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, fmt.Sprintf("bad request body: %v", err), http.StatusBadRequest)
        return
    }
    if req.Trigger == nil {
        http.Error(w, "missing trigger: body must be {\"trigger\": {...}}", http.StatusBadRequest)
        return
    }
    fmt.Fprintf(w, `{"status":"ok","trigger_type":%q}`, req.Trigger.Type)
}

Fix 4 — GAP-005 name resolution (flag wins / conflict error / neither errors):

func resolveFlowName(flagName string, args []string) (string, error) {
    positional := ""
    if len(args) == 1 {
        positional = args[0]
    }
    switch {
    case flagName == "" && positional == "":
        return "", errors.New("flow name required: pass --name <name> or a positional argument")
    case flagName != "" && positional != "" && flagName != positional:
        return "", fmt.Errorf("conflicting flow names: --name %q vs positional %q", flagName, positional)
    case flagName != "":
        return flagName, nil // flag wins
    default:
        return positional, nil
    }
}