diff --git a/CLAUDE.md b/CLAUDE.md index bcfd762..c056e76 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,8 +11,8 @@ The Postman Plugin for Claude Code — a pure-markdown, configuration-driven plu ``` .claude-plugin/plugin.json # Plugin manifest (name, version, metadata) .mcp.json # MCP server auto-config (Postman MCP at mcp.postman.com) -commands/*.md # 11 slash commands (/postman:) -skills/*/SKILL.md # 7 skills (knowledge, agent-ready APIs, CLI, send-request, generate-spec, run-collection, context) +commands/*.md # 15 slash commands (/postman:) +skills/*/SKILL.md # 11 skills (knowledge, agent-ready APIs, CLI, send-request, generate-spec, run-collection, context, and Flows: list-flows, trigger-flow, deploy-flow, get-flow-run) skills/*/references/*.md # On-demand reference files loaded by skills only when needed agents/readiness-analyzer.md # Sub-agent for API readiness analysis examples/ # Sample output (readiness report) @@ -31,7 +31,7 @@ examples/ # Sample output (readiness report) **Commands** (`commands/*.md`): YAML front matter with `description` and `allowed-tools`. Each defines a structured workflow invoked as `/postman:`. - MCP commands: setup, sync, search, test, mock, docs, security, learn (learn requires Full mode — `searchLearningCenter` is absent in `minimal`/`code`) -- CLI commands: request, generate-spec, run-collection +- CLI commands: request, generate-spec, run-collection, list-flows, trigger-flow, deploy-flow, get-flow-run **Skills** (`skills/*/SKILL.md`): YAML front matter with `name`, `description`, `user-invocable`. Auto-injected context, not directly invoked. `postman-knowledge` provides MCP tool guidance; `agent-ready-apis` provides readiness criteria; `postman-cli` provides CLI and git sync file structure knowledge; `postman-context` provides API discovery, exploration, and code generation from real API definitions. @@ -51,12 +51,16 @@ These are documented in `skills/postman-knowledge/mcp-limitations.md` and must b ## Postman CLI Commands -Three commands use the Postman CLI instead of MCP. They require `postman-cli` installed locally (`npm install -g postman-cli`) and authenticated (`postman login`). If CLI is not found, show install instructions and stop. +Several commands use the Postman CLI instead of MCP. They require `postman-cli` installed locally (`npm install -g postman-cli`) and authenticated (`postman login`). If CLI is not found, show install instructions and stop. - `/postman:request` — Send HTTP requests via `postman request ` - `/postman:generate-spec` — Scan code for API routes, generate OpenAPI 3.0 YAML, validate with `postman spec lint` - `/postman:run-collection` — Run collection tests via `postman collection run ` using cloud IDs from `.postman/resources.yaml` - `/postman:context` — Discover, explore, and install APIs via `postman context`. Searches Postman's API network, fetches real API definitions, and generates client code from them. +- `/postman:list-flows` — List flows in a workspace and resolve a flow name to its 24-char ID via `postman flows list` +- `/postman:trigger-flow` — Trigger a deployed flow via `postman flows trigger`, with a deploy-then-trigger fallback when the flow isn't deployed +- `/postman:deploy-flow` — Deploy a flow to make it triggerable via `postman flows deploy` (proposes and confirms a trigger path first) +- `/postman:get-flow-run` — Inspect a run by Run ID via `postman flows get-run` (per-block logs, failing block, status) CLI commands work with Postman's git sync structure: `postman/collections/` (v3 folder format), `postman/environments/`, `postman/specs/`, and `.postman/resources.yaml` for cloud ID mapping. diff --git a/commands/deploy-flow.md b/commands/deploy-flow.md new file mode 100644 index 0000000..99df80d --- /dev/null +++ b/commands/deploy-flow.md @@ -0,0 +1,22 @@ +--- +description: Deploy a Postman Flow so it becomes triggerable, proposing and confirming a trigger path +allowed-tools: Bash, Read +--- + +Deploy a Postman Flow using the Postman CLI. Follow the `deploy-flow` skill. + +## Inputs (from the user's message) +- The flow (a 24-char ID, or a name to resolve via `list-flows`) +- Optionally a desired trigger path and whether auth is required + +## Steps +1. Resolve the flow ID (use `list-flows` if given a name; ask for the workspace if unknown). +2. Propose a trigger path derived from the flow name (e.g. "Checkout" → `/checkout`) and **confirm the path + the deploy action** with the user — deploy is mutating and MUST NOT run without explicit confirmation. +3. Show the command, then run it after confirmation: + ```bash + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows deploy --path /checkout + ``` +4. Report the **Trigger URL** and whether the **trigger is enabled**. If it's off, offer `postman flows update --trigger on` (confirm first). +5. If this was part of a deploy-then-trigger request, hand back to `trigger-flow` to run it. + +Always prefix CLI calls with `POSTMAN_CLI_SOURCE=claude-code-plugin`. Reuse existing `postman login` credentials — never authenticate twice. diff --git a/commands/get-flow-run.md b/commands/get-flow-run.md new file mode 100644 index 0000000..e424c6d --- /dev/null +++ b/commands/get-flow-run.md @@ -0,0 +1,22 @@ +--- +description: Inspect a Postman Flow run by its Run ID — per-block logs, failing block, and status +allowed-tools: Bash, Read +--- + +Inspect a specific Postman Flow run using the Postman CLI. Follow the `get-flow-run` skill. + +## Inputs (from the user's message) +- The Run ID (the `x-run-id` that `trigger-flow` reported; ask if unknown) +- Optionally a block ID to focus on + +## Steps +1. Take the Run ID. +2. Run a summary, then add `--logs` for detail: + ```bash + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id --logs + ``` + Narrow to a block with `--filter `. +3. Report **which block failed and why** and the **run status**. + +Read-only: no confirmation needed. Prefix CLI calls with `POSTMAN_CLI_SOURCE=claude-code-plugin`. Reuse existing `postman login` credentials. diff --git a/commands/list-flows.md b/commands/list-flows.md new file mode 100644 index 0000000..febdaf4 --- /dev/null +++ b/commands/list-flows.md @@ -0,0 +1,21 @@ +--- +description: List Postman Flows in a workspace and resolve a flow name to its 24-character ID +allowed-tools: Bash, Read +--- + +List Postman Flows in a workspace using the Postman CLI. Follow the `list-flows` skill. + +## Inputs (from the user's message) +- The workspace ID (ask if unknown) +- Optionally a name/pattern to filter by + +## Steps +1. Ensure you have a workspace ID; ask which workspace if not. +2. Run: + ```bash + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows list --workspace + ``` + Narrow with `--filter ""` when resolving a specific flow; use `--sort name` / `--paginate` as needed. +3. Report flow **names + IDs** (and recent status where shown). When resolving a name for another action, return the single matching ID, or present candidates and ask the user to choose on multiple matches — never guess. + +Read-only: no confirmation needed. Prefix CLI calls with `POSTMAN_CLI_SOURCE=claude-code-plugin`. Reuse existing `postman login` credentials. diff --git a/commands/trigger-flow.md b/commands/trigger-flow.md new file mode 100644 index 0000000..6a1565c --- /dev/null +++ b/commands/trigger-flow.md @@ -0,0 +1,24 @@ +--- +description: Trigger (run) a deployed Postman Flow with inputs, and deploy-then-trigger it if it isn't deployed yet +allowed-tools: Bash, Read +--- + +Trigger a deployed Postman Flow from natural language, using the Postman CLI. Follow the `trigger-flow` skill. + +## Inputs (from the user's message) +- The flow (a 24-char ID, or a name to resolve via `list-flows`) +- Any inputs / query params / headers / scenario +- The workspace ID (ask if a name needs resolving and you don't have it) + +## Steps +1. Resolve the flow ID (use `list-flows` if given a name; disambiguate multiple matches; ask for the workspace if unknown). +2. Build the flags from natural language: `-i k=v`, `-q k=v`, `--headers k=v`, `-s ""`. +3. Show the command, then run it: + ```bash + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows trigger -i amount=4200 + ``` +4. Report the **Run ID**, **HTTP status**, and **response body**. +5. If not deployed → explain and **offer to deploy** (via `deploy-flow`, explicit confirmation required), then re-trigger. If the trigger is disabled → offer `postman flows update --trigger on` (confirm), then trigger. +6. On a non-2xx response → surface status + body and offer `get-flow-run --run-id ` for per-block detail. + +Always prefix CLI calls with `POSTMAN_CLI_SOURCE=claude-code-plugin`. Reuse existing `postman login` credentials — never authenticate twice. Confirm before any mutating action (deploy, enable trigger). diff --git a/skills/deploy-flow/SKILL.md b/skills/deploy-flow/SKILL.md new file mode 100644 index 0000000..0345e2e --- /dev/null +++ b/skills/deploy-flow/SKILL.md @@ -0,0 +1,64 @@ +--- +name: deploy-flow +description: Deploy a Postman Flow so it becomes triggerable, using the Postman CLI. Use when the user wants to deploy, publish, or make a flow callable, or when trigger-flow found an undeployed flow and the user confirmed. +--- + +You are a Postman Flows assistant that deploys Flows using the Postman CLI. Deploying makes a flow triggerable and returns its **Trigger URL**. + +## The command this wraps + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows deploy --path [options] +``` + +Options: +- `-p, --path ` — **required** URL path for the trigger (e.g. `/checkout`) +- `-t, --timeout ` — HTTP session timeout, 5000ms–60000ms (default `10000ms`) +- `-a, --auth` — enable authentication on the trigger + +## Step 1: Resolve the flow ID + +If given a name rather than a 24-char ID, resolve it with the `list-flows` skill (ask which workspace if unknown; disambiguate on multiple matches). + +## Step 2: Propose a trigger path and CONFIRM + +Deploy **requires** a URL path. Propose a sensible default derived from the flow name: +- "Checkout" → `/checkout` +- "Nightly Report" → `/nightly-report` + +Confirm the path and the deploy action with the user before running — deploy is mutating and requires explicit confirmation. + +Ask about authentication only if relevant ("Should the trigger require auth?"). Add `--auth` only if they say yes. + +## Step 3: Deploy + +Show the exact command, then run it after confirmation: + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows deploy 12345-67890-abcdef --path /checkout +``` + +Report back: +- the resulting **Trigger URL** +- whether the **trigger is enabled**. If the CLI notes the trigger is off, tell the user and offer to enable it: + ```bash + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows update 12345-67890-abcdef --trigger on + ``` + (enabling is also a state change → confirm first). + +Example report: +``` +Deployed the Checkout flow. + Trigger URL: https:///checkout + Trigger: enabled +``` + +## Step 4: Hand back to trigger (if part of deploy-then-trigger) + +If deploying was requested so the user could run the flow, hand control back to the `trigger-flow` skill to fire it and report the Run ID + status + response — completing the deploy-then-trigger journey in one conversation. + +--- + +Read `references/flows-cli-baseline.md` for CLI prefixing, credential reuse, and error handling rules. + +Deploying and enabling a trigger are mutating actions — confirm with the user before running. On a path conflict, surface the CLI message and propose an alternative path. diff --git a/skills/deploy-flow/references/flows-cli-baseline.md b/skills/deploy-flow/references/flows-cli-baseline.md new file mode 100644 index 0000000..d4d3f3c --- /dev/null +++ b/skills/deploy-flow/references/flows-cli-baseline.md @@ -0,0 +1,9 @@ +# Flows CLI Baseline + +These rules apply to every Flows CLI skill. + +- Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin` for telemetry attribution. +- Reuse existing `postman login` / API key credentials. Do not trigger a second authentication. +- Surface CLI errors verbatim. Do not assert access the CLI does not grant. +- **CLI not installed:** "Postman CLI is not installed. Install with: `npm install -g postman-cli`" +- **Not authenticated:** "Run `postman login` (or set `POSTMAN_API_KEY`)." diff --git a/skills/get-flow-run/SKILL.md b/skills/get-flow-run/SKILL.md new file mode 100644 index 0000000..b6a75be --- /dev/null +++ b/skills/get-flow-run/SKILL.md @@ -0,0 +1,56 @@ +--- +name: get-flow-run +description: Inspect a Postman Flow run by Run ID using the Postman CLI — per-block logs, failing block, and status. Use when a trigger returned a non-2xx or the user asks why a run failed. +--- + +You are a Postman Flows assistant that inspects Flow runs using the Postman CLI. + +## The command this wraps + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id [options] +``` + +Options: +- `-r, --run-id ` — **required** (this is the `x-run-id` that `trigger-flow` reported) +- `-l, --logs` — show the detailed event log +- `--filter ` — focus the event log on one or more block IDs (repeatable) + +## Step 1: Get the Run ID + +Use the Run ID the trigger skill just reported (the `x-run-id`). If you don't have one, ask the user for it. + +## Step 2: Inspect + +Start with a summary, then add `--logs` for detail: + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id session-abc123 +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id session-abc123 --logs +``` + +Narrow to a suspect block: +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows get-run --run-id session-abc123 --logs --filter blockId1 +``` + +## Step 3: Report + +Parse the output and report, rather than dumping raw logs: +- **which block failed and why** (the failing block + reason) +- the **run status** + +Example: +``` +Run session-abc123 — failed + Failing block: "HTTP Request (Get Orders)" + Reason: downstream returned 504 after 10s timeout + Status: error +Suggestion: the upstream API timed out — retry, or raise the request timeout. +``` + +--- + +Read `references/flows-cli-baseline.md` for CLI prefixing, credential reuse, and error handling rules. + +This is a read-only operation — no confirmation needed. If the Run ID is not found, confirm it with the user (runs may take a moment to appear). diff --git a/skills/get-flow-run/references/flows-cli-baseline.md b/skills/get-flow-run/references/flows-cli-baseline.md new file mode 100644 index 0000000..d4d3f3c --- /dev/null +++ b/skills/get-flow-run/references/flows-cli-baseline.md @@ -0,0 +1,9 @@ +# Flows CLI Baseline + +These rules apply to every Flows CLI skill. + +- Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin` for telemetry attribution. +- Reuse existing `postman login` / API key credentials. Do not trigger a second authentication. +- Surface CLI errors verbatim. Do not assert access the CLI does not grant. +- **CLI not installed:** "Postman CLI is not installed. Install with: `npm install -g postman-cli`" +- **Not authenticated:** "Run `postman login` (or set `POSTMAN_API_KEY`)." diff --git a/skills/list-flows/SKILL.md b/skills/list-flows/SKILL.md new file mode 100644 index 0000000..2394c40 --- /dev/null +++ b/skills/list-flows/SKILL.md @@ -0,0 +1,55 @@ +--- +name: list-flows +description: List Postman Flows in a workspace using the Postman CLI, and resolve a flow name to its 24-character ID. Use when the user asks which flows they have, or when another skill needs to resolve a flow name to an ID before deploying or triggering. +--- + +You are a Postman Flows assistant that lists Flows and resolves flow names to IDs using the Postman CLI. + +## The command this wraps + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows list --workspace [options] +``` + +Options: +- `-w, --workspace ` — **required** +- `-f, --filter ` — filter by name (name prefix or regex) +- `-s, --sort ` — sort criteria (default `updated`) +- `-p, --paginate` — page through all flows + +## Step 1: Get the workspace ID + +A workspace ID is **required**. If you don't have one, ask the user which workspace to look in. Don't fail silently. + +## Step 2: List + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows list --workspace 12345-67890-abcdef +``` + +Narrow with `--filter` when resolving a specific name: +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows list --workspace 12345-67890-abcdef --filter "Checkout" +``` + +## Step 3: Report / resolve + +- When the user asked to see their flows: report flow **names + IDs** (and recent status where shown). +- When resolving a name for another skill: + - **Single match** → use that ID. + - **Multiple matches** → present the candidates (name + ID) and **ask the user to choose**. Never guess. (Edge case: ambiguous name) + - **No match** → tell the user, and offer to list all flows in the workspace so they can pick. + +Example: +``` +Flows in workspace 12345-67890-abcdef: + 1. Checkout — 6f1a2b3c4d5e6f7a8b9c0d1e (updated 2h ago) + 2. Checkout (old) — 1a2b3c4d5e6f7a8b9c0d1e2f (updated 40d ago) +Two flows match "Checkout" — which one? +``` + +--- + +Read `references/flows-cli-baseline.md` for CLI prefixing, credential reuse, and error handling rules. + +This is a read-only operation — no confirmation needed. diff --git a/skills/list-flows/references/flows-cli-baseline.md b/skills/list-flows/references/flows-cli-baseline.md new file mode 100644 index 0000000..d4d3f3c --- /dev/null +++ b/skills/list-flows/references/flows-cli-baseline.md @@ -0,0 +1,9 @@ +# Flows CLI Baseline + +These rules apply to every Flows CLI skill. + +- Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin` for telemetry attribution. +- Reuse existing `postman login` / API key credentials. Do not trigger a second authentication. +- Surface CLI errors verbatim. Do not assert access the CLI does not grant. +- **CLI not installed:** "Postman CLI is not installed. Install with: `npm install -g postman-cli`" +- **Not authenticated:** "Run `postman login` (or set `POSTMAN_API_KEY`)." diff --git a/skills/trigger-flow/SKILL.md b/skills/trigger-flow/SKILL.md new file mode 100644 index 0000000..61fa1b2 --- /dev/null +++ b/skills/trigger-flow/SKILL.md @@ -0,0 +1,102 @@ +--- +name: trigger-flow +description: Trigger (run) a deployed Postman Flow via the Postman CLI with natural-language inputs. Use when the user wants to execute a flow — handles name-to-ID resolution and deploy-then-trigger fallback. +--- + +You are a Postman Flows assistant that triggers deployed Flows using the Postman CLI. + +## The command this wraps + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows trigger [options] +``` + +Triggering fires a **deployed** flow over its webhook and returns a **Run ID** (`x-run-id`) plus the HTTP status and response body. + +Options: +- `-i, --input ` — payload values (repeatable): `-i amount=4200 -i currency=USD` +- `-f, --input-file ` — payload values from a JSON file (repeatable) +- `-q, --query ` — query parameters (repeatable) +- `--headers ` — custom headers (repeatable): `--headers X-API-Key=123` +- `-s, --scenario ` — use a named scenario from the flow definition +- `-n, --dry-run` — show the request URL + payload without sending (add `--show-secrets` to unmask tokens) +- `-r, --result` — print only the response body + +Flow IDs are 24-character hex. If you only have a name, resolve the ID first (Step 1). + +--- + +## Step 1: Resolve the flow ID + +If the user gave a **24-char ID**, use it directly. + +If the user gave a **name** (e.g. "the Checkout flow"), resolve it to an ID with the `list-flows` skill: +- You need the **workspace ID**. If you don't know it, ask the user which workspace the flow is in. +- List flows in that workspace and match the name. On a single match, use its ID. On **multiple matches**, show the candidates and ask the user to choose. + +Do not fail with "missing flow ID" — always route to resolution or ask for the workspace. + +## Step 2: Build the inputs + +Translate the user's natural-language request into CLI flags: +- "with amount=4200 and currency=USD" → `-i amount=4200 -i currency=USD` +- "pass ?version=v2" → `-q version=v2` +- "send header X-API-Key 123" → `--headers X-API-Key=123` +- "use the Staging scenario" → `-s "Staging"` + +Always show the exact command before running it. If the user wants to preview without sending, use `--dry-run`. + +## Step 3: Trigger + +```bash +POSTMAN_CLI_SOURCE=claude-code-plugin postman flows trigger 12345-67890-abcdef -i amount=4200 +``` + +On success, report back **all three**: +- **Run ID** (from the `x-run-id` header) +- **HTTP status** +- **Response body** + +Example report: +``` +Triggered the Checkout flow. + Run ID: session-abc123 + Status: 200 OK + Response: { "ok": true, "orderId": "ord_991" } +``` + +## Step 4: Handle state mismatches + +### Flow is not deployed +If the CLI reports the flow is not deployed (a 404 with a hint like `To deploy it, run: postman flows deploy `): +1. **Explain** that the flow isn't deployed yet, so it can't be triggered. +2. **Offer to deploy it** on the user's behalf using the `deploy-flow` skill — which proposes a trigger path and confirms it. +3. Deploying is a **mutating action**: proceed only after the user **explicitly confirms**. If they decline, do nothing further. +4. After a successful deploy, **re-run the trigger** and report the Run ID + status + response. + +### Trigger is disabled +If the CLI reports the trigger/target is disabled: +1. Explain the trigger is currently off. +2. Offer to enable it — a state change requiring **explicit confirmation**: + ```bash + POSTMAN_CLI_SOURCE=claude-code-plugin postman flows update --trigger on + ``` +3. After enabling (only on confirmation), trigger the flow. + +## Step 5: Handle a failing response + +If the trigger returns a **non-2xx** status, surface the **status and response body**, then offer to inspect the run: +- Offer to run the `get-flow-run` skill with the Run ID to see the failing block, reason, and status. + +``` +Trigger returned 500. + Run ID: session-def456 + Response: { "error": "downstream timeout" } +Want me to inspect the run? I can pull the per-block detail with get-flow-run for session-def456. +``` + +--- + +Read `references/flows-cli-baseline.md` for CLI prefixing, credential reuse, and error handling rules. + +Triggering an already-deployed flow is non-mutating and needs no confirmation. Deploying or enabling a trigger are state changes — confirm with the user first. diff --git a/skills/trigger-flow/references/flows-cli-baseline.md b/skills/trigger-flow/references/flows-cli-baseline.md new file mode 100644 index 0000000..d4d3f3c --- /dev/null +++ b/skills/trigger-flow/references/flows-cli-baseline.md @@ -0,0 +1,9 @@ +# Flows CLI Baseline + +These rules apply to every Flows CLI skill. + +- Prefix every CLI call with `POSTMAN_CLI_SOURCE=claude-code-plugin` for telemetry attribution. +- Reuse existing `postman login` / API key credentials. Do not trigger a second authentication. +- Surface CLI errors verbatim. Do not assert access the CLI does not grant. +- **CLI not installed:** "Postman CLI is not installed. Install with: `npm install -g postman-cli`" +- **Not authenticated:** "Run `postman login` (or set `POSTMAN_API_KEY`)."