User Guide

Installation

Just install it like a regular Python package:

$ pip install http-prompt

You’ll probably see some permission errors if you’re trying to install it on the system-wide Python. It isn’t recommended. But if that’s what you want to do, you need to sudo:

$ sudo pip install http-prompt

Another alternative is to use --user option to install the package into your user directory:

$ pip install --user http-prompt

To upgrade HTTP Prompt, do:

$ pip install -U http-prompt

Quickstart

To start a session, you use the http-prompt executable:

# Start with the last session or http://localhost:8000
$ http-prompt

# Start with the given URL
$ http-prompt http://httpbin.org

# Start with some initial options
$ http-prompt localhost:8000/api --auth user:pass username=somebody

Once you’re in a session, you can use the following commands.

To change URL address, use cd:

# Relative URL path
> cd api/v1

# Absolute URL
> cd http://localhost/api

To add headers, querystring, or body parameters, use the syntax as in HTTPie. The following are all valid:

# Header
> Content-Type:application/json

# Querystring parameter
> page==2

# Body parameters
> username=foo
> full_name='foo bar'

# Body parameters in raw JSON (new in v0.9.0)
> number:=1234
> is_ok:=true
> names:=["foo","bar"]
> user:='{"username": "foo", "password": "bar"}'

# Write them in one line
> Content-Type:application/json page==2 username=foo

You can also add HTTPie options like this:

> --form --auth user:pass
> --verify=no

# HTTPie options and request parameters in one line
> --form --auth user:pass username=foo Content-Type:application/json

To preview how HTTP Prompt is going to call HTTPie, do:

> httpie post
http --auth user:pass --form POST http://localhost/api apikey==abc username=john

You can temporarily override the request parameters by supplying options and parameters in httpie command. The overrides won’t affect the later requests.

# No parameters initially
> httpie
http http://localhost

# Override parameters temporarily
> httpie /api/something page==2 --json
http --json http://localhost/api/something page==2

# Current state is not affected by the above overrides
> httpie
http http://localhost

Since v0.6.0, apart from httpie command, you can also use env to print the current session:

> env
--verify=no
cd http://localhost
page==10
limit==20

To actually send an HTTP request, enter one of the HTTP methods:

> get
> post
> put
> patch
> delete
> head
> options (new in v0.8.0)

The above HTTP methods also support temporary overriding:

# No parameters initially
> httpie
http http://localhost

# Send a request with some overrided parameters
> post /api/v1 --form name=jane

# Current state remains intact
> httpie
http http://localhost

To remove an existing header, a querystring parameter, a body parameter, or an HTTPie option:

# Remove a header
> rm -h Content-Type

# Remove a querystring parameter
> rm -q apikey

# Remove a body parameter
> rm -b username

# Remove an HTTPie option
> rm -o --auth

To reset the session, i.e., clear all parameters and options:

> rm *

To exit a session, simply enter:

> exit

Output Redirection

New in v0.6.0.

You can redirect the output of a command to a file by using the syntax:

# Write output to a file
> COMMAND > /path/to/file

# Append output to a file
> COMMAND >> /path/to/file

where COMMAND can be one of the following:

  • env
  • httpie
  • HTTP actions: get, post, put, patch, delete, head, options

Saving and Loading Sessions

One of the use cases of output redirection is to save and load sessions, which is especially useful for team collaboration, where you want to share your sessions with your team members.

To save your current session, you redirect the output of env to a file:

> env > /path/to/file

To load a saved session, you can use source or exec. Their only difference is that exec wipes out the current session before loading. Usage:

# Update the current session
> source /path/to/file

# Wipe out the current session and load from a file
> exec /path/to/file

New in v0.11.0.

Load a saved session from the command line directly with the --env option. This allows you for example to define aliases and easily start HTTP Prompt with a full configuration already loaded for each of your projects.

# Define alias for project1
$ alias http_project1='http-prompt --env /path/to/project1/env/file'

# Launch HTTP Prompt for project1
$ http_project1

Any extra argument in the command line is still used and overwrites the value from the session file if already present

