AIP-2603

List command arguments

Some list requests take argument(s) for the parent collection in which to list resources. For example, suppose an API has book resources belonging to publisher resources, and consider a request to list books belonging to a publisher:

message ListBooksRequest {
  // The parent, which owns this collection of books.
  // Format: publishers/{publisher}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];

  // The maximum number of items to return.
  int32 page_size = 2;

  // The next_page_token value returned from a previous List request, if any.
  string page_token = 3;
}

For the corresponding gcloud list command, we have the choice between gcloud publishers books list PUBLISHER (positional) and gcloud publishers books list --publisher=PUBLISHER (flag).

Guidance

All list command arguments should be flags, not positionals. In gcloud's resource model, command groups generally correspond to resources, and the positional arguments for commands in a group are reserved for those resources. In the case of a list command that takes an argument, the argument will refer to the parent resource and not the command group's resource; therefore, it should be a flag instead of a positional.

In the example above, the list command takes an argument for a publisher. Commands in the books command group should reserve positional arguments for book resources. Thus, the publisher argument for the list command should be a flag:

gcloud publishers books list --publisher=PUBLISHER

Changelog

• 2020-09-23: Changed the examples from "shelves" to "publishers", to present a better example of resource ownership.