Getting Started

Installation¶

Posting can be installed in a matter of seconds on MacOS, Linux, and Windows.

Rye (recommended)¶

Rye is recommended, as it is faster than Homebrew and pipx by several orders of magnitude:

# Install Rye (on MacOS/Linux only - Windows users see below)
curl -sSf https://rye.astral.sh/get | bash

# install Posting
rye install posting

Windows users should follow the guide Rye to learn how to install Rye.

pipx¶

If you prefer, you can install Posting via pipx.

pipx install posting

The methods above will both install Posting globally, in an isolated environment. Do not attempt to install Posting with pip.

Homebrew is not supported

Installing via Homebrew is not supported, as some of Posting's Rust and C dependencies can take over 10 minutes to compile. When using Rye, installation time is measured in tens of milliseconds, and with pipx it's just a few seconds.

A quick introduction¶

This introduction will show you how to create a simple POST request to the JSONPlaceholder mock API to create a new user. It focuses on an efficient keyboard-driven workflow, but you can also use the mouse if you prefer.

Collections and requests¶

A collection is simply a directory which may contain requests saved by Posting.

If you launch Posting without specifying a collection, any requests you create will be saved in the "default" collection. This is a directory reserved by Posting on your filesystem, and unrelated to the directory you launched Posting from.

This is fine for quick throwaway requests, but you'll probably want to create a new collection for each project you work on so that you can check it into version control.

To create a new collection, simply create a new directory and pass it into Posting:

mkdir my-collection
posting --collection my-collection

Now, any requests you create will be saved in the my-collection directory as simple YAML files with the .posting.yaml extension.

Creating a request¶

When you launch Posting, no request is open, so the UI will look rather empty.

Let's create a simple POST request to the JSONPlaceholder mock API to create a new user.

Press Ctrl+T to open the request method dropdown, then press P to quickly select the POST method.

Press Tab to move focus to the next widget, which is the URL bar. The URL bar can also be focused with Ctrl+L. Type https://jsonplaceholder.typicode.com/users into the URL bar.

Adding a JSON body¶

Press Ctrl+O to enter "jump mode", then press W to quickly jump to the "Body" tab.

Press J (or Down) to move the cursor down to the dropdown. Press Enter to open it, and select the option Raw (json, text, etc.).

Move down to the text area below using J (or Down), and type (or paste) the JSON below.

{
  "name": "John Doe",
  "username": "johndoe",
  "email": "john.doe@example.com"
}

Viewing keyboard shortcuts¶

Now is probably a good time to note that you can see the full list of keyboard shortcuts for the focused widget by pressing F1. The text area widget in particular has a lot of useful shortcuts and supports things like undo/redo.

Sending the request¶

Press Ctrl+J to send the request. This shortcut works globally.

Saving the request¶

Finally, press Ctrl+S to save the request to disk. Fill out the form on the modal that appears, and press Enter or Ctrl+N to write the request to disk.