ReferencePostman CLICLI commands

API governance commands

View as Markdown

This topic covers API governance commands for the Postman CLI.

API governance is the practice of applying a defined set of standards consistently across the API design and testing phases of your development process. The Postman CLI includes commands that checks your API specifications in Spec Hub against your team’s configured Postman API governance rules.

postman spec lint

This command runs syntax validation and governance rule checks against a single- or multi-file API specification in Spec Hub. Provide the local file path or ID for a specification that’s in OpenAPI (2.0, 3.0, or 3.1) or AsyncAPI (2.x or 3.x) format. If you’re providing the local file path for a multi-file specification, provide the path to the root file.

By default, if you provide a local file path for a specification, the command runs syntax validation and governance checks using the All workspaces governance group. Use the --workspace-id option to run governance checks using the rules from a specific workspace.

Governance checks require signing in to Postman with the postman login command. If you’re not signed in, or the governance rules can’t be retrieved, the command returns syntax validation results and notes that governance rules weren’t applied.

Lint results are reported to Postman by default. Reporting requires that the specification exist in Postman, so linting a standalone local file that isn’t synced to a Postman specification isn’t reported. When you run the command in a CI/CD pipeline, you can view the results in the API Catalog. Click Integrated services, click your service, open the Test tab, find your run in the CI Pipeline Runs table, and click View report. To opt out, pass --report-events=false.

You can find the specification ID in Postman. Click Items icon Items tab, click Specs in the sidebar, and select a specification. Then click the Info icon Specification Info tab in the right sidebar to view or copy the specification ID.

Usage

postman spec lint <spec-file-path|spec-id> [options]
<spec-file-path|spec-id>

The local file path to the API specification or the specification’s unique identifier.

Options

--fail-severity [severity], -f
Defaults to ERROR

Triggers an exit failure code for rule violations at or higher than the specified severity level. The options, in order of lowest to highest severity, are HINT, INFO, WARNING, and ERROR.

--output [output-format], -o

Controls the output format for issues found in an OpenAPI or AsyncAPI specification. Accepts JSON or CSV. Defaults to table view if no output format is specified.

--workspace-id [workspace-id]

Run syntax validation and governance rule checks using the rules from a particular workspace by providing its ID. You can use this option if you provide the local file path for a specification. Learn how to get a workspace’s ID.

--report-events

Lint results are reported to Postman by default, whether or not you pass --report-events. To turn reporting off, pass --report-events=false. You can also use --no-report-events.

Examples

postman spec lint openapi.yaml --workspace-id 987654321-54321ef-4321-1ab2-1ab2-ab1234112a12
postman spec lint 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

Learn more at API governance overview and Use the Postman CLI with GitHub Actions.

Output

You can change the output of governance rule violations to JSON or CSV. If you don’t specify an output, it defaults to table view.

The following is an example of the output in table format (default):

Example output

The following is an example of the output in JSON format:

{
  "violations": [
    {
      "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
      "line number": "13",
      "path": "paths./spacecrafts/{spacecraftIds}.parameters.0",
      "severity": "WARNING",
      "issue": "Parameter \"spacecraftId\" must be used in path \"/spacecrafts/{spacecraftIds}\".",
      "issue type": "Syntax"
    },
    {
      "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
      "line number": "19",
      "path": "paths./spacecrafts/{spacecraftIds}.get",
      "severity": "WARNING",
      "issue": "Operation must define parameter \"{spacecraftIds}\" as expected by path \"/spacecrafts/{spacecraftIds}\".",
      "issue type": "Syntax"
    },
    {
      "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
      "line number": "4",
      "path": "info",
      "severity": "WARNING",
      "issue": "The info object should have a description.",
      "issue type": "Governance"
    },
    {
      "file": "../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml",
      "line number": "21",
      "path": "paths./spacecrafts/{spacecraftIds}.get.responses",
      "severity": "WARNING",
      "issue": "Operation should return a 5xx HTTP status code",
      "issue type": "Governance"
    }
  ]
}

The following is an example of the output in CSV format:

