Skip to content

About

A CLI that runs the requests stored in a Postman filesystem-format workspace

Topics

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

preman logo

preman

Run a Postman Local View workspace, unary gRPC included, from the terminal or a desktop app

A CLI and a macOS app that read the .postman/ and postman/ files checked into your repository and run them locally: HTTP and unary gRPC, Postman scripts and tests, environments, and CI reports, without the paid Postman runner.

Release npm License Built with TypeScript Built with Electron CI

Releases · Documentation · Contributing · Report a bug

Why · Highlights · Install · Quick start · How it works · Reference · License

Opening a request in the preman desktop app, sending it, and reading its tests

Why

Local View and Native Git keep collections, environments, specs, and tests in the same Git repository as the application code. Postman Desktop remains a good place to edit them. The free Postman CLI can run HTTP collections, but gRPC collection runs require a paid plan:

$ postman collection run postman/collections/payment
Error: This collection contains gRPC requests. Please upgrade your plan to run collections with gRPC protocol support.
Visit https://www.postman.com/pricing/ for more details.

preman reads the checked-in files directly and runs those requests locally. It is a small alternative runner for Postman's filesystem format, not a replacement for the full Postman CLI.

Highlights

In the app, Cmd+K opens any request by name, and a script's pm.environment.set carries a login token into the next request:

Opening Login and Profile from the command palette and sending both

A pasted curl becomes a request file you can send straight away:

Importing a curl command as a request and sending it

Install

CLI: requires Node.js 20 or later.

npm install -g preman

Desktop app: download the arm64 DMG from the latest release. Once installed, the app updates itself.

Platform Download
macOS (Apple silicon) preman-<version>-arm64.dmg

The app is ad-hoc signed rather than notarized, so macOS calls the download damaged the first time. Drag preman.app to /Applications and clear the quarantine attribute:

xattr -dr com.apple.quarantine /Applications/preman.app

See Install for why, and for building from source.

Quick start

From a repository connected to Postman Local View:

preman list
preman run "payment/Long Chau"
payment/Long Chau  →  pe.aev2.ExchangeService.Exchange
target localhost:9095 [plaintext] (request url) · schema proto-file

✓ OK / OK 563ms
{
  "return_code": "OK",
  "transaction": { ... }
}

✓ Transaction status is TRANS_PROCESSING
1 test · 1 passed
  1. preman searches upward from the current directory for .postman/resources.yaml or a postman/collections directory; -d <path> points it at another repository.
  2. preman run <collection> runs every request in a collection or folder in Postman order; -e <name> picks the environment.
  3. If a gRPC request cannot find its schema, preman protos names the link that is missing.
  4. In the app, Open workspace… on the same repository shows the same requests.

How it works

preman is three packages. @preman/core is the engine: it discovers the workspace, resolves variables, runs scripts in a node:vm sandbox, and sends the request. The preman CLI and @preman/desktop are two front ends to it, and both read and write the same files, so the workspace on disk is the only state they share. The desktop app runs three kinds of process: the main process owns the window and holds no workspace state, each open workspace gets its own engine in an Electron utility process, and the renderer is a pure view that talks to that engine over a MessagePort. Response bodies stay in the engine, and edits are written through the YAML document API so comments and formatting survive. The reference describes the behaviour in full, and docs/decisions records why it is built this way.

Documentation

Using preman

The desktop app

Reference

  • Reference: selection rules, variable precedence, protocol behaviour, scripts, assertions, exit codes, schema resolution, and the engine protocol.
  • Decisions: the architecture decision records.
  • Performance: the budgets the test suite asserts.

Not supported

  • Streaming gRPC (client, server or bidirectional), gRPC server reflection, WebSocket and other request kinds; a collection run reports them instead of executing them.
  • Intel, universal, Windows and Linux builds of the desktop app.

Contributing

Bug reports and pull requests are welcome. CONTRIBUTING.md covers setting up and which checks a change needs; AGENTS.md is the full reference for commands and conventions.

License

MIT

About

A CLI that runs the requests stored in a Postman filesystem-format workspace

Topics

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages