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.
Releases · Documentation · Contributing · Report a bug
Why · Highlights · Install · Quick start · How it works · Reference · License
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.
- Unary gRPC and HTTP: a request's
.protoor embedded descriptor; multipart,urlencoded, binary and GraphQL bodies; server-sent events. - Postman's scripts, as written: pre-request, post-response and
onMessage,pm.test,pm.sendRequest, and Lodash, CryptoJS, Moment and the other common libraries. - Made for CI: JSON and JUnit reports, iteration data, environment writeback, and exit codes that tell a transport failure from a failed test.
- A linter for silent mistakes: fields that parse but are never read, found without sending a request.
- Protos that resolve on every machine: declared through one shared link per repository, with the missing ones named and a one-command repair.
- Paste a curl or grpcurl: it becomes a request file, and every flag that could not be kept is named.
- Copy a request as a command: the
curlorgrpcurlthat would send it, with what it cannot carry listed. - Migrate from Postman cloud: a cloud workspace onto disk, gRPC included, borrowing Postman Desktop's session.
- A desktop app on the same files: edit and run requests in a window; the
CLI sees every change, and
git statusstays clean. - Mutual TLS and private CAs: from flags or
.postman/preman.yaml.
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:
A pasted curl becomes a request file you can send straight away:
CLI: requires Node.js 20 or later.
npm install -g premanDesktop 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.appSee Install for why, and for building from source.
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
premansearches upward from the current directory for.postman/resources.yamlor apostman/collectionsdirectory;-d <path>points it at another repository.preman run <collection>runs every request in a collection or folder in Postman order;-e <name>picks the environment.- If a gRPC request cannot find its schema,
preman protosnames the link that is missing. - In the app, Open workspace… on the same repository shows the same requests.
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.
Using preman
- Install: the CLI, the desktop app, opening the unsigned macOS app, updates, and building from source.
- Running from the terminal: commands, options, CI reports, and what runs.
- Linting: finding fields preman will not honour, without sending a request.
- Protos: declaring
.protofiles through a shared link. - Importing and copying commands:
curlandgrpcurl, in and out. - Migrating from Postman cloud: a cloud workspace onto disk.
The desktop app
- The desktop app: workspaces, requests, environments, auth, bodies and responses.
- The log and debugging: what the log holds, and attaching an inspector to the engine.
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.
- 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.
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.