# Use saved session but overwrite the URL and add a parameter
$ http-prompt --env /path/to/file localhost:8080 page==2

Saving HTTP Responses

Printing HTTP responses to the console is good for small text responses. For larger text or binary data, you may want to save the response to a file. Usage:

# Save http://httpbin.org/image/png to a file
> cd http://httpbin.org/image/png
> get > pig.png

# Or use this one-liner
> get http://httpbin.org/image/png > pig.png

Pipeline

New in v0.7.0.

HTTP Prompt supports simplified pipeline syntax, where you can pipe the output to a shell command:

# Replace 'localhost' to '127.0.0.1'
> httpie POST http://localhost | sed 's/localhost/127.0.0.1/'
http http://127.0.0.1

# Only print the line that contains 'User-Agent' using grep
> get http://httpbin.org/get | grep 'User-Agent'
    "User-Agent": "HTTPie/0.9.6"

On macOS, you can even copy the result to the clipboard using pbcopy:

# Copy the HTTPie command to the clipboard (macOS only)
> httpie | pbcopy

Another cool trick is to use jq to parse JSON data:

> get http://httpbin.org/get | jq '.headers."User-Agent"'
"HTTPie/0.9.6"

Note: Syntax with multiple pipes is not supported currently.

Shell Substitution

New in v0.7.0.

Shell substitution happens when you put a shell command between two backticks like `...`. This syntax allows you compute a value from the shell environment and assign the value to a parameter:

# Set date to current time
> date==`date -u +"%Y-%m-%d %H:%M:%S"`
> httpie
http http://localhost:8000 'date==2016-10-08 09:45:00'

# Get password from a file. Suppose the file has a content of
# "secret_api_key".
> password==`cat ./apikey.txt`
> httpie
http http://localhost:8000 password==secret_api_key

Configuration

New in v0.4.0.

When launched for the first time, HTTP Prompt creates a user config file at $XDG_CONFIG_HOME/http-prompt/config.py (or %LOCALAPPDATA%/http-prompt/config.py on Windows). By default, it’s ~/.config/http-prompt/config.py (or ~/AppData/Local/http-prompt/config.py).

config.py is a Python module with all the available options you can customize. Don’t worry. You don’t need to know Python to edit it. Just open it up with a text editor and follow the guidance inside.

Persistent Context

New in v0.4.0.

HTTP Prompt keeps a data structure called context to represent your current session. Every time you enter a command modifying your context, HTTP Prompt saves the context to your filesystem, enabling you to resume your previous session when you restart http-prompt.

The last saved context is located at $XDG_DATA_HOME/http-prompt/context.hp (or %LOCALAPPDATA%/http-prompt/context.hp on Windows). By default, it’s ~/.local/share/http-prompt/context.hp (or ~/AppData/Local/http-prompt/context.hp).

As context data may contain sensitive data like API keys, you should keep the user data directory private. By default, HTTP Prompt sets the modes of $XDG_DATA_HOME/http-prompt to rwx------ (i.e., 700) so that the only person who can read it is the owner (you).

Note for users of older versions: Since 0.6.0, HTTP Prompt only stores the last context instead of grouping multiple contexts by hostnames and ports like it did previously. We changed the behavior because the feature can be simply replaced by env, exec and source commands. See the discussion in issue #70 for detail.

ls, cd, and OpenAPI/Swagger Specification

New in v0.10.0.

OpenAPI (formerly known as Swagger) is a specification that describes an HTTP/REST API. The http-prompt has a --spec option for you to provide an OpenAPI specification in JSON format. The specification enables HTTP Prompt to do some cool things like autocomplete API endpoint paths and parameters for you.

See it in action:

ls-demo

To use this feature, specify an OpenAPI/Swagger specification file with --spec command line option:

# Specify a spec on local filesystem
$ http-prompt http://localhost:8000 --spec /path/to/spec.json

# Specify a spec on the internet (https://apis.guru has lots of them)
$ http-prompt https://api.github.com --spec https://api.apis.guru/v2/specs/github.com/v3/swagger.json

Then you can use ls and cd commands to navigate API endpoints with autocomplete!