file,line number,path,severity,issue,issue type
../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,13,paths./spacecrafts/{spacecraftIds}.parameters.0,WARNING,"Parameter ""spacecraftId"" must be used in path ""/spacecrafts/{spacecraftIds}"".",Syntax
../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,19,paths./spacecrafts/{spacecraftIds}.get,WARNING,"Operation must define parameter ""{spacecraftIds}"" as expected by path ""/spacecrafts/{spacecraftIds}"".",Syntax
../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,4,info,WARNING,The info object should have a description.,Governance
../../../Desktop/test-collections/spacecraft-api/src/main/resources/openapi.yaml,21,paths./spacecrafts/{spacecraftIds}.get.responses,WARNING,Operation should return a 5xx HTTP status code,Governance

postman spec list

This command lists API specifications in OpenAPI (2.0, 3.0, or 3.1) or AsyncAPI (2.x or 3.x) format. Pass a path to scan for local specification files on disk, or omit it to list the specifications in the linked Postman workspace. Use --workspace to target a specific workspace. The output includes their names, IDs, types, and root files.

Usage

postman spec list [path] [options]
[path]

Path to a local directory to scan for specification files. Omit it to list a workspace’s specifications instead.

Options

-w, --workspace <id>

The ID of the Postman workspace to list specifications from. Defaults to the workspace linked in your .postman/resources.yaml file.

--api-key <key>

Your Postman API key. If omitted, the command uses the POSTMAN_API_KEY environment variable or your postman login session.

--json

Prints the results as JSON for machine-readable output.

Examples

postman spec list ./specs
postman spec list --workspace 12345678-90ab-cdef-1234-567890abcdef

postman spec get

This command reads a specification’s full definition by ID or local file path, including every file in a multi-file specification. It prints a summary of the specification, including its name, type, file count, and root file. It also lists each file the specification contains, showing its path, type (root or supporting file), size, and content.

Usage

postman spec get <spec...> [options]
<spec...>

The ID or local file path of one or more specifications to read.

Options

--api-key <key>

Your Postman API key. If omitted, the command uses the POSTMAN_API_KEY environment variable or your postman login session.

--json

Prints the full specification definition, including file contents, as JSON for machine-readable output.

Examples

postman spec get ./openapi.yaml
postman spec get 12345678-90ab-cdef-1234-567890abcdef

postman spec create

This command creates an API specification. With a path, it scaffolds a minimal specification file on disk, which doesn’t require signing in. Without a path, it creates the specification in your Postman workspace, which requires signing in with the postman login command or an --api-key. It supports OpenAPI, AsyncAPI, GraphQL, protobuf, and Smithy formats. For OpenAPI and AsyncAPI, use --format to choose YAML or JSON.

Usage

postman spec create [path] [options]
[path]

The path to write a local specification file to. Omit it to create the specification in a Postman workspace instead.

Options

-n, --name <name>
Required

The specification’s name or title.

-t, --type <type>
Defaults to openapi

The specification type. Accepts openapi, asyncapi, graphql, protobuf, or smithy.

--spec-version <version>

The specification version, for example 3.1 for OpenAPI or 3 for protobuf.

-f, --format <format>
Defaults to yaml

The file format, yaml or json. Applies to OpenAPI and AsyncAPI only.

-w, --workspace <id>

The workspace to create the specification in when you omit the path. Defaults to the workspace linked in your .postman/resources.yaml file. If no workspace is linked there, you must provide one with --workspace.

--force

Overwrites an existing local file. By default, if a file already exists at the path, the command stops without overwriting it.

--api-key <key>

Your Postman API key. If omitted, the command uses the POSTMAN_API_KEY environment variable or your postman login session.

Examples

postman spec create --name "Pet Store"
postman spec create ./postman/specs/pet-store/index.yaml --name "Pet Store"
postman spec create ./api.yaml --name "Events" --type asyncapi

postman spec file add

This command adds a new file to a multi-file specification. Identify the specification by its ID in your Postman workspace or by the path to its local directory, then give the path of the file to add within the specification. Provide the file’s content with --content, or pipe it through standard input.

Usage

postman spec file add <spec> <filePath> [options]
<spec>

The specification to add the file to, identified by its ID in your Postman workspace or by the path to its local directory.

<filePath>

The path of the file to add, relative to the specification’s root.

Options

-c, --content <content>

