req

netsleuth's req CLI is an advanced command-line HTTP client that takes inspiration from curl and httpie, and adds its own unique flavor.

$ req https://netsleuth.io/example.json
GET /example.json HTTP/1.1
User-Agent: netsleuth/1.0.1 (req; +https://netsleuth.io)
Host: netsleuth.io

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 17

{ hello: 'world' }

$ req POST https://netsleuth.io/example.json Header:val foo=bar n=5
POST /example.json HTTP/1.1
User-Agent: netsleuth/1.0.1 (req; +https://netsleuth.io)
Header: val
Content-Type: application/json
Accept: application/json, */*
Content-Length: 19
Host: netsleuth.io

{ foo: 'bar', n: 5 }

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Content-Length: 2

{}

req comes with a number of features not found elsewhere:

• A JSON-first argument interface that makes it easy to work with modern RESTful APIs, with minimal shell escaping required.
• Profiles that save request defaults such as cookies and auth tokens for frequently-used servers
• Read cookies out of your browser's cookie jar (--chrome-cookies)
• Clipboard integration (--paste and --copy options)
• You can optionally use the netsleuth GUI to inspect requests made from the command line.
• Save request and response to a HAR file for later inspection or diffing.

Usage examples can be found here.

Make sure you've installed netsleuth globally (npm install -g netsleuth) to have req available on your PATH. The following content is also available by running req --help.

Usage:

req [options] [method] <url> [<param>...]
req <command>

By default, req will print HTTP headers on stderr and the response body on stdout. In addition, the request and response details will be sent to the netsleuth GUI, which is available at http://localhost:9000/inspect/req-cli

Positional arguments:

[method]

The HTTP request method. Any uppercase word accepted. Default: GET or POST depending on whether there is data to be sent in the request body.

<url>

The request URL. May be fully-qualified, or use shorthand:

Default to localhost

Without an explicit hostname, req will assume localhost.

req /foo -> http://127.0.0.1/foo
req :3000/foo -> http://127.0.0.1:3000/foo

// and s//

Shortcut for http:// and https://.

req //host/foo -> http://host/foo

Named profile

req allows you to configure named profiles with a saved Origin URL, cookies, and default headers. See the section on Profiles below.

req profilename/foo -> http://127.0.0.1:4000/foo

With fully-qualified URLs, you may also specify auth credentials using the standard URL auth notation. Username + password credentials are sent using HTTP Basic auth. If no password is specified, the username is sent as a Bearer token.

req http://user:pass@localhost/foo -> "Authorization: Basic dXNlcjpwYXNz"
req http://t0k3n@localhost/foo -> "Authorization: Bearer t0k3n"

har:/path/to/file.har#entry

Use the special har: scheme to specify that req should make a request by replaying from a HAR file on disk (or har:! to read the system clipboard). Optionally use entry to search request URLs or specify the the request entry by index (default 0). Later params can override any properties loaded from the HAR.

req har:file.har bar=baz
req har:file.har#/foo

[param]…

Any number of additional space-separated parameters may be specified. Values may be quoted as necessary.

key=value and key==value

The request body will be set to a JSON object with this key/value added.

• Use dot notation in the key for nested objects (foo.bar=value)
• Use [] to push primitive values to an array (foo[]=1 foo[]=2)
• Numeric values will be set as numbers
• true, false, and null will be set as booleans/null
• Anything else will be set as a string
• Keys and/or values with spaces must be enclosed with quotes
• Non-strings can be set as a string by using ==
• Special param values can be escaped to string with \

req /foo n=1 a==1 b="x y" c=z -> {"n":1,"a":"1","b":"x y","c":"z"}
req /foo a=\\@a b=\\=b -> {"a":"@a","b":"=b"}
req /foo obj.a=1 obj.b=2 -> {"obj":{"a":1,"b":2}}
req /foo arr[]=1 arr[]=2 -> {"arr":[1,2]}

key=@filepath

Reads and buffers this file and adds its content to the request body. If the file can be parsed as JSON, the object itself is set on the property. Otherwise, the raw contents are set as a string.

req /foo bar=@bar.json -> {"bar":{"from":"file"}}
req /foo bar=@bar.txt -> {"bar":"stuff from file"}

?key=value

URL parameters to be merged in to the request URL. (Useful to avoid shell-escaping &s and manual URL-encoding.)

req /foo ?q="bar baz" ?p=1 -> http://localhost/foo?q=bar%20baz&p=1

Header:value

Adds a request header.

req /foo X-Signature:"xyz" -> X-Signature: xyz

@filepath

The request body will be streamed from this file. If a Content-Type header is not explicitly specified, req will try to guess based on file extension or fall back to application/octet-stream. Cannot be mixed with key=value params.

req PUT /foo @~/example.json

+namedPayload

If the <url> uses a Profile, req will copy JSON properties saved in the Profile under this name to the request body. Later params can override. Assuming the “proj” Profile has a payload named “bar” with the value {a:1, b:2, c:3}:

req proj/foo +bar b=5 -> {"a":1,"b":5,"c":3}

– raw body

The text following -- (and a space) will be transmitted as the request body. req will not apply any modification to the text, but normal shell escaping rules apply. Cannot be mixed with key=value, @filepath, or +payload params, but Header:value params may be specified before the --.

–paste clipboard

If the --paste option is specified, req will use your system clipboard contents as the request body. Only plain text is supported. If the text parses as JSON, you may use key=value params to override keys in the pasted data.

Profiles

req supports named profiles, which are a set of default options for a particular host. This allows you to send saved headers with your requests, without having to specify them on the command line every time.

Profiles can be managed using the req profile command. See req profile --help for more details. Alternatively, manually edit ~/.sleuthrc.

Use profiles by typing the profile name in place of the protocol+host part of the URL. Any params on the command line override the profile’s defaults.

req profilename/foo a=1

Standard in/out

req prints most of its output on stderr; only the HTTP response body is printed to stdout. This means shell pipes and redirection work exactly as one might expect.

req GET /page > page.html
req POST /upload -t jpg < cat.jpg
req /foo | req --txt /bar

If stdout is connected to a terminal, JSON responses are buffered, parsed, and pretty-printed. Otherwise (or if --raw is set), the response is streamed out unmodified.

Commands

Additional commands are available which manage req’s configuration and environment. Type req <command> --help for details of each command.

profile

Options

HTTP Behavior
  --no-follow, -F  Do not follow HTTP 3xx redirects                    [boolean]
  --continue       Send Expect: 100-continue and wait for a 100 before sending
                   request body                                        [boolean]
  --txt            Set request Content-Type: text/plain (utf8)         [boolean]
  --json           Set request Content-Type: and Accept: application/json, and
                   treat response as JSON regardless of Content-Type   [boolean]
  --bin            Set request Content-Type: application/octet-stream  [boolean]
  --type, -t       Set request Content-Type to the mimetype normally associated
                   with the specified file extension
  --charset, -h    Add a `charset` directive to the request Content-Type.
  --gzip, -z       Set Accept-Encoding: gzip                           [boolean]
  --gzip-req, -Z   Compress the request body                           [boolean]
  --ua, -u         Use a common User-Agent string.  Choices:
                   {chrome,firefox}[-{win,mac,linux}] safari edge ie ios android
                   curl
  --enc            Force the response body to be treated as text with this
                   character encoding
  --no-ua, -U      Do not set default User-Agent                       [boolean]
  --1945           Strictly follow RFC1945 when handling HTTP 301/302 redirects
                   and do not change the request method                [boolean]

Display
  --raw, -r         Response body should be streamed out unmodified (ie disable
                    pretty-printing)                                   [boolean]
  --quiet, -q       Do not print any HTTP information, only the response body in
                    the terminal                                       [boolean]
  --term-enc        Character encoding used when sending data to the terminal
                                                              [default: "utf-8"]
  --max-length, -l  Maximum length of body data to print to the terminal (0 for
                    no limit)                         [number] [default: 156160]
  --diff            Diff the request/response against one saved in this HAR file
                    (or - for stdin, or ! for clipboard).  Use #entry to search
                    request URLs or specify an entry index (like har: scheme,
                    above; default 0)

Network Behavior
  --secure, -s     Force TLS (https)                                   [boolean]
  --insecure, -S   Ignore TLS certificate errors                       [boolean]
  --ca             Validate TLS certificates using the CA certificate(s) in this
                   file
  --client-cert    Present TLS client certificate from this PEM or PFX file
  --client-key     File containing key for PEM client-cert
  --client-key-pw  Password for client certificate's private key
  -4               Use IPv4 only                                       [boolean]
  -6               Use IPv6 only                                       [boolean]
  --bind           Local interface to bind for network connections
  --max-upload     Limit request upload to this number of [kmg]bytes/sec
  --max-download   Limit response download to this number of [kmg]bytes/sec

GUI
  --inspector, -i     Inspector GUI tab to send this request to
                                                            [default: "req-cli"]
  --no-inspector, -I  Do not send this request to the Inspector GUI    [boolean]

Output
  --out-enc   Enable character encoding conversion and use this encoding when
              sending data to non-terminal outputs.
  --har       Write request and response details to a HAR file located at this
              path, or - for stdout.  If the file already exists, data will be
              appended.
  --copy, -c  Copy response body to clipboard                          [boolean]

Input
  --paste, -v  Send clipboard contents as request body                 [boolean]

Options:
  --version             Show version number                            [boolean]
  --chrome-cookies, -C  Use your browser's cookies for this request    [boolean]
  --help, -?            Show my help                                   [boolean]

Options may appear anywhere on the command line (before or after positional arguments).