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 shelf resources, and consider a request to list books in a shelf:

message ListBooksRequest {
  // Required. The shelf containing the books to list, for example,
  // "projects/project1/shelves/shelf1".
  string parent = 1;

  // 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 shelves books list SHELF (positional) and gcloud shelves books list --shelf=SHELF (flag).


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 shelf. Commands in the books command group should reserve positional arguments for book resources. Thus, the shelf argument for the list command should be a flag:

gcloud shelves books list --shelf=SHELF