The file’s content. If omitted, the command reads the content from standard input.

--api-key <key>

Your Postman API key. If omitted, the command uses the POSTMAN_API_KEY environment variable or your postman login session.

Examples

postman spec file add 12345678-90ab-cdef-1234-567890abcdef schemas/user.yaml --content "type: object"
postman spec file add ./postman/specs/api schemas/user.yaml --content "type: object"

postman spec file update

This command updates an existing file in a multi-file specification. Identify the specification by its ID in your Postman workspace or by the path to its local directory, then give the path of the file to update. Provide the new content with --content, or pipe it through standard input.

Usage

postman spec file update <spec> <filePath> [options]
<spec>

The specification that contains the file, identified by its ID in your Postman workspace or by the path to its local directory.

<filePath>

The path of the file to update, relative to the specification’s root.

Options

-c, --content <content>

The new file content. If omitted, the command reads the content from standard input.

--api-key <key>

Your Postman API key. If omitted, the command uses the POSTMAN_API_KEY environment variable or your postman login session.

Examples

postman spec file update 12345678-90ab-cdef-1234-567890abcdef index.yaml --content "openapi: 3.1.0"
postman spec file update ./postman/specs/api schemas/user.yaml --content "type: object"

postman spec file rm

This command removes a file from a multi-file specification. Identify the specification by its ID in your Postman workspace or by the path to its local directory, then give the path of the file to remove. The command prompts for confirmation unless you pass --yes.

Usage

postman spec file rm <spec> <filePath> [options]
<spec>

The specification that contains the file, identified by its ID in your Postman workspace or by the path to its local directory.

<filePath>

The path of the file to remove, relative to the specification’s root.

Options

-y, --yes

Skips the confirmation prompt.

--api-key <key>

Your Postman API key. If omitted, the command uses the POSTMAN_API_KEY environment variable or your postman login session.

Examples

postman spec file rm 12345678-90ab-cdef-1234-567890abcdef schemas/user.yaml --yes
postman spec file rm ./postman/specs/api schemas/user.yaml --yes

postman spec generate collection

Generates a collection from an OpenAPI specification. Pass a local file path to generate the collection on disk in your local project, or a specification ID to generate it in the Postman Cloud. By default, the command groups requests into folders by the specification’s paths. Use --folder-strategy Tags to group them by tags instead.

Usage

postman spec generate collection <spec> [options]
<spec>

The OpenAPI specification to generate a collection from, as a local file path or a specification ID.

Options

-n, --name <name>
Required

A name for the generated collection.

--folder-strategy <strategy>
Defaults to Paths

How to group requests into folders. Accepts Paths to group by the specification’s paths, or Tags to group by operation tags.

--api-key <key>

Your Postman API key. If omitted, the command uses the POSTMAN_API_KEY environment variable or your postman login session.

Examples

postman spec generate collection ./openapi.yaml --name "My API"
postman spec generate collection ./openapi.yaml --name "My API" --folder-strategy Tags
postman spec generate collection 12345678-90ab-cdef-1234-567890abcdef --name "My API"

postman api lint

The postman api lint command is only supported for API Builder objects in Postman v11. The Postman API Builder isn’t supported in Postman v12 and later. Learn about using the API Builder in Postman v11 and earlier.

This command runs validation checks for governance rules against the API specification provided in the Postman config file, a local file, or a UUID. The api lint command shows a warning if it’s unable to find the API ID to send data back to Postman.

This command supports APIs in the Postman API Builder that aren’t linked to Git.

To use this command, sign in to Postman with the postman login command.

Usage

postman api lint <definition-file|api-uuid> [options]
<definition-file|api-uuid>

The API definition file path or API UUID to lint.

Options

--integration-id [integration-id]

Specifies the integration ID for the report.

--fail-severity [severity], -f
Defaults to ERROR

Triggers an exit failure code for rule violations at or higher than the specified severity level. The options, in order of lowest to highest severity, are HINT, INFO, WARN, and ERROR.

--suppress-exit-code, -x

Specifies whether to override the default exit code for the current run.

Examples

postman api lint my-definition-file.json
postman api lint 12345678-12345ab-1234-1ab2-1ab2-ab1234112a12

Learn more at API governance overview.