@theholocron/holocron-plugin-postman

Postman plugin for Holocron. Implements the multi-cardinality tooling capability against Postman's REST API.

Install

pnpm add -D @theholocron/holocron-plugin-postman@alpha

Why REST, not the CLI

Postman ships a CLI (postman, the newer + more capable successor to newman), but for our tooling surface — collection / spec / environment management — REST is the canonical interface and avoids a system-binary dependency. The CLI is best suited for running collections (the newman use case); we sync, we don't run.

Auth

Token resolution order:

1. --token <KEY> flag on the holocron invocation
2. HOLOCRON_POSTMAN_API_KEY env var
3. POSTMAN_API_KEY env var (Postman's own standard)
4. Keyring postman.<org> — tried first when an org is active via --org, HOLOCRON_ORG, or org in holocron.config.ts
5. Keyring postman — unnamespaced fallback; set via holocron auth set postman <key>

Generate the key at https://web.postman.co/settings/me/api-keys.

Config

{
  "providers": {
    "tooling": [
      [
        "postman",
        {
          "workspaceId": "00000000-0000-0000-0000-000000000000",
          "specFile": "apps/api/openapi.json",
          "specName": "Rando API",
          "collectionName": "Rando API",
          "envFiles": ["apps/api/postman-env-staging.json"],
        },
      ],
      "storybook",
    ],
  },
}

• workspaceId (required) — Postman workspace id. Find via holocron tooling postman workspaces.
• specFile (optional) — relative path to the local OpenAPI JSON. sync reads + uploads this.
• specName (optional) — display name in Postman's Spec Hub. Defaults to repo name.
• collectionName (optional) — name for the imported collection. Defaults to specName.
• envFiles (optional) — local Postman environment JSON files to push.

What's implemented

| Method | What it does | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Tooling interface | | | sync() | Reads specFile, upserts the Spec Hub spec, delete-then-imports the collection, find-or-creates each env in envFiles. | | doctor() | Probes /me + /workspaces; returns { ok, message }. | | Postman-specific methods (on PostmanTooling, not on the Tooling interface) | | | getMyself | GET /me — authed user identity. | | listWorkspaces | GET /workspaces. | | findCollectionByName | GET /collections?workspace=… + name filter. | | deleteCollection | DELETE /collections/{uid}. | | importOpenApi | POST /import/openapi?workspace=… with the spec stringified into { type: "string", input }. | | findEnvironmentByName | GET /environments?workspace=… + name filter. | | createEnvironment | POST /environments?workspace=…. | | updateEnvironment | PUT /environments/{uid}. | | findSpecByName | GET /specs?workspaceId=… + name filter. | | createSpec | POST /specs?workspaceId=… (flat body — name/type are NOT wrapped under spec). | | upsertSpecFile | PATCH /specs/{id}/files/{path} (PUT returns 404 here). |

Status

v2.0.0-alpha.0 — published on npm under the alpha dist-tag. Release notes. APIs may still shift before stable v2.0.0.

PostmanPlanLimitError is thrown when Postman responds with limitReachedError (e.g., Free-tier "0 APIs" cap) — callers can discriminate to render "upgrade required" instead of a raw API dump.