[api] Improve documentation

commands/api.go

@@ -16,7 +16,7 @@ import (
 
 var cmdApi = &Command{
 	Run:   apiCommand,
-	Usage: "api [-t] [-X <METHOD>] [--cache <TTL>] <ENDPOINT> [-F <KEY-VALUE>]",
+	Usage: "api [-it] [-X <METHOD>] [-H <HEADER>] [--cache <TTL>] <ENDPOINT> [-F <FIELD>|--input <FILE>]",
 	Long: `Low-level GitHub API request interface.
 
 ## Options:
@@ -28,9 +28,9 @@ var cmdApi = &Command{
 		Use '-XGET' to force serializing fields into the query string for the GET
 		request instead of JSON body of the POST request.
 
-	-F, --field <KEY-VALUE>
-		Send data in 'KEY=VALUE' format. The <VALUE> part has some magic handling;
-		see '--raw-field' for passing arbitrary strings.
+	-F, --field <KEY>=<VALUE>
+		Data to serialize with the request. <VALUE> has some magic handling; use
+		'--raw-field' for sending arbitrary string values.
 
 		If <VALUE> starts with "@", the rest of the value is interpreted as a
 		filename to read the value from. Use "@-" to read from standard input.
@@ -38,12 +38,16 @@ var cmdApi = &Command{
 		If <VALUE> is "true", "false", "null", or looks like a number, an
 		appropriate JSON type is used instead of a string.
 
+		It is not possible to serialize <VALUE> as a nested JSON array or hash.
+		Instead, construct the request payload externally and pass it via
+		'--input'.
+
 		Unless '-XGET' was used, all fields are sent serialized as JSON within the
 		request body. When <ENDPOINT> is "graphql", all fields other than "query"
 		are grouped under "variables". See
 		<https://graphql.org/learn/queries/#variables>
 
-	-f, --raw-field <KEY-VALUE>
+	-f, --raw-field <KEY>=<VALUE>
 		Same as '--field', except that it allows values starting with "@", literal
 		strings "true", "false", and "null", as well as strings that look like
 		numbers.
@@ -52,8 +56,8 @@ var cmdApi = &Command{
 		The filename to read the raw request body from. Use "-" to read from standard
 		input. Use this when you want to manually construct the request payload.
 
-	-H, --header <KEY-VALUE>
-		An HTTP request header in 'KEY: VALUE' format.
+	-H, --header <KEY>:<VALUE>
+		Set an HTTP request header.
 
 	-i, --include
 		Include HTTP response headers in the output.

utils/args_parser.go

@@ -192,7 +192,7 @@ func NewArgsParser() *ArgsParser {
 
 func NewArgsParserWithUsage(usage string) *ArgsParser {
 	p := NewArgsParser()
-	f := `(-[a-zA-Z0-9@^]|--[a-z][a-z0-9-]+)(?:[ =]<?([a-zA-Z_-]+)>?)?`
+	f := `(-[a-zA-Z0-9@^]|--[a-z][a-z0-9-]+)(?:[ =]([a-zA-Z_<>:=-]+))?`
 	re := regexp.MustCompile(fmt.Sprintf(`(?m)^\s*%s(?:,\s*%s)?$`, f, f))
 	for _, match := range re.FindAllStringSubmatch(usage, -1) {
 		n1 := match[1]