cli AGENTS.md

AGENTS.md

Command pattern - always use RegisterCLICommand

All new commands must use the struct-based pattern. Do not copy the old flat var cmd = &cobra.Command{...} commands - they exist in cmd/storage/, cmd/dns/, cmd/dbaas/ and are legacy.

Read this file before writing any new command: cmd/aiservices/deployment/deployment_create.go

For subcommand placement in an existing group, also read ## Folder layout below.

Skeleton:

type myResourceCreateCmd struct {
    exocmd.CliCommandSettings `cli-cmd:"-"`

    _ bool `cli-cmd:"create"`

    Name string `cli-arg:"#"  cli-usage:"NAME"`        // required positional
    Tag  string `cli-arg:"?"  cli-usage:"TAG"`          // optional positional
    Zone string `cli-short:"z" cli-usage:"zone"`        // becomes --zone / -z flag
}

func (c *myResourceCreateCmd) CmdAliases() []string { return exocmd.GCreateAlias }
func (c *myResourceCreateCmd) CmdShort() string     { return "Create a resource" }
func (c *myResourceCreateCmd) CmdLong() string      { return "..." }

func (c *myResourceCreateCmd) CmdPreRun(cmd *cobra.Command, args []string) error {
    exocmd.CmdSetZoneFlagFromDefault(cmd)
    return exocmd.CliCommandDefaultPreRun(c, cmd, args)
}

func (c *myResourceCreateCmd) CmdRun(_ *cobra.Command, _ []string) error {
    // c.Name, c.Zone are already populated here
    return nil
}

func init() {
    cobra.CheckErr(exocmd.RegisterCLICommand(parentCmd, &myResourceCreateCmd{
        CliCommandSettings: exocmd.DefaultCLICmdSettings(),
    }))
}

Supported struct tags:

Tag	Purpose
cli-cmd:"-"	Exclude field from CLI processing
cli-cmd:"name"	Sets the cobra command name (use on a _ bool field)
cli-arg:"#"	Required positional argument
cli-arg:"?"	Optional positional argument; []string becomes variadic
cli-flag:"flag-name"	Override the auto-derived kebab-case flag name
cli-short:"z"	Single-character shorthand
cli-usage:"text"	Flag usage string; also used as positional arg label in help
cli-hidden:""	Mark flag hidden
cli-deprecated:"msg"	Mark flag deprecated