{"id":14425,"plugin_id":"plugin_asdk_app_6a6b12e06c5c8191ac5d5252fa5f92c8","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:09:30.248Z","digest":"ff37f1a825ca8483dc58a85adc4b4e54b3e4f9607584aecdc7b80826d199c091","against":null,"payload":{"name":"bootstrap","description":"Resolves the Postman CLI, authenticates when the task needs it, and manages the filesystem/workspace binding for a repository. Use when the user asks to set up Postman, enable filesystem workflows, authenticate, initialize, import, connect, pull, push, sync, or share a workspace — and before skills that need a linked workspace, only when the CLI, linked workspace, or spec path has not already been confirmed.","included_files":[{"relative_path":"reference/cli_installation.md","size_in_bytes":1645}],"skill_md_contents":"---\nname: bootstrap\ndescription: Resolves the Postman CLI, authenticates when the task needs it, and manages the filesystem/workspace binding for a repository. Use when the user asks to set up Postman, enable filesystem workflows, authenticate, initialize, import, connect, pull, push, sync, or share a workspace — and before skills that need a linked workspace, only when the CLI, linked workspace, or spec path has not already been confirmed.\n---\n\n# Bootstrap Postman for This Repo\n\n## Overview\n\nOne-time and idempotent: every other Postman skill in this plugin reads the\nvalues this one records and re-derives none of them. Finding an existing\n`postman/` tree or an OpenAPI file is a signal to inspect, not to assume this\nrepo is already set up.\n\n## Rules\n\n- Make ad-hoc HTTP calls with `postman request`, never `curl` or another\n  client. If the request already exists in a collection, preserve its saved\n  auth, variables, scripts, and payload by using `postman collection run\n  <collection-path> -i <request>` instead of reconstructing it on the command\n  line; see `api-testing`.\n- Never invent a subcommand or a flag. Run `-h` first and believe it.\n- Lint specs with `postman spec lint`, never `postman api …` — the API Builder\n  is deprecated in v12+ and the CLI prints no warning.\n- Local commands need no login; only commands that reach the Postman\n  workspace do. Don't force a login the task doesn't need.\n- A missing `postman` binary means install it. Route to `postman-mcp-server`\n  only after an install has been attempted and actually failed.\n- Never fabricate a workspace id, spec path, or collections directory. Report\n  the gap and stop.\n- Never echo an API key or session token into output, logs, or summaries.\n- \"Present\" is not \"current\": check the version and existing links before\n  setting anything up.\n- Wire up an existing repo only. Never scaffold a new API or a starter spec.\n- Write no host-specific paths — the same `skills/` directory loads on every\n  route.\n- Do not use `init` or `workspace create` to share or import a workspace that\n  already exists. Choose the direction of sync from the lifecycle table below.\n\n## Ask the CLI: `-h`\n\nThe CLI is self-describing at different levels. Walk down only as far as the\nquestion needs:\n\n```bash\npostman -h                      # resources: collection, spec, mock, monitor, workspace, api, flows…\npostman <resource> -h           # that resource's actions\npostman <resource> <action> -h  # real flags, defaults, and worked `Eg.` lines\n```\n\nRead the third level before writing any command that carries a flag — it is the\nonly place defaults are stated, and a wrong default fails silently. Live output\nis authoritative over any summary, including this file. There is also no single\nverb for \"is the workspace linked and synced\": run `postman workspace -h` and\npick from what it prints.\n\n---\n\n# Process\n\nThree steps, in order. Stop at the first that fails and report which one.\n\n## 1. Resolve the CLI\n\n### 1.1 Check what is already there\n\n**Present, and at which version?**\n\n```bash\ncommand -v postman && postman --version\n```\n\n**Current?** Never blocking — no network is a normal answer. But don't call a\nfeature missing without having made this comparison.\n\n```bash\nnpm view postman-cli version\n```\n\n### 1.2 Install only if missing\n\n**Preferred — npm, all platforms:**\n\n```bash\nnpm install -g postman-cli\n```\n\n**Windows, or avoiding a global npm install:** use the platform installers in\n[reference/cli_installation.md](reference/cli_installation.md). Every route puts\n`postman` on `PATH`.\n\n**Updating a copy that already exists:** use the same route that installed it.\ncurl-installed binaries don't take `npm install -g` cleanly.\n\n**If every route fails:** name what blocked you — no Node, no shell, no write\naccess, or a hosted session that cannot install — then hand off to the\n`postman-mcp-server` skill. An attempted install that actually failed is the\nonly thing that qualifies.\n\n## 2. Establish the filesystem and workspace bindings\n\n### 2.1 Authenticate only if this step needs it\n\nLocal commands need no login, and `postman init` is among them — its own help\nsays *\"No authentication, and safe in CI.\"* Skip this entirely unless the\ncommand you're about to run pulls or pushes an existing workspace, or shares\none with a team.\n\n**With an API key — preferred, non-interactive:**\n\n```bash\n[ -n \"$POSTMAN_API_KEY\" ] && postman login --with-api-key \"$POSTMAN_API_KEY\"\n```\n\n**Browser flow, when that variable is unset:**\n\n```bash\npostman login\n```\n\n**Never echo the key or token.** Auth state lives in the CLI's own config; this\nskill writes no credential file. Report that authentication succeeded, nothing\nmore.\n\n### 2.2 Inspect both sides before choosing a command\n\nRead `.postman/resources.yaml` for `localResources` and `workspace.id`, and\ninspect the local `postman/` tree. When the user names an existing workspace or\nasks to import, sync, or share one, use `workspace list --json` and `workspace\nget <id> --elements --json` to confirm the workspace side. Never create a\nsecond workspace merely because this repository is not connected yet.\n\nPrefer filesystem-first work: materialize an existing workspace with\n`workspace pull <id>`, or initialize local files with `postman init --no-cloud`\nwhen no workspace exists. Then inspect, edit, diff, and validate the\nversion-controlled files before any push.\n\n| Existing state and intent | Use | Why |\n| --- | --- | --- |\n| No workspace exists; start locally | `postman init --json --no-cloud` | Creates the git-native filesystem without requiring login. |\n| No workspace exists; create and bind one | `postman workspace create --visibility <value>` or the explicit init creation path | Creation is the requested lifecycle event. |\n| Workspace exists; enable filesystem work | `postman workspace pull <workspace-id>` | Connects the workspace to the repository and materializes its entities under `postman/`. |\n| Workspace exists; record only the Git binding | `postman workspace connect-git <workspace-id> [path]` | Binds without downloading its contents. |\n| Bound workspace; the workspace is authoritative | `postman workspace pull` | Refreshes local files from the connected workspace. |\n| Bound workspace; local files are authoritative | `postman workspace diff --push-strategy default`, then `postman workspace push` | Previews and publishes creates/updates without deleting unmatched workspace entities. |\n| “Share this existing workspace with my team” and it is already team-accessible | Diff, then `postman workspace push` | Publishes local contents to the existing workspace; `create` would make a duplicate. |\n\nIf “share” also requires changing a personal workspace's visibility or team\npermissions, inspect its metadata first. `push` synchronizes entities; it does\nnot change access control. Do not create a replacement to work around a missing\nmetadata-update command.\n\n`workspace diff` is read-only. Match its push strategy to the intended push.\n`--push-strategy force-sync` can delete workspace entities absent locally, so use it\nonly when the user explicitly requests mirroring and approves the shown\ndeletions. Do not add `-y` merely to bypass a prompt.\n\n### 2.3 Initialize only when there is no workspace to pull\n\n`postman init --json` is the agent-facing form. It writes\n`.postman/resources.yaml` and scaffolds `postman/` for specs, collections and\nenvironments. Downstream skills read that file and nothing else.\n\n```bash\npostman init --json --no-cloud               # local only, no workspace\npostman init --json --visibility personal    # also create and bind a workspace\n```\n\nUse `--visibility` only when a new workspace is actually wanted. If the\nworkspace already exists, use `pull` to enable the filesystem workflow;\nuse `push` only when publishing local changes to an already-bound workspace.\n\n**The workspace step is interactive** without `--no-cloud` or `--visibility`.\n\n**Read the payload, not stderr.** Take `bindings` and `exitCode` from the JSON.\nEach binding reports a `source` of `inferred` or `none` — an inferred spec is a\nguess worth confirming before building on it.\n\n**Exit codes that are not failures:** 2 means several specs could be\nauthoritative, so re-run with `--spec <path>`. 5 means the local files were\nwritten but the requested workspace was not created — it does *not* mean re-run.\n\n## 3. Verify and report\n\n### 3.1 Checkpoints\n\n- `postman --version` returned a real version.\n- Auth is confirmed, or established as not required for this task.\n- `.postman/resources.yaml` names a spec or a collections directory.\n- `workspace.id` is set, or the run was deliberately local-only — `--no-cloud`\n  leaves it empty and still exits 0, which is a pass, not a gap.\n- After `pull`, expected workspace entities exist under `postman/`. After\n  `push`, report created/updated entities and conflicts; do not claim a\n  workspace is shared unless its access level permits the intended teammates.\n\n\"The CLI is installed\" is not the bar, and a loaded skill configures nothing.\n\n### 3.2 Summary format\n\n```md\n## Postman bootstrap\n- **CLI**: <version> (latest: <version> | not checked)\n- **Auth**: <api-key | browser | not required for this task>\n- **Workspace**: <id | none — local only>\n- **Spec path**: <path (inferred | explicit) | none — user must create>\n- **Collections dir**: <path | none — user must create>\n```\n\n---\n\n# Reference Files\n\n- `collection-schema-v3` skill — read when inspecting or writing the\n  collection files this skill resolves.\n- [CLI Installation](reference/cli_installation.md) — read for install, update\n  and uninstall commands per platform.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}