4357696d56
- Add manpage OBS-URL: https://build.opensuse.org/request/show/658772 OBS-URL: https://build.opensuse.org/package/show/network:utilities/httpie?expand=0&rev=3
293 lines
9.1 KiB
Groff
293 lines
9.1 KiB
Groff
.TH HTTP "1" "February 2016" "http 0.9.2" "User Commands"
|
|
.SH NAME
|
|
httpie - CLI, cURL-like tool for humans
|
|
.SH SYNOPSIS
|
|
.TP
|
|
.B http
|
|
.RI
|
|
[\-\-json] [\-\-form] [\-\-pretty {all,colors,format,none}] [\-\-style STYLE]
|
|
[\-\-print WHAT] [\-\-verbose] [\-\-headers] [\-\-body] [\-\-stream]
|
|
[\-\-output FILE] [\-\-download] [\-\-continue]
|
|
[\-\-session SESSION_NAME_OR_PATH | \-\-session\-read\-only SESSION_NAME_OR_PATH]
|
|
[\-\-auth USER[:PASS]] [\-\-auth\-type {basic,digest}]
|
|
[\-\-proxy PROTOCOL:PROXY_URL] [\-\-follow] [\-\-verify VERIFY]
|
|
[\-\-cert CERT] [\-\-cert\-key CERT_KEY] [\-\-timeout SECONDS]
|
|
[\-\-check\-status] [\-\-ignore\-stdin] [\-\-help] [\-\-version]
|
|
[\-\-traceback] [\-\-debug]
|
|
.br
|
|
[METHOD] \fIURL\fR [REQUEST_ITEM [REQUEST_ITEM ...]]
|
|
|
|
.SH DESCRIPTION
|
|
\fBHTTPie\fP is a CLI HTTP utility built out of frustration with existing tools.
|
|
The goal is to make CLI interaction with HTTP-based services as human-friendly
|
|
as possible.
|
|
.PP
|
|
HTTPie does so by providing an http command that allows for issuing arbitrary
|
|
HTTP requests using a simple and natural syntax and displaying colorized responses.
|
|
|
|
.SH OPTIONS
|
|
.SS Positional Arguments
|
|
These arguments come after any flags and in the order they are listed here.
|
|
Only URL is required.
|
|
.TP
|
|
METHOD
|
|
|
|
The HTTP method to be used for the request (GET, POST, PUT, DELETE, ...).
|
|
.br
|
|
This argument can be omitted in which case HTTPie will use POST if there
|
|
is some data to be sent, otherwise GET:
|
|
|
|
\f(CW$ http example.org # => GET\fR
|
|
|
|
\f(CW$ http example.org hello=world # => POST\fR
|
|
|
|
.TP
|
|
URL
|
|
|
|
The scheme defaults to 'http://' if the URL does not include one.
|
|
|
|
You can also use a shorthand for localhost
|
|
|
|
\f(CW$ http :3000 # => http://localhost:3000\fR
|
|
|
|
\f(CW$ http :/foo # => http://localhost/foo\fR
|
|
|
|
.TP
|
|
REQUEST_ITEM
|
|
|
|
Optional key\-value pairs to be included in the request. The separator used
|
|
determines the type:
|
|
|
|
\fB':'\fR HTTP headers
|
|
Referer:http://httpie.org
|
|
Cookie:foo=bar
|
|
User\-Agent:bacon/1.0
|
|
|
|
\fB'=='\fR URL parameters to be appended to the request URI
|
|
search==httpie
|
|
|
|
\fB'='\fR Data fields to be serialized into a JSON object
|
|
(with \fB\-\-json\fR, \fB\-j\fR) or form data (with \fB\-\-form\fR, \fB\-f\fR)
|
|
name=HTTPie
|
|
language=Python
|
|
description='CLI HTTP client'
|
|
|
|
\fB':='\fR Non\-string JSON data fields (only with \fB\-\-json\fR, \fB\-j\fR)
|
|
awesome:=true
|
|
amount:=42
|
|
colors:='["red", "green", "blue"]'
|
|
|
|
\fB'@'\fR Form file fields (only with \fB\-\-form\fR, \fB\-f\fR)
|
|
cs@~/Documents/CV.pdf
|
|
|
|
\fB'=@'\fR A data field like '=', but takes a file path and embeds its content:
|
|
essay=@Documents/essay.txt
|
|
|
|
\fB':=@'\fR A raw JSON field like ':=', but takes a file path and embeds its content:
|
|
package:=@./package.json
|
|
|
|
You can use a backslash to escape a colliding separator in the field name:
|
|
|
|
field\-name\-with\e:colon=value
|
|
|
|
|
|
.SS "Predefined Content Types:"
|
|
.HP
|
|
\fB\-\-json\fR, \fB\-j\fR
|
|
.IP
|
|
(default) Data items from the command line are serialized as a JSON object.
|
|
The Content\-Type and Accept headers are set to application/json
|
|
(if not specified).
|
|
.HP
|
|
\fB\-\-form\fR, \fB\-f\fR
|
|
.IP
|
|
Data items from the command line are serialized as form fields.
|
|
.IP
|
|
The Content\-Type is set to application/x\-www\-form\-urlencoded (if not
|
|
specified). The presence of any file fields results in a
|
|
multipart/form\-data request.
|
|
.SS "Output Processing:"
|
|
.HP
|
|
\fB\-\-pretty\fR {all,colors,format,none}
|
|
.IP
|
|
Controls output processing. The value can be "none" to not prettify
|
|
the output (default for redirected output), "all" to apply both colors
|
|
and formatting (default for terminal output), "colors", or "format".
|
|
.HP
|
|
\fB\-\-style\fR STYLE, \fB\-s\fR STYLE
|
|
.IP
|
|
Output coloring style (default is "solarized"). One of:
|
|
.IP
|
|
algol, algol_nu, autumn, borland, bw, colorful, default,
|
|
emacs, friendly, fruity, igor, lovelace, manni, monokai,
|
|
murphy, native, paraiso\-dark, paraiso\-light, pastie,
|
|
perldoc, rrt, solarized, tango, trac, vim, vs, xcode
|
|
.IP
|
|
For this option to work properly, please make sure that the $TERM
|
|
environment variable is set to "xterm\-256color" or similar
|
|
(e.g., via `export TERM=xterm\-256color' in your ~/.bashrc).
|
|
.SS "Output Options:"
|
|
.HP
|
|
\fB\-\-print\fR WHAT, \fB\-p\fR WHAT
|
|
.IP
|
|
String specifying what the output should contain:
|
|
.IP
|
|
\&'H' request headers
|
|
\&'B' request body
|
|
\&'h' response headers
|
|
\&'b' response body
|
|
.IP
|
|
The default behaviour is 'hb' (i.e., the response headers and body
|
|
is printed), if standard output is not redirected. If the output is piped
|
|
to another program or to a file, then only the response body is printed
|
|
by default.
|
|
.HP
|
|
\fB\-\-verbose\fR, \fB\-v\fR
|
|
.IP
|
|
Print the whole request as well as the response. Shortcut for \fB\-\-print\fR=\fI\,HBbh\/\fR.
|
|
.HP
|
|
\fB\-\-headers\fR, \fB\-h\fR
|
|
.IP
|
|
Print only the response headers. Shortcut for \fB\-\-print\fR=\fI\,h\/\fR.
|
|
.HP
|
|
\fB\-\-body\fR, \fB\-b\fR
|
|
.IP
|
|
Print only the response body. Shortcut for \fB\-\-print\fR=\fI\,b\/\fR.
|
|
.HP
|
|
\fB\-\-stream\fR, \fB\-S\fR
|
|
.IP
|
|
Always stream the output by line, i.e., behave like `tail \fB\-f\fR'.
|
|
.IP
|
|
Without \fB\-\-stream\fR and with \fB\-\-pretty\fR (either set or implied),
|
|
HTTPie fetches the whole response before it outputs the processed data.
|
|
.IP
|
|
Set this option when you want to continuously display a prettified
|
|
long\-lived response, such as one from the Twitter streaming API.
|
|
.IP
|
|
It is useful also without \fB\-\-pretty\fR: It ensures that the output is flushed
|
|
more often and in smaller chunks.
|
|
.HP
|
|
\fB\-\-output\fR FILE, \fB\-o\fR FILE
|
|
.IP
|
|
Save output to FILE. If \fB\-\-download\fR is set, then only the response body is
|
|
saved to the file. Other parts of the HTTP exchange are printed to stderr.
|
|
.HP
|
|
\fB\-\-download\fR, \fB\-d\fR
|
|
.IP
|
|
Do not print the response body to stdout. Rather, download it and store it
|
|
in a file. The filename is guessed unless specified with \fB\-\-output\fR
|
|
[filename]. This action is similar to the default behaviour of wget.
|
|
.HP
|
|
\fB\-\-continue\fR, \fB\-c\fR
|
|
.IP
|
|
Resume an interrupted download. Note that the \fB\-\-output\fR option needs to be
|
|
specified as well.
|
|
.SS "Sessions:"
|
|
.HP
|
|
\fB\-\-session\fR SESSION_NAME_OR_PATH
|
|
.IP
|
|
Create, or reuse and update a session. Within a session, custom headers,
|
|
auth credential, as well as any cookies sent by the server persist between
|
|
requests.
|
|
.IP
|
|
Session files are stored in:
|
|
.IP
|
|
/home/gaetano/.httpie/sessions/<HOST>/<SESSION_NAME>.json.
|
|
.HP
|
|
\fB\-\-session\-read\-only\fR SESSION_NAME_OR_PATH
|
|
.IP
|
|
Create or read a session without updating it form the request/response
|
|
exchange.
|
|
.SS "Authentication:"
|
|
.HP
|
|
\fB\-\-auth\fR USER[:PASS], \fB\-a\fR USER[:PASS]
|
|
.IP
|
|
If only the username is provided (\fB\-a\fR username), HTTPie will prompt
|
|
for the password.
|
|
.HP
|
|
\fB\-\-auth\-type\fR {basic,digest}
|
|
.IP
|
|
The authentication mechanism to be used. Defaults to "basic".
|
|
.IP
|
|
"basic": Basic HTTP auth
|
|
"digest": Digest HTTP auth
|
|
.SS "Network:"
|
|
.HP
|
|
\fB\-\-proxy\fR PROTOCOL:PROXY_URL
|
|
.IP
|
|
String mapping protocol to the URL of the proxy
|
|
(e.g. http:http://foo.bar:3128). You can specify multiple proxies with
|
|
different protocols.
|
|
.HP
|
|
\fB\-\-follow\fR
|
|
.IP
|
|
Set this flag if full redirects are allowed (e.g. re\-POST\-ing of data at
|
|
new Location).
|
|
.HP
|
|
\fB\-\-verify\fR VERIFY
|
|
.IP
|
|
Set to "no" to skip checking the host's SSL certificate. You can also pass
|
|
the path to a CA_BUNDLE file for private certs. You can also set the
|
|
REQUESTS_CA_BUNDLE environment variable. Defaults to "yes".
|
|
.HP
|
|
\fB\-\-cert\fR CERT
|
|
.IP
|
|
You can specify a local cert to use as client side SSL certificate.
|
|
This file may either contain both private key and certificate or you may
|
|
specify \fB\-\-cert\-key\fR separately.
|
|
.HP
|
|
\fB\-\-cert\-key\fR CERT_KEY
|
|
.IP
|
|
The private key to use with SSL. Only needed if \fB\-\-cert\fR is given and the
|
|
certificate file does not contain the private key.
|
|
.HP
|
|
\fB\-\-timeout\fR SECONDS
|
|
.IP
|
|
The connection timeout of the request in seconds. The default value is
|
|
30 seconds.
|
|
.HP
|
|
\fB\-\-check\-status\fR
|
|
.IP
|
|
By default, HTTPie exits with 0 when no network or other fatal errors
|
|
occur. This flag instructs HTTPie to also check the HTTP status code and
|
|
exit with an error if the status indicates one.
|
|
.IP
|
|
When the server replies with a 4xx (Client Error) or 5xx (Server Error)
|
|
status code, HTTPie exits with 4 or 5 respectively. If the response is a
|
|
3xx (Redirect) and \fB\-\-follow\fR hasn't been set, then the exit status is 3.
|
|
Also an error message is written to stderr if stdout is redirected.
|
|
.SS "Troubleshooting:"
|
|
.HP
|
|
\fB\-\-ignore\-stdin\fR
|
|
.IP
|
|
Do not attempt to read stdin.
|
|
.HP
|
|
\fB\-\-help\fR
|
|
.IP
|
|
Show this help message and exit.
|
|
.HP
|
|
\fB\-\-version\fR
|
|
.IP
|
|
Show version and exit.
|
|
.HP
|
|
\fB\-\-traceback\fR
|
|
.IP
|
|
Prints exception traceback should one occur.
|
|
.HP
|
|
\fB\-\-debug\fR
|
|
.IP
|
|
Prints exception traceback should one occur, and also other information
|
|
that is useful for debugging HTTPie itself and for reporting bugs.
|
|
.PP
|
|
For every \fB\-\-OPTION\fR there is also a \fB\-\-no\-OPTION\fR that reverts OPTION
|
|
to its default value.
|
|
|
|
.SH REPORTING BUGS
|
|
Suggestions and bug reports are greatly appreciated: <https://github.com/jakubroztocil/httpie/issues>
|
|
|
|
.SH AUTHOR
|
|
httpie was written by Jakub Roztocil <jakub@roztocil.name>.
|
|
.PP
|
|
This manual page was written for the Debian project (and may be used by others).
|
|
|