declarative

type ArgSpec struct {
	// APIField is the sub-field name within the structured argument value,
	// typically key or value for map arguments.
	APIField string `yaml:"api_field,omitempty"`
}

type Argument struct {
	// ArgName is the name of the argument as it appears to the user, such as
	// instance-id. For flags gcloud prepends --.
	ArgName string `yaml:"arg_name,omitempty"`

	// APIField is the dot-separated path into the API request message that
	// receives this argument's value, for example instance.displayName.
	APIField string `yaml:"api_field,omitempty"`

	// HelpText is the help text shown for the argument in gcloud help and
	// error messages.
	HelpText string `yaml:"help_text"`

	// Action overrides the argparse action used for the argument, for example
	// store_true or store_true_false. Typically used with boolean fields.
	Action string `yaml:"action,omitempty"`

	// IsPositional makes the argument positional rather than a flag.
	IsPositional bool `yaml:"is_positional"`

	// IsPrimaryResource marks this argument as the primary resource the
	// command operates on. At most one argument per command may set this.
	IsPrimaryResource bool `yaml:"is_primary_resource,omitempty"`

	// RequestIDField is the request-message field that receives the
	// user-supplied resource ID on a create command, for example instanceId.
	RequestIDField string `yaml:"request_id_field,omitempty"`

	// ResourceSpec declares this argument as a gcloud concept resource and
	// describes its collection and attributes.
	ResourceSpec *ResourceSpec `yaml:"resource_spec,omitempty"`

	// Required makes the argument mandatory. gcloud rejects invocations that
	// leave it unset.
	Required bool `yaml:"required"`

	// Repeated accepts more than one value for the argument and maps to a
	// repeated API field.
	Repeated bool `yaml:"repeated,omitempty"`

	// Clearable causes gcloud to also generate companion flags such as
	// --clear-..., --add-..., and --remove-... on update commands.
	Clearable bool `yaml:"clearable,omitempty"`

	// Type selects the gcloud argument parser, for example long, double, or a
	// fully-qualified reference to an ArgDict or ArgList parser.
	Type string `yaml:"type,omitempty"`

	// Default is the value used when the user does not supply the argument.
	Default Default `yaml:"default,omitempty"`

	// Choices is the fixed set of values the user can supply. Used for
	// enum-typed fields; each choice maps an arg_value to an enum_value.
	Choices []Choice `yaml:"choices,omitempty"`

	// Spec lists the sub-fields of a structured argument such as a map. For a
	// map field, Spec typically contains entries for key and value.
	Spec []ArgSpec `yaml:"spec,omitempty"`

	// ResourceMethodParams maps API method parameter names to attribute names
	// on a resource argument. Use it when the API method uses a non-standard
	// parameter name for the resource.
	ResourceMethodParams map[string]string `yaml:"resource_method_params,omitempty"`
}

type Arguments struct {
	// Params is the ordered list of arguments the command accepts. Each entry
	// becomes either a positional argument or a flag.
	Params []Argument `yaml:"params,omitempty"`
}

type Async struct {
	// Collection is the gcloud API collection of the operation resource, for
	// example service.projects.locations.operations.
	Collection []string `yaml:"collection,omitempty"`

	// ExtractResourceResult unwraps the target resource from the operation's
	// response field when the operation completes. Set when the LRO response
	// type matches the resource being created or updated.
	ExtractResourceResult bool `yaml:"extract_resource_result"`
}

type Attribute struct {
	// AttributeName is the user-facing name used for the generated flag, for
	// example project.
	AttributeName string `yaml:"attribute_name,omitempty"`

	// Help is the help text shown for the generated flag.
	Help string `yaml:"help,omitempty"`

	// ParameterName is the API parameter name that this attribute maps to in
	// the request URL, for example projectsId.
	ParameterName string `yaml:"parameter_name,omitempty"`

	// Property is the gcloud core property consulted when the flag is not
	// supplied, for example core/project.
	Property string `yaml:"property,omitempty"`
}

type Choice struct {
	// ArgValue is the value the user types on the command line, typically
	// lowercased and kebab-cased.
	ArgValue string `yaml:"arg_value,omitempty"`

	// EnumValue is the API enum value that ArgValue maps to.
	EnumValue string `yaml:"enum_value,omitempty"`

	// HelpText is the per-choice help shown in gcloud help.
	HelpText string `yaml:"help_text,omitempty"`
}

