Add --include and --exclude and override defaults based on output mode

README.md

@@ -167,6 +167,34 @@ Flags:
 Use "packet [command] --help" for more information about a command.
 ```
 
+## Includes and Excludes
+
+Packet API resource responses may have related resources. These related
+resources can be embedded in the result or referred. Referred resources will
+only include a `Href` value, which includes the unique ID of the resource.
+Embedded resources will be represented with their full API value, which may
+contain additional embedded or referred resources.
+
+The resources that you want embedded can be _included_ in results using
+`--include`.  The resources that you want referred can be _excluded_ with
+`--exclude`.  By excluding some of the embedded-by-default resources, you can
+speed up and reduce the size of responses.  By including referred-by-default
+resources, you can avoid the round trip of subsequent calls.
+
+```sh
+packet devices get --project-id $ID --yaml --exclude=ssh_keys,plan --include=project
+```
+
+These arguments are available in any command that returns a response document.
+The included and excluded fields requested from the API may differ based on the
+output format, for example, for historic reasons, `packet projects get --yaml`
+includes the details of all project members. In the table output format, no
+member related fields are displayed and so `packet projects get` will exclude
+the member resource.
+
+Excluding fields needed for the table output will result in an error. Mixing
+includes and excludes affecting the same top-level field is not supported.
+
 ## Reference
 
 The full CLI documentation can be found [here](docs/packet.md) or by clicking the links below.

cmd/check_capacity.go

@@ -70,6 +70,4 @@ func init() {
 	_ = checkCapacityCommand.MarkFlagRequired("facility")
 	_ = checkCapacityCommand.MarkFlagRequired("plan")
 	_ = checkCapacityCommand.MarkFlagRequired("quantity")
-	checkCapacityCommand.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	checkCapacityCommand.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/create_device.go

@@ -151,6 +151,4 @@ func init() {
 	createDeviceCmd.Flags().BoolVarP(&spotInstance, "spot-instance", "I", false, `Set the device as a spot instance`)
 	createDeviceCmd.Flags().Float64VarP(&spotPriceMax, "spot-price-max", "m", 0, `--spot-price-max=1.2 or -m=1.2`)
 	createDeviceCmd.Flags().StringVarP(&terminationTime, "termination-time", "T", "", `Device termination time: --termination-time="15:04:05"`)
-	createDeviceCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	createDeviceCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/create_organization.go

@@ -80,6 +80,4 @@ func init() {
 	createOrganizationCmd.Flags().StringVarP(&logo, "logo", "l", "", "Logo URL]")
 
 	_ = createOrganizationCmd.MarkFlagRequired("name")
-	createOrganizationCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	createOrganizationCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/create_project.go

@@ -72,6 +72,4 @@ func init() {
 	createProjectCmd.Flags().StringVarP(&paymentMethodID, "payment-method-id", "m", "", "UUID of the payment method")
 
 	_ = createProjectCmd.MarkFlagRequired("name")
-	createProjectCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	createProjectCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/create_ssh-key.go

@@ -65,6 +65,4 @@ func init() {
 
 	_ = createSSHKeyCmd.MarkFlagRequired("label")
 	_ = createSSHKeyCmd.MarkFlagRequired("key")
-	createSSHKeyCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	createSSHKeyCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/create_virtual_network.go

@@ -68,6 +68,4 @@ func init() {
 
 	_ = createVirtualNetworkCmd.MarkFlagRequired("project-id")
 	_ = createVirtualNetworkCmd.MarkFlagRequired("facility")
-	createVirtualNetworkCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	createVirtualNetworkCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/create_volume.go

@@ -83,6 +83,4 @@ func init() {
 	createVolumeCmd.Flags().StringVarP(&billingCycle, "billing-cycle", "b", "hourly", "Billing cycle")
 	createVolumeCmd.Flags().StringVarP(&description, "description", "d", "", "Description of the volume")
 	createVolumeCmd.Flags().BoolVarP(&locked, "locked", "l", false, "Set the volume to be locked")
-	createVolumeCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	createVolumeCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/retrieve_capacity.go

@@ -57,6 +57,4 @@ packet capacity get
 
 func init() {
 	capacityCmd.AddCommand(retrieveCapacityCmd)
-	retrieveCapacityCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retrieveCapacityCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/retrieve_device.go

@@ -46,7 +46,7 @@ packet device get --id [device_UUID]
 		} else if deviceID == "" && projectID == "" {
 			return fmt.Errorf("Either id or project-id should be set.")
 		} else if projectID != "" {
-			devices, _, err := PacknGo.Devices.List(projectID, nil)
+			devices, _, err := PacknGo.Devices.List(projectID, listOptions(nil, nil))
 			if err != nil {
 				return errors.Wrap(err, "Could not list Devices")
 			}
@@ -77,6 +77,4 @@ packet device get --id [device_UUID]
 func init() {
 	retriveDeviceCmd.Flags().StringVarP(&projectID, "project-id", "p", "", "UUID of the project")
 	retriveDeviceCmd.Flags().StringVarP(&deviceID, "id", "i", "", "UUID of the device")
-	retriveDeviceCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retriveDeviceCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/retrieve_event.go

@@ -52,12 +52,21 @@ packet event get -d [device_UUID]
 
 Retrieve all events of a current user:
 packet event get
+
+When using "--json" or "--yaml", "--include=relationships" is implied.
 `,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		var events []packngo.Event
 		var err error
 		header := []string{"ID", "Body", "Type", "Created"}
