chore(cli): add examples (#1052)

cmd/file_addplugins.go

@@ -138,6 +138,11 @@ order they are given:
 	}
 `,
 		RunE: executeAddPlugins,
+		Example: "# adds 2 plugins to all services in a deck file, except if they are already present\n" +
+			"cat kong.yml | deck file add-plugins --selector='services[*]' plugin1.json plugin2.yml\n" +
+			"\n" +
+			"# same, but now overwriting plugins if they already exist\n" +
+			"cat kong.yml | deck file add-plugins --overwrite --selector='services[*]' plugin1.json plugin2.yml",
 		Args: cobra.MinimumNArgs(0),
 	}
 

cmd/file_addtags.go

@@ -72,6 +72,8 @@ func newAddTagsCmd() *cobra.Command {
 The tags are added to all objects that match the selector expressions. If no
 selectors are given, all Kong entities are tagged.`,
 		RunE: executeAddTags,
+		Example: "# adds tags 'tag1' and 'tag2' to all services in file 'kong.yml'\n" +
+			"cat kong.yml | deck file add-tags --selector='services[*]' tag1 tag2",
 		Args: cobra.MinimumNArgs(1),
 	}
 

cmd/file_listtags.go

@@ -76,6 +76,8 @@ func newListTagsCmd() *cobra.Command {
 The tags are collected from all objects that match the selector expressions. If no
 selectors are given, all Kong entities will be scanned.`,
 		RunE: executeListTags,
+		Example: "# list all tags used on services\n" +
+			"cat kong.yml | deck file list-tags --selector='services[*]'",
 		Args: cobra.NoArgs,
 	}
 

cmd/file_merge.go

@@ -59,6 +59,8 @@ Doesn't perform any checks on content, e.g. duplicates, or any validations.
 If the input files are not compatible, returns an error. Compatibility is
 determined by the '_transform' and '_format_version' fields.`,
 		RunE: executeMerge,
+		Example: "# Merge 3 files\n" +
+			"deck file patch -o merged.yaml file1.yaml file2.yaml file3.yaml",
 		Args: cobra.MinimumNArgs(1),
 	}
 

cmd/file_openapi2kong.go

@@ -70,6 +70,8 @@ The example file at https://github.com/Kong/go-apiops/blob/main/docs/learnservic
 has extensive annotations explaining the conversion process, as well as all supported 
 custom annotations (x-kong-... directives).`,
 		RunE: executeOpenapi2Kong,
+		Example: "# Convert an OAS file, adding 2 tags, and namespacing the UUIDs to a unique name\n" +
+			"cat service_oas.yml | deck file openapi2kong --select-tag=serviceA,teamB --uuid-base=unique-service-name",
 		Args: cobra.NoArgs,
 	}
 

cmd/file_patch.go

@@ -159,6 +159,8 @@ If the 'values' object instead is an array, then any arrays returned by the sele
 will get the 'values' appended to them.
 `,
 		RunE: executePatch,
+		Example: "# update the read-timeout on all services\n" +
+			"cat kong.yml | deck file patch --selector=\"$..services[*]\" --value=\"read_timeout:10000\"",
 	}
 
 	patchCmd.Flags().StringVarP(&cmdPatchInputFilename, "state", "s", "-",