Postman CLI for coding agents

When a coding agent changes an API or its client code, it needs a way to check that requests and responses still match expected behavior. Postman CLI runs Postman collections from a terminal or CI pipeline. A collection is a saved set of API requests and tests. The agent can run a collection in the repository and check whether its tests pass.

The CLI also has commands for Postman tasks that coding agents can use, and it can produce output that agents can read. An agent can use it to check whether an API contract still holds after a code change. A local collection file does not require a Postman API key; cloud resources do. Collection runs send requests to the configured API, so check the target environment before running tests that could change data.

Install and prepare the project

The official Postman CLI overview documents installation methods, including npm. With npm installed, install the CLI globally:

npm install -g postman-cli

In a repository that uses Postman, postman init sets up an AI-ready API project and installs agent skills. Review the changes it makes before committing them. Postman documents this initialization alongside its agent and CI instructions.

The CLI also provides postman describe, postman context-graph ask, and postman skills for coding agents. Use the official documentation for their current arguments and behavior; do not assume they replace a collection run.

Run a local collection

Ask an agent to run the API regression collection after it changes a client or service. The collection checks existing requests and tests for behavior changes. Replace the placeholder path below with a collection file that already exists in the repository:

postman collection run ./path/to/collection.json --json

The path is a placeholder for a collection file in your repository. The command runs the local collection and requests JSON output, which an agent can parse. The CLI also reports success or failure with an exit code. Most commands return 0 for success and a nonzero code for failure, though some commands use more specific codes. Check both the JSON output and the exit status when deciding whether to report a passing run. Postman documents the collection and output options.

The collection file stays on the machine, but its requests go to the hosts configured in the collection or its environment. A test that creates, updates, or deletes records affects the target API. Before running the command, inspect the collection and confirm its base URL points to a test service if the requests can write data.

Choose local or cloud authentication

You can run a local collection file without signing in. A collection or other resource stored in Postman’s cloud requires an API key. For scripts and CI jobs that cannot answer prompts, Postman documents authentication through postman login --with-api-key, the --api-key or --postman-api-key options, and the POSTMAN_API_KEY environment variable in its agent and CI guidance.

Keep the key in a shell environment or a CI secret, not in an agent prompt, source file, or command recorded in repository history. If an agent only needs to test a checked-in collection, use the local file and avoid granting it cloud access.

Use the result in an agent task

After making a change, a coding agent can run the collection and use the results to find requests or tests that failed. For example, give the agent a task like this:

Run ./path/to/collection.json with Postman CLI. Do not change the collection or contact production. Report the command’s exit status and any failed tests. If the collection targets production or includes write requests, stop and ask before running it.

The CLI supports machine-readable --json output and an option to disable event reporting, --no-report-events. Some commands require a particular Postman plan. If a command is missing or a cloud feature is unavailable, the account may lack access; that does not mean a test failed. Check the plan requirements in the CLI overview.