Postman CLI context-graph commands `(postman context-graph)`

This topic covers the postman context-graph commands for the Postman CLI.

Your team’s Context Graph is Postman’s map of your team’s APIs and the dependencies between them. Use the postman context-graph commands to ask it natural-language questions, such as what depends on a given API, and to onboard GitHub repos and Postman workspaces into it. The team a query runs against is derived from your credentials, so there’s no workspace or team option.

These commands require authentication. Sign in with the postman login command, or pass a Postman API key with --api-key.

`postman context-graph ask`

Submits a natural-language question about your team’s Context Graph and returns an ask ID, which you check later with postman context-graph status. Use --wait to block until the answer arrives and print it. This is usually how you’ll want to run it, whether manually or using automation. Omit --wait only if you want to submit several asks without waiting, or need to poll on your own schedule. If an ask happens to finish before this command returns, it prints the answer instead of an ID.

Usage

postman context-graph ask <query> [options]

<query>

The natural-language question to ask about your team’s Context Graph.

Options

--wait

Waits for the answer and prints it inline, instead of returning an ask ID.

--no-include-answer

Returns the ask record without including the answer inline.

--interval <seconds>

Defaults to 2

How often to poll for the answer, in seconds. Accepts a value from 0.5 to 3600. Requires --wait.

--timeout <seconds>

Defaults to 300

How long to wait for the answer before giving up, in seconds, up to 86400 (24 hours). Requires --wait. If the wait times out, the ask keeps running in Postman, and you can check it later with postman context-graph status.

--json

Prints the ask record as JSON for machine-readable output, instead of a table.

--api-key <key>

Authenticates with a Postman API key instead of your postman login session. Falls back to the POSTMAN_API_KEY environment variable.

Examples

postman context-graph ask "What depends on billing-api?" --wait
postman context-graph ask "Which APIs are in the graph?"
postman context-graph ask "What depends on billing-api?" --wait --interval 5 --timeout 120

Exit codes

Code	Meaning
`0`	The ask completed, or was accepted without `--wait`.
`1`	A request or CLI error, such as an authentication failure, a network error, or an invalid option value.
`2`	The ask reached a failed state.
`4`	The `--wait` timeout elapsed before the ask finished. The ask keeps running, so you can check it later with `postman context-graph status`.

`postman context-graph status`

Checks on an ask submitted with postman context-graph ask, without waiting. Provide the ask ID that ask returned. If the ask has finished, it prints the answer. Otherwise, it reports that the ask is still in progress.

Usage

postman context-graph status <askId> [options]

<askId>

The ID of the ask to check, returned by postman context-graph ask.

Options

--json

Prints the ask record as JSON for machine-readable output, instead of a table.

--api-key <key>

Authenticates with a Postman API key instead of your postman login session. Falls back to the POSTMAN_API_KEY environment variable.

Examples

postman context-graph status 12345678-90ab-cdef-1234-567890abcdef

Exit codes

Code	Meaning
`0`	The ask completed.
`1`	A request or CLI error, such as an authentication failure, a network error, or an unknown ask ID.
`2`	The ask reached a failed state.
`3`	The ask is still in progress.

`postman context-graph ingest`

These commands add GitHub repos and Postman workspaces into your team’s Context Graph and check ingestion progress. Use ingest git to index a repo’s code and ingest workspaces to index a workspace’s specs, collections, and environments. To cover both for a Git-linked workspace, run both commands. The --all-git-linked-workspaces option of ingest git only discovers the linked repos and never ingests the workspace itself.

The commands return once each ingestion has started. Use postman context-graph ingest status to check progress. Re-running a command for a repo or workspace reuses its source and starts a fresh ingestion.

`postman context-graph ingest git`

This command adds GitHub repos into your team’s Context Graph by indexing each repo’s code. The team is derived from your credentials.

Usage

postman context-graph ingest git [repoUrls...] [options]

[repoUrls...]

One or more GitHub repo URLs, in HTTPS or git@ SSH form, up to 500 per call. Optional when you pass --all-git-linked-workspaces.

Options

--all-git-linked-workspaces

Also adds the repo linked to every Git-linked workspace in your team.

--tag <tag>

Limits --all-git-linked-workspaces to workspaces with this tag. Repeat the option to pass up to 5 tags. A workspace must match all of them.

--ttl <seconds>

Overrides the service’s default TTL, in seconds.

--json

Prints the onboarding response as JSON.

--api-key <key>

Authenticates with a Postman API key instead of your postman login session. Falls back to the POSTMAN_API_KEY environment variable.

Example

postman context-graph ingest git https://github.com/acme/billing-api

Exit codes

Code	Meaning
`0`	Every ingestion started.
`1`	The request failed, such as an authentication failure, a network error, or malformed input.
`4`	Partial success. Some repos were skipped or failed to start.

`postman context-graph ingest workspaces`

This command adds Postman workspaces into your team’s Context Graph by indexing each workspace’s specs, collections, and environments. It doesn’t index the code of a linked repo. Use postman context-graph ingest git for that. Without --workspace, it adds your team’s Git-linked workspaces.

Usage

postman context-graph ingest workspaces [options]

Options

-w, --workspace <id>

The ID of a workspace to onboard. Repeat the option to onboard more than one workspace.

--top <n>

Caps how many workspaces this call adds.

--ttl <seconds>

Overrides the service’s default TTL, in seconds.

--json

Prints the onboarding response as JSON.

--api-key <key>

Authenticates with a Postman API key instead of your postman login session. Falls back to the POSTMAN_API_KEY environment variable.

Examples

postman context-graph ingest workspaces
postman context-graph ingest workspaces --workspace 1f0df51a-8658-4ee8-a2a1-d2567dfa09a9

Exit codes

Code	Meaning
`0`	Every ingestion started.
`1`	The request failed, such as an authentication failure, a network error, or malformed input.
`4`	Partial success. Some workspaces failed to start.

`postman context-graph ingest status`

This command checks ingestion progress for your team, or for one source. Without --source, it prints a team-wide summary by each source’s latest job status. It doesn’t wait for ingestion to finish.

Usage

postman context-graph ingest status [options]

Options

--source <sourceId>

Shows the jobs for one source, by the source ID that ingest git or ingest workspaces printed.

--json

Prints the service response as JSON.

--api-key <key>

Authenticates with a Postman API key instead of your postman login session. Falls back to the POSTMAN_API_KEY environment variable.

Examples

postman context-graph ingest status
postman context-graph ingest status --source <sourceId>

Exit codes

Code	Meaning
`0`	The status was fetched.
`1`	The request failed, such as an authentication failure, a network error, or malformed input.