Getting started

Launch Postguy and find your workspace

Start the app. It picks a workspace folder in this order:

1. ./postguy-workspace, if that folder exists where you launched the app (and you passed no --workspace option).
2. ~/postguy-workspace (%USERPROFILE%\postguy-workspace on Windows).

The folder is created on first use. It holds all your collections, environments and settings as plain files.

A new workspace opens on a welcome screen. It has three buttons: New HTTP request, Import… and Settings…. It also shows the hint "Cmd/Ctrl+N new request · Cmd/Ctrl+I import · Cmd/Ctrl+K commands". The status line at the bottom right reads "Ready".

Create a collection and a request

Press Cmd/Ctrl+N. In an empty workspace, this creates a collection named New Collection with a request named New Request, and opens the request in a tab. The request is an HTTP GET.

To create things by hand, use the + button at the top of the sidebar. Its menu offers:

• New HTTP request
• New gRPC request
• New WebSocket request
• New collection
• New environment

Right-click a collection in the sidebar for Rename (F2), Add request, Add folder, Run, Duplicate and Delete.

Rename the collection to My API.

Send a request

In the request tab, enter this URL and click Send (or press Cmd/Ctrl+Enter):

https://httpbin.org/get

The response appears below the request, with its status, time and size.

Read the response

The response viewer has four tabs:

Save the request

Press Cmd/Ctrl+S. A request tab with unsaved edits shows a dirty marker. The collection runner and the CLI use the saved version, so save before you run.

Add an environment

An environment holds variables you can reuse in any request.

1. In the sidebar, open the + menu and choose New environment. It opens as a tab named New Environment. Edit the name at the top.
2. In the variables table (columns Variable and Value), add a variable baseUrl with the value https://httpbin.org.
3. In the selector at the right of the tab strip, which reads No environment, choose your environment.
4. Change the request URL to use the variable, then send again:

{{baseUrl}}/get

{{name}} is replaced when you send. For the lookup order and secret variables, see Variables.

Add a test

Open the Tests tab of the request. The Assertions table has one row per check, with the columns expression, operator and value. Add a row:

Then open the Scripts tab and put this in the Post-response editor:

pm.test("status 200", () => pm.response.to.have.status(200))

Send the request again and open Test Results. Both checks are listed with a PASS or FAIL badge. Save the request. See Scripts and tests.

Run the collection in the Runner

Right-click the collection in the sidebar and choose Run. Or press Cmd/Ctrl+K and choose Open collection runner.

The Runner tab lets you set:

• Collection
• Environment
• Requests: which ones to include
• Iterations
• Delay
• Data file
• Stop on error

Select your environment and click Run My API. Results appear on the right. Filter them by All, Passed, Failed or Skipped. The Download report section offers CSV, Excel, PDF, HTML, JSON and JUnit. See Collection runner.

Run it headlessly

The CLI runs the same engine without a window. Close the app first, because only one process can open a workspace at a time. Then run:

postguy-cli run --collection "My API" --workspace ~/postguy-workspace --reporters cli,junit --out reports

• --collection takes a collection id or its exact name. If the name matches more than one collection, use an id.
• --environment takes an environment id or name the same way. Without it, the run uses the workspace's active environment, which is the one selected in the app. So selecting your environment before you close the app is enough. To be explicit, add --environment "New Environment".
• The cli reporter prints a summary to the terminal.
• The junit reporter writes reports/postguy-run-<run id>.xml.

Exit codes: