CLI

CLI options

Every Portman CLI flag, with aliases, types and defaults, plus common command examples for converting specs and running tests.

The Portman CLI takes an OpenAPI document as input (-u for a URL or -l for a local file) and accepts flags that control conversion, test generation, output, Postman upload and Newman runs. All of these flags can also be stored in a CLI options file.

Usage

bash

portman -u <url> -l <local> -b <baseUrl> -t <includeTests>

All options

Option	Alias	Type	Description
`--help`		boolean	Show help.
`--version`		boolean	Show version number.
`--url`	`-u`	string	URL of the OpenAPI spec to port to a Postman collection.
`--local`	`-l`	string	Use a local OpenAPI spec to port to a Postman collection.
`--baseUrl`	`-b`	string	Override the spec's base URL to use in Postman.
`--output`	`-o`	string	Write the Postman collection to an output file.
`--oaOutput`		string	Write the (filtered) OpenAPI file to an output file.
`--runNewman`	`-n`	boolean	Run Newman on the newly created collection.
`--newmanRunOptions`		string	JSON stringified object with options for configuring Newman.
`--newmanOptionsFile`		string	Path or URL to a Newman options file.
`--newmanIterationData`	`-d`	string	Iteration data to run Newman with the newly created collection.
`--localPostman`		string	Use a local Postman collection, skipping the OpenAPI conversion.
`--syncPostman`		boolean	Upload the generated collection to Postman. Default: `false`.
`--syncPostmanCollectionIds`		boolean	Synchronise the IDs of newly created Postman collections with those already on Postman, useful for Postman pull requests. Default: `false`.
`--postmanFastSync`		boolean	Postman sync creates a new collection (new UID) instead of updating. Default: `false`.
`--postmanRefreshCache`		boolean	Postman sync refreshes all locally cached Postman API data. Default: `false`.
`--postmanUid`	`-p`	string	Postman collection UID to upload the generated collection to.
`--postmanWorkspaceName`		string	Postman workspace name to target for the upload.
`--includeTests`	`-t`	boolean	Inject the Portman test suite. Default: `true`.
`--bundleContractTests`		boolean	Bundle Portman contract tests in a separate folder in Postman. Default: `false`.
`--portmanConfigFile`	`-c`	string	Path or URL to the Portman config file (`portman-config.json`).
`--postmanConfigFile`	`-s`	string	Path to the openapi-to-postman config file (`postman-config.json`).
`--filterFile`		string	Path or URL to the openapi-format filter file (`oas-format-filter.json`).
`--envFile`		string	Path to the `.env` file to inject environment variables.
`--collectionName`		string	Overwrite the OpenAPI title to set the Postman collection name.
`--cliOptionsFile`		string	Path or URL to a Portman CLI options file.
`--ignoreCircularRefs`		boolean	Ignore circular references in the OpenAPI spec. Default: `false`.
`--logAssignVariables`		boolean	Toggle logging of assigned variables. Default: `true`.
`--warn` / `--no-warn`		boolean	Toggle warnings for missing `openApiOperationIds`. Default: `true`.
`--init`		string	Configure Portman CLI options interactively.
`--extraUnknownFormats`		array	Add extra unknown formats to JSON schema tests.

Examples

Initialize the Portman CLI configuration interactively:

bash

portman --init

Convert a remotely hosted spec:

bash

portman -u https://specs.apideck.com/crm.yml

Overwrite the base URL in the spec and run Newman:

bash

portman -u https://specs.apideck.com/crm.yml -b http://localhost:3050 -n true

Pass a local data file for Newman to use for iterations:

bash

portman -u https://specs.apideck.com/crm.yml -b http://localhost:3050 -n true -d ./tmp/newman/data/crm.json

Convert a local spec and write the collection to a specific file:

bash

portman -l ./tmp/specs/crm.yml -o ./tmp/specs/crm.postman.json

Skip tests and only generate the collection:

bash

portman -l ./tmp/specs/crm.yml -t false

Filter the OpenAPI document before conversion (see Filtering operations):

bash

portman -u https://specs.apideck.com/crm.yml --filterFile examples/cli-filtering/oas-format-filter.json

Add extra formats to the JSON schema validation. This makes schema validation more lenient and solves problems with unknown formats:

bash

portman -l ./tmp/specs/crm.yml -o ./tmp/specs/crm.postman.json --extraUnknownFormats ulid one two

Pass custom config files, in JSON or YAML:

bash

portman -u https://specs.apideck.com/crm.yml -c ./tmp/crm/portman-config.json -s ./common/postman-config.jsonportman -u https://specs.apideck.com/crm.yml -c ./tmp/crm/portman-config.yaml -s ./common/postman-config.json

Load all options from a file:

bash

portman --cliOptionsFile ./examples/cli-options/portman-cli-options.json

The openapi-to-postman config

The conversion itself is handled by openapi-to-postman. Portman ships a default postman-config.default.json, which is used when you do not pass --postmanConfigFile. If you use a custom Postman config file with Portman 1.28.0 or later, set the parametersResolution option to either "Example" or "Schema". The options requestParametersResolution and exampleParametersResolution are deprecated openapi-to-postman options.

Source: Portman README

Quickstart

CLI options file

CLI options

Usage

All options

Examples

The openapi-to-postman config

Related