Skip to navigation
Postman CLISetup and account

Postman CLI basic commands

View as Markdown

This topic covers basic Postman CLI commands for getting help, version information, and updating the CLI.

postman

The base command of the Postman CLI is postman. Run this command with the syntax and options detailed below.

Usage

postman [options]

Options

--color <value>
'auto' | 'on' | 'off'Defaults to auto

Controls colored output in the terminal. Accepts auto, on, or off. With auto, the Postman CLI attempts to turn colored output on or off based on the terminal’s color support.

--help, -h

Returns information about Postman CLI commands and options.

--silent

Silences all terminal output.

--version, -v

Returns the version number for the Postman CLI.

You can run the man postman command to return a manual page with the Postman CLI commands and options.

Examples

postman --help
postman -v

postman update

Updates the Postman CLI to the latest version using the method you installed it with, such as npm, Homebrew, or the install script. Run it after a new release to upgrade in place. To check whether an update is available without installing it, pass --check.

After a successful update, the command checks the postman/skills folder in the current directory and updates any agent skills that are behind.

The Postman CLI also runs an automatic update check that reports when the agent skills in postman/skills are behind. The check runs at most once every 24 hours, and setting the POSTMAN_CLI_SKIP_UPDATE_CHECK environment variable to 1 turns off both the skills check and the version check.

Usage

postman update [options]

Options

--check

Checks whether a newer version of the Postman CLI is available, without installing it. If an update is available, the command tells you to run postman update. Otherwise, it reports that you’re running the latest version. The command also reports whether the folder’s agent skills are behind, without updating them.

postman status

Shows the Postman CLI version, whether a folder contains Postman resources, the account or session the CLI is using, the state of the folder’s agent skills, and which coding agents have the Postman plugin installed. The command is read-only and doesn’t require you to sign in.

Usage

postman status [dir-path] [options]
[dir-path]

The folder to check. Defaults to the current directory. The command doesn’t search parent folders.

Options

--json

Prints the status as JSON with the version, initialized, auth, skills, and agentPlugins fields.

Output

  • Postman resources — Reports whether the folder contains both a .postman folder and a postman folder. If it doesn’t, run postman init.
  • Authentication — Reports the same account, temporary-session, or signed-out details as postman whoami. When the POSTMAN_API_KEY environment variable is set, the command reports that the CLI is using it. The command doesn’t print or validate the key.
  • Skills — Reports current, behind, or unknown, with the same guidance as postman skills status. The command checks the published skills even if the folder isn’t initialized. It makes one request that doesn’t require authentication. Set POSTMAN_SKILLS_URL to change where it checks, and POSTMAN_SKILLS_TIMEOUT_MS to change the five-second time limit.
  • Agent plugins — Lists each detected coding agent and whether the Postman plugin is installed, not installed, or can’t be determined. In --json output, agentPlugins.agents maps each agent to installed, not_installed, agent_not_found, or unknown, and agentPlugins.installCommand holds the command that installs the plugins, npx @postman/postman-plugin. The command checks each agent, and checks your system’s configuration, not the folder’s. The command respects the CODEX_HOME and CLAUDE_CONFIG_DIR environment variables.

Exit codes

  • 0 — The check completed, including when skills are behind.
  • 1 — The command couldn’t read the status, or couldn’t reach the skills repository.
  • 2 — The path isn’t an existing folder.

Examples

postman status
postman status ./services/api --json

postman feedback

Submits feedback about the Postman CLI, such as usability issues, gaps, and improvement suggestions. You, or an AI agent, pass the feedback as text, which gives a structured way to send it from the command line.

Usage

postman feedback <text> [options]
<text>

The feedback to submit.

Options

--type <type>
'general' | 'cli_gap' | 'improvement_suggestion' | 'bug_report' | 'feature_request'Defaults to general

The kind of feedback you’re submitting.

--context <context>

The command or feature the feedback is about.

--json

Prints the result as JSON for machine-readable output.

Examples

postman feedback "The performance run output is hard to read when piped"
postman feedback "Add a dry-run flag to workspace push" --type feature_request --context "workspace push"