-		listOpt := &packngo.ListOptions{Includes: []string{"relationships"}}
+
+		inc := []string{"relationships"}
+
+		// don't fetch extra details that won't be rendered
+		if !isYaml && !isJSON {
+			inc = nil
+		}
+		listOpt := listOptions(inc, nil)
 
 		if deviceID != "" && projectID != "" && organizationID != "" && eventID != "" {
 			return fmt.Errorf("The id, project-id, device-id, and organization-id parameters are mutually exclusive")
@@ -109,7 +118,4 @@ func init() {
 	retrieveEventCmd.Flags().StringVarP(&projectID, "project-id", "p", "", "UUID of the project")
 	retrieveEventCmd.Flags().StringVarP(&deviceID, "device-id", "d", "", "UUID of the device")
 	retrieveEventCmd.Flags().StringVarP(&volumeID, "organization-id", "o", "", "UUID of the organization")
-
-	retrieveEventCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retrieveEventCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/retrieve_facilities.go

@@ -37,7 +37,7 @@ packet facilities get
 
 	`,
 	RunE: func(cmd *cobra.Command, args []string) error {
-		facilities, _, err := PacknGo.Facilities.List(nil)
+		facilities, _, err := PacknGo.Facilities.List(listOptions(nil, nil))
 		if err != nil {
 			return errors.Wrap(err, "Could not list Facilities")
 		}
@@ -51,8 +51,3 @@ packet facilities get
 		return output(facilities, header, &data)
 	},
 }
-
-func init() {
-	retrieveFacilitiesCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "-j or --json JSON output")
-	retrieveFacilitiesCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "-y or --yaml YAML output")
-}

cmd/retrieve_hardware_reservations.go

@@ -36,10 +36,19 @@ var retrieveHardwareReservationsCmd = &cobra.Command{
 
 Retrieve all hardware reservations of a project:
 packet hardware_reservations get -p [project_id]
+
+When using "--json" or "--yaml", "--include=project,facility,device" is implied.
 	`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		header := []string{"ID", "Facility", "Plan", "Created"}
-		listOpt := &packngo.ListOptions{Includes: []string{"project,facility,device"}}
+
+		inc := []string{"project", "facility", "device"}
+
+		// don't fetch extra details that won't be rendered
+		if !isYaml && !isJSON {
+			inc = nil
+		}
+		listOpt := listOptions(inc, nil)
 
 		if hardwareReservationID == "" && projectID == "" {
 			return fmt.Errorf("Either id or project-id should be set.")
@@ -59,8 +68,8 @@ packet hardware_reservations get -p [project_id]
 
 			return output(reservations, header, &data)
 		} else if hardwareReservationID != "" {
-			getOpt := &packngo.GetOptions{Includes: listOpt.Includes}
-			r, _, err := PacknGo.HardwareReservations.Get(hardwareReservationID, getOpt)
+			getOpts := &packngo.GetOptions{Includes: listOpt.Includes, Excludes: listOpt.Excludes}
+			r, _, err := PacknGo.HardwareReservations.Get(hardwareReservationID, getOpts)
 			if err != nil {
 				return errors.Wrap(err, "Could not get Hardware Reservation")
 			}
@@ -79,6 +88,4 @@ func init() {
 	hardwareReservationsCmd.AddCommand(retrieveHardwareReservationsCmd)
 	retrieveHardwareReservationsCmd.Flags().StringVarP(&projectID, "project-id", "p", "", "UUID of the project")
 	retrieveHardwareReservationsCmd.Flags().StringVarP(&hardwareReservationID, "id", "i", "", "UUID of the hardware reservation")
-	retrieveHardwareReservationsCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retrieveHardwareReservationsCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/retrieve_ip.go

@@ -106,7 +106,4 @@ func init() {
 	retrieveIPCmd.Flags().StringVarP(&projectID, "project-id", "p", "", "UUID of the project")
 	retrieveIPCmd.Flags().StringVarP(&assignmentID, "assignment-id", "a", "", "UUID of the assignment")
 	retrieveIPCmd.Flags().StringVarP(&reservationID, "reservation-id", "r", "", "UUID of the reservation")
-
-	retrieveIPCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retrieveIPCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/retrieve_operating_system.go

@@ -47,8 +47,3 @@ var retrieveOperatingSystemCmd = &cobra.Command{
 		return output(oss, header, &data)
 	},
 }
-
-func init() {
-	retrieveOperatingSystemCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retrieveOperatingSystemCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
-}

cmd/retrieve_organization.go

@@ -21,6 +21,7 @@
 package cmd
 
 import (
+	"github.com/packethost/packngo"
 	"github.com/pkg/errors"
 	"github.com/spf13/cobra"
 )
@@ -39,8 +40,9 @@ packet organization get -i [organization-id]
 
 	`,
 	RunE: func(cmd *cobra.Command, args []string) error {
+		listOpts := listOptions(nil, nil)
 		if organizationID == "" {
-			orgs, _, err := PacknGo.Organizations.List(nil)
+			orgs, _, err := PacknGo.Organizations.List(listOpts)
 			if err != nil {
 				return errors.Wrap(err, "Could not list Organizations")
 			}
@@ -54,7 +56,8 @@ packet organization get -i [organization-id]
 
 			return output(orgs, header, &data)
 		} else {
-			org, _, err := PacknGo.Organizations.Get(organizationID, nil)
+			getOpts := &packngo.GetOptions{Includes: listOpts.Includes, Excludes: listOpts.Excludes}
+			org, _, err := PacknGo.Organizations.Get(organizationID, getOpts)
 			if err != nil {
 				return errors.Wrap(err, "Could not get Organization")
 			}
@@ -71,6 +74,4 @@ packet organization get -i [organization-id]
 
 func init() {
 	retrieveOrganizationCmd.Flags().StringVarP(&organizationID, "organization-id", "i", "", "UUID of the organization")
-	retrieveOrganizationCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retrieveOrganizationCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/retrieve_plans.go

@@ -35,7 +35,7 @@ var retrievePlansCmd = &cobra.Command{
 
   `,
 	RunE: func(cmd *cobra.Command, args []string) error {
-		plans, _, err := PacknGo.Plans.List(nil)
+		plans, _, err := PacknGo.Plans.List(listOptions(nil, nil))
 		if err != nil {
 			return errors.Wrap(err, "Could not list Plans")
 		}
@@ -50,8 +50,3 @@ var retrievePlansCmd = &cobra.Command{
 		return output(plans, header, &data)
 	},
 }
-
-func init() {
-	retrievePlansCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retrievePlansCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
-}

cmd/retrieve_project.go

@@ -40,17 +40,25 @@ packet project get
 Retrieve a specific project:
 packet project get -i [project_UUID]
 packet project get -n [project_name]
+
+When using "--json" or "--yaml", "--include=members" is implied.
 	`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if projectID != "" && projectName != "" {
 			return fmt.Errorf("Must specify only one of project-id and project name")
 		}
-		if projectID == "" {
-			listOpt := &packngo.ListOptions{
-				Includes: []string{"members"},
-			}
 
-			projects, _, err := PacknGo.Projects.List(listOpt)
+		inc := []string{"members"}
+
+		// don't fetch extra details that won't be rendered
+		if !isYaml && !isJSON {
+			inc = nil
+		}
+
+		listOpts := listOptions(inc, nil)
+
+		if projectID == "" {
+			projects, _, err := PacknGo.Projects.List(listOpts)
 			if err != nil {
 				return errors.Wrap(err, "Could not list Projects")
 			}
@@ -77,7 +85,8 @@ packet project get -n [project_name]
 			header := []string{"ID", "Name", "Created"}
 			return output(projects, header, &data)
 		} else {
-			p, _, err := PacknGo.Projects.Get(projectID, &packngo.GetOptions{Includes: []string{"members"}})
+			getOpts := &packngo.GetOptions{Includes: listOpts.Includes, Excludes: listOpts.Excludes}
+			p, _, err := PacknGo.Projects.Get(projectID, getOpts)
 			if err != nil {
 				return errors.Wrap(err, "Could not get Project")
 			}
@@ -94,6 +103,4 @@ packet project get -n [project_name]
 func init() {
 	retriveProjectCmd.Flags().StringVarP(&projectName, "project", "n", "", "Name of the project")
 	retriveProjectCmd.Flags().StringVarP(&projectID, "project-id", "i", "", "UUID of the project")
-	retriveProjectCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retriveProjectCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/retrieve_ssh_key.go

@@ -75,6 +75,4 @@ packet ssh-key get --id [ssh-key_UUID]
 
 func init() {
 	retrieveSSHKeysCmd.Flags().StringVarP(&sshKeyID, "id", "i", "", "UUID of the SSH key")
-	retrieveSSHKeysCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retrieveSSHKeysCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/retrieve_user.go

@@ -69,6 +69,4 @@ packet user get --id [user_UUID]
 
 func init() {
 	retriveUserCmd.Flags().StringVarP(&userID, "id", "i", "", "UUID of the user")
-	retriveUserCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retriveUserCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/retrieve_virtual_network.go

@@ -37,7 +37,7 @@ packet virtual-network get -p [project_UUID]
 
 	`,
 	RunE: func(cmd *cobra.Command, args []string) error {
-		vnets, _, err := PacknGo.ProjectVirtualNetworks.List(projectID, nil)
+		vnets, _, err := PacknGo.ProjectVirtualNetworks.List(projectID, listOptions(nil, nil))
 		if err != nil {
 			return errors.Wrap(err, "Could not list Project Virtual Networks")
 		}
@@ -56,6 +56,4 @@ packet virtual-network get -p [project_UUID]
 func init() {
 	retrieveVirtualNetworksCmd.Flags().StringVarP(&projectID, "project-id", "p", "", "UUID of the project")
 	_ = retrieveVirtualNetworksCmd.MarkFlagRequired("project-id")
-	retrieveVirtualNetworksCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retrieveVirtualNetworksCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/retrieve_volume.go

@@ -51,7 +51,7 @@ packet volume get --id [volume_UUID]
 		} else if projectID == "" && volumeID == "" {
 			return fmt.Errorf("Either id or project-id should be set.")
 		} else if projectID != "" {
-			volumes, _, err := PacknGo.Volumes.List(projectID, nil)
+			volumes, _, err := PacknGo.Volumes.List(projectID, listOptions(nil, nil))
 			if err != nil {
 				return errors.Wrap(err, "Could not list Volumes")
 			}
@@ -83,6 +83,4 @@ packet volume get --id [volume_UUID]
 func init() {
 	retriveVolumeCmd.Flags().StringVarP(&projectID, "project-id", "p", "", "UUID of the project")
 	retriveVolumeCmd.Flags().StringVarP(&volumeID, "id", "i", "", "UUID of the volume")
-	retriveVolumeCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retriveVolumeCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }

cmd/retrieve_vpn.go

@@ -51,7 +51,4 @@ packet vpn get --faciliy ewr1
 func init() {
 	retrieveVpnCmd.Flags().StringVarP(&facility, "facility", "f", "", "Code of the facility for which VPN config is to be retrieved")
 	_ = retrieveVpnCmd.MarkFlagRequired("id")
-
-	retrieveVpnCmd.PersistentFlags().BoolVarP(&isJSON, "json", "j", false, "JSON output")
-	retrieveVpnCmd.PersistentFlags().BoolVarP(&isYaml, "yaml", "y", false, "YAML output")
 }