type Command struct {
	// ReleaseTracks lists the gcloud release tracks the command is registered
	// in. Valid values are "ALPHA", "BETA", and "GA".
	ReleaseTracks []string `yaml:"release_tracks,omitempty"`

	// AutoGenerated marks the command as produced by tooling rather than
	// written by hand. It is informational only.
	AutoGenerated bool `yaml:"auto_generated,omitempty"`

	// Hidden removes the command from gcloud help and the CLI completer.
	// Hidden commands remain runnable for users who know the full path.
	Hidden bool `yaml:"hidden,omitempty"`

	// HelpText supplies the brief, description, and examples shown for this
	// command in gcloud help.
	HelpText HelpText `yaml:"help_text"`

	// Arguments declares the positional arguments and flags the command
	// accepts.
	Arguments Arguments `yaml:"arguments"`

	// Request describes the API request issued when the command runs. It is
	// omitted for commands that do not call an API.
	Request *Request `yaml:"request,omitempty"`

	// Async describes how gcloud polls the long-running operation returned by
	// the API. Present when the method returns an LRO.
	Async *Async `yaml:"async,omitempty"`

	// Response describes how gcloud interprets the API response, for example
	// which field holds the resource ID for --uri support on list commands.
	Response *Response `yaml:"response,omitempty"`

	// Update customizes how update commands build and send patch requests,
	// including field-mask handling.
	Update *Update `yaml:"update,omitempty"`

	// Output customizes how command output is formatted, for example a
	// table(...) projection for list commands.
	Output *Output `yaml:"output,omitempty"`
}

type Default struct {
	// Value holds the default value as it should appear in YAML. A nil pointer
	// means no default was specified.
	Value *any
}

type HelpText struct {
	// Brief is a one-line summary of the command shown in command lists and at
	// the top of gcloud help output.
	Brief string `yaml:"brief"`

	// Description is the detailed help shown under the DESCRIPTION section of
	// gcloud help.
	Description string `yaml:"description"`

	// Examples are the command examples shown under the EXAMPLES section of
	// gcloud help. The literal {command} is expanded to the full command path.
	Examples string `yaml:"examples,omitempty"`
}

type Output struct {
	// Format is a gcloud resource projection expression applied to the command
	// output, for example table(name, state).
	Format string `yaml:"format,omitempty"`
}

type Request struct {
	// APIVersion selects the API version to call, for example v1 or v1beta.
	APIVersion string `yaml:"api_version,omitempty"`

	// Collection is the list of gcloud API collections the command operates
	// on. Multiple entries support AIP-127 multi-pattern resources.
	Collection []string `yaml:"collection,omitempty"`

	// Method is the API method name. When empty, gcloud infers the method
	// from the command type (for example, list for a list command).
	Method string `yaml:"method,omitempty"`

	// StaticFields sets request fields to fixed values regardless of user
	// input. Keys are dot-separated field paths in the request message.
	StaticFields map[string]string `yaml:"static_fields,omitempty"`
}

type ResourceSpec struct {
	// Attributes lists the resource's path components (project, location,
	// resource ID, and so on) in the order they appear in the collection
	// pattern.
	Attributes []Attribute `yaml:"attributes,omitempty"`

	// Collection is the fully-qualified gcloud collection identifier, for
	// example parallelstore.projects.locations.instances.
	Collection string `yaml:"collection,omitempty"`

	// DisableAutoCompleters turns off automatic tab-completion for this
	// resource. Set for cross-API references where the completer would need to
	// call a different service.
	DisableAutoCompleters bool `yaml:"disable_auto_completers"`

	// Name is the singular resource name, for example instance.
	Name string `yaml:"name,omitempty"`

	// PluralName is the plural resource name used in help text, for example
	// instances.
	PluralName string `yaml:"plural_name,omitempty"`
}

type Response struct {
	// IDField is the response field that holds the resource identifier. On
	// list commands it enables the --uri flag.
	IDField string `yaml:"id_field,omitempty"`
}

type Update struct {
	// DisableAutoFieldMask turns off gcloud's automatic field-mask computation
	// from the set of user-specified flags. Set it when the command builds the
	// field mask itself.
	DisableAutoFieldMask bool `yaml:"disable_auto_field_mask,omitempty"`

	// ReadModifyUpdate makes gcloud fetch the current resource, apply the
	// user's changes, and send the result back. Use it for APIs that do not
	// accept partial updates.
	ReadModifyUpdate bool `yaml:"read_modify_update"`
}