rename nomad curl to nomad operator api

command/commands.go

@@ -214,11 +214,6 @@ func Commands(metaPtr *Meta, agentUi cli.Ui) map[string]cli.CommandFactory {
 				Meta: meta,
 			}, nil
 		},
-		"curl": func() (cli.Command, error) {
-			return &CurlCommand{
-				Meta: meta,
-			}, nil
-		},
 		// operator debug was released in 0.12 as debug. This top-level alias preserves compatibility
 		"debug": func() (cli.Command, error) {
 			return &OperatorDebugCommand{
@@ -501,6 +496,12 @@ func Commands(metaPtr *Meta, agentUi cli.Ui) map[string]cli.CommandFactory {
 			}, nil
 		},
 
+		"operator api": func() (cli.Command, error) {
+			return &OperatorAPICommand{
+				Meta: meta,
+			}, nil
+		},
+
 		"operator autopilot": func() (cli.Command, error) {
 			return &OperatorAutopilotCommand{
 				Meta: meta,

command/curl.go → command/operator_api.go

@@ -16,38 +16,38 @@ import (
 	"github.com/posener/complete"
 )
 
-type CurlCommand struct {
+type OperatorAPICommand struct {
 	Meta
 
 	verboseFlag bool
 	method      string
 	body        io.Reader
 }
 
-func (*CurlCommand) Help() string {
+func (*OperatorAPICommand) Help() string {
 	helpText := `
-Usage: nomad curl [options] <path>
+Usage: nomad operator api [options] <path>
 
-  curl is a utility command for accessing Nomad's HTTP API and is inspired by
-  the popular curl command line program. Nomad's curl command populates Nomad's
-  standard environment variables into their appropriate HTTP headers. If the
-  'path' does not begin with "http" then $NOMAD_ADDR will be used. 
+  api is a utility command for accessing Nomad's HTTP API and is inspired by
+  the popular curl command line program. Nomad's operator api command populates
+  Nomad's standard environment variables into their appropriate HTTP headers.
+  If the 'path' does not begin with "http" then $NOMAD_ADDR will be used. 
 
   The 'path' can be in one of the following forms:
 
     /v1/allocations                       <- API Paths must start with a /
     localhost:4646/v1/allocations         <- Scheme will be inferred
     https://localhost:4646/v1/allocations <- Scheme will be https://
 
-  Note that Nomad's curl does not always match the popular curl programs
-  behavior. Instead Nomad's curl is optimized for common Nomad HTTP API
-  operations.
+  Note that this command does not always match the popular curl program's
+  behavior. Instead Nomad's operator api command is optimized for common Nomad
+  HTTP API operations.
 
 General Options:
 
   ` + generalOptionsUsage(usageOptsDefault) + `
 
-Curl Specific Options:
+Operator API Specific Options:
 
   -dryrun
     Output curl command to stdout and exit.
@@ -74,26 +74,26 @@ Curl Specific Options:
 	return strings.TrimSpace(helpText)
 }
 
-func (*CurlCommand) Synopsis() string {
+func (*OperatorAPICommand) Synopsis() string {
 	return "Query Nomad's HTTP API like curl"
 }
 
-func (c *CurlCommand) AutocompleteFlags() complete.Flags {
+func (c *OperatorAPICommand) AutocompleteFlags() complete.Flags {
 	return mergeAutocompleteFlags(c.Meta.AutocompleteFlags(FlagSetClient),
 		complete.Flags{
 			"-dryrun": complete.PredictNothing,
 		})
 }
 
-func (c *CurlCommand) AutocompleteArgs() complete.Predictor {
+func (c *OperatorAPICommand) AutocompleteArgs() complete.Predictor {
 	//TODO(schmichael) wouldn't it be cool to build path autocompletion off
 	//                 of our http mux?
 	return complete.PredictNothing
 }
 
-func (*CurlCommand) Name() string { return "curl" }
+func (*OperatorAPICommand) Name() string { return "operator api" }
 
-func (c *CurlCommand) Run(args []string) int {
+func (c *OperatorAPICommand) Run(args []string) int {
 	var dryrun bool
 	headerFlags := newHeaderFlags()
 
@@ -117,7 +117,7 @@ func (c *CurlCommand) Run(args []string) int {
 	}
 
 	if n := len(args); n > 1 {
-		c.Ui.Error(fmt.Sprintf("curl accepts exactly 1 argument, but %d arguments were found", n))
+		c.Ui.Error(fmt.Sprintf("operator api accepts exactly 1 argument, but %d arguments were found", n))
 		c.Ui.Error(commandErrorText(c))
 		return 1
 	}
@@ -274,7 +274,7 @@ func setQueryParams(config *api.Config, path *url.URL) {
 
 // apiToCurl converts a Nomad HTTP API config and path to its corresponding
 // curl command or returns an error.
-func (c *CurlCommand) apiToCurl(config *api.Config, headers http.Header, path *url.URL) (string, error) {
+func (c *OperatorAPICommand) apiToCurl(config *api.Config, headers http.Header, path *url.URL) (string, error) {
 	parts := []string{"curl"}
 
 	if c.verboseFlag {

website/content/docs/commands/operator/api.mdx

@@ -0,0 +1,54 @@
+---
+layout: docs
+page_title: 'Commands: operator api'
+description: |
+  operator api is a utility command for accessing Nomad's HTTP API similar to
+  the popular open source program curl.
+---
+
+# Command: operator api
+
+The `operator api` command allows easy access to Nomad's HTTP API similar to
+the popular [curl] program. Nomad's `operator api` command reads [environment
+variables][envvars] to dramatically ease HTTP API access compared to trying to
+manually write the same command with the third party `curl` command.
+
+For example for the following environment:
+
+```
+NOMAD_TOKEN=d4434353-c797-19e4-a14d-4068241f86a4
+NOMAD_CACERT=$HOME/.nomad/ca.pem
+NOMAD_CLIENT_CERT=$HOME/.nomad/cli.pem
+NOMAD_CLIENT_KEY=$HOME/.nomad/client-key.pem
+NOMAD_TLS_SERVER_NAME=client.global.nomad
+NOMAD_ADDR=https://remote.client123.internal:4646
+```
+
+Accessing Nomad's [`/v1/jobs`][jobs] HTTP endpoint with `nomad operator
+api` would require:
+
+```
+nomad operator api /v1/jobs
+```
+
+Performing the same request using the external `curl` tool would require:
+
+```
+curl \
+  --cacert "$HOME/.nomad/ca.pem" \
+  --cert "$HOME/.nomad/client.pem" \
+  --key "$HOME/.nomad/client-key.pem" \
+  --connect-to "client.global.nomad:4646:remote.client123.internal:4646" \
+  -H "X-Nomad-Token: ${NOMAD_TOKEN}" \
+  https://client.global.nomad:4646/v1/jobs
+```
+
+The `-dryrun` flag for `nomad operator api` will output a curl command instead
+of performing the HTTP request immediately. Note that you do *not* need the 3rd
+party `curl` command installed to use `operator api`. The `curl` output from
+`-dryrun` is intended for use in scripts or running in locations without a
+Nomad binary present.
+
+[curl]: https://curl.se/
+[envvars]: /docs/commands#environment-variables
+[jobs]: /api-docs/jobs