rural - User-friendly command-line HTTP tool in Rust

Why rural?

Most developers tend to use curl when they need to make HTTP requests from the command line. In terms of speed and breadth of features, curl pretty much has it all. However, in terms of the command-line API, curl can sometimes leave something to be desired. For example, the -G or --get flag can be used to make a GET request, but there is no --post option, and -P is used to instruct the server to connect to an open FTP port instead of sending the reponse back directly.

One alternative to using curl for command-line HTTP requests is HTTPie. HTTPie has an excellent command-line API, including some superb syntatic sugar for various parameter types and headers. However, being written in Python, HTTPie is quite a bit slower than curl.

Rural aims to provide the ease-of-use of HTTPie at a speed comparable to that of curl. To that end, rural purposely implements a similar API to HTTPie, including the syntatic sugar for parameters and headers.

Status

Rural currently implements most of the common features needed for making HTTP requests in the command line. However, many less common features have not been implemented. (A brief look at man curl shows just how much functionality there is to include). If there's a feature you'd like to be implemented, feel free to open an issue, or even better, a pull request! Contributions are always quite welcome.

To date, no specific optimization has been done on rural. From a set of extremely unscientific tests, rural currently runs at the same order of magnitude as curl in terms of speed (which is an order of magnitude faster than HTTPie).

Installation

If you don't already have Rust installed, you can get the Rust toolchain installer here.

Once Rust is installed, run cargo install rural. Make sure you add $HOME/.cargo/bin to your PATH if you instructed rustup not to do so itself.

Usage

Method types

Rural currently supports making GET, POST, PUT, DELETE, HEAD, OPTIONS, and PATCH requests. To make a request, invoke rural with the request method (in lowercase) and the URL:

rural get http://example.com
rural post http://example.com
rural put http://example.com
rural delete http://example.com
rural head http://example.com
rural options http://example.com
rural patch http://example.com

HTTPS

Rural requires OpenSSL to make HTTPS requests:

rural get https://example.com

Output

Sections

To see the response headers instead of the body, use the --headers flag (-d for short):

rural --headers get http://example.com
rural -d get http://example.com

Note that whenever the headers are printed out, the HTTP version number and response status code are printed by default. To suppress this extra output and just get the headers, add the --suppress-info flag as well (-s for short):

rural --headers --suppress-info get http://example.com
rural -ds get http://example.com

To print both the reponse headers and the body, use the --both flag (-b for short):

rural --both get http://example.com
rural -b get http://example.com

--suppress-info works for --both as well:

rural --both --suppress-info get http://example.com
rural -bs get http://example.com

Output file

To save the response body to a file, use the --out argument with the desired output file name (-o for short):

rural get http://example.com --out output.json
rural get http://example.com -o output.html

Colors

By default, rural will colorize the response headers, the HTTP info string, and any JSON in the response body. To suppress this, use the --no-color flag (-n for short):

rural --no-color http://example.com
rural -n http://example.com

NOTE: The library used to colorize the JSON uses ANSI color escape sequences, which will not work correctly on Windows. Because of this, rural disables colorized output on Windows.

Parameters

Rural supports supplying GET parameters in the querystring or by using the syntax key==value:

rural get 'http://example.com?bass=john&drums=keith'
rural get http://example.com bass==john drums==keith

To supply body parameters, use the syntax key=value:

rural post http://example.com bass=john drums=keith

Rural defaults to sending body parameters as JSON. To instead send them as form parameters, use --form (-f for short):

rural --form post http://example.com bass=john drums=keith
rural -f post http://example.com bass=john drums=keith

Body parameters can also be sent using literal JSON rather than plaintext. To do this, use the syntax key:=value (note that JSON values will generally have to be wrapped in quotes due to how most shells interpret some of the characters, as shown below):

rural post http://example.com who:='{ "bass": "john", "drums": "keith", "others": ["pete", "roger"] }'

Note that body parameters can also be specified for other types of requests besides POST:

rural put http://example.com bass=john
rural delete http://example.com drums=keith

Headers

HTTP headers (either standard or custom) can be provided using the syntax name:value:

rural get http://example.com bass:john drums:keith

License

Rural is licensed under the MIT LICENSE.