Postman CLI 実践コマンドガイド

Posted at 2026-04-08

はじめに

これは、Postmanの公式のコマンドラインツールであるPostman CLIの使い方について、著者が重要と判断したポイントを厳選してまとめたドキュメントです。Postman CLIはコレクションの実行、ワークスペース管理、OpenAPI SpecのLint、モックサーバーの起動、モニターの実行、パフォーマンステストなど、さまざまなPostmanの機能をコマンドラインから利用できます。

Newmanとの違い

コマンドラインツールには他にもNewman というOSSのツールがあります。Postman CLI と Newman はどちらもコレクションを実行できるツールですが、Postmanの機能をフルに活用するには Postman CLI の使用を推奨します。主な違いは以下のとおりです。

機能	Postman CLI	Newman
メンテナンス	Postman が管理・提供	コミュニティ主導 (ソースはGitHubで公開)
Node.jsライブラリとして利用可能 (＊1)	なし	あり
Postmanへのlogin/logout サポート	あり	なし
パッケージサポート(＊2)	あり	なし
レポーティング	ビルトインのReporter を選択可能。Postmanログイン時はPostman Cloudに結果送信	Reporterプラグインで選択可。ただしPostman Cloudへの送信はなし
ガバナンスチェック(＊3)	あり	なし
マルチプロトコルAPIリクエストサポート(＊4)	あり	なし

(＊1) - Postman CLIはNode.jsのライブラリとしても利用可能で、JavaScriptコードから直接コレクションの実行機能を呼び出せる。
(＊2) - Postmanスクリプトやテストで利用可能なパッケージライブラリ。よく使用するスクリプトやテストを共通モジュールとしてパッケージ化し、チーム内で再利用できる。共通のユーティリティ関数やテストロジックをパッケージ化して管理できるため、スクリプトの保守性が向上する。
(＊3) - ガバナンスチェック機能。Postman Cloudに設定されたルール（セキュリティ、命名規則など）に基づいて、OpenAPI Specの静的チェックを行う機能。一般的、もしくは自社固有のAPI設計ガイドラインに沿っているかを自動検証できる。
(＊4) - HTTP以外のプロトコル（gRPC、WebSocket、GraphQLなど）を使用したAPIリクエストのサポート

Quick Reference

この記事で取り扱うコマンドの一覧です。

カテゴリ	コマンド	概要
インストール	`npm install -g postman-cli@latest`	最新版をインストール
Login/Logout	`postman login`	ブラウザ経由でサインイン
	`postman login --with-api-key <key>`	APIキーで認証（CI推奨）
	`postman logout`	サインアウト
ワークスペース	`postman workspace prepare`	ローカルのコレクション・環境を検証
	`postman workspace push`	Postman Cloudへ同期
コレクション	`postman collection run <collection-id\|path>`	コレクションを実行
	`postman collection run <collection-id\|path> -i <folder-id\|name>`	フォルダーを指定して実行
	`postman collection run <collection-id\|path> -e <env>`	環境を指定して実行
	`postman collection run <collection-id\|path> --env-var "key=value"`	環境変数を指定・上書きして実行
	`postman collection run <collection-id\|path> -d <csv or json>`	データファイルを指定して実行
	`postman collection run <collection-id\|path> --bail`	テスト失敗時に即終了
	`postman collection run <collection-id\|path> -r json,junit`	レポーター指定
APIリクエスト	`postman request run <request>`	単一リクエストを実行
Spec Lint	`postman spec lint <spec-id\|path>`	OpenAPI Specのガバナンスチェック
モックサーバー	`postman mock run <manifestPath>`	ローカルモックサーバーを起動
モニター	`postman monitor run <monitor-id>`	クラウドモニターをオンデマンド実行
パフォーマンス	`postman performance run <collection-id>`	パフォーマンステストを実行

CLIインストール

以下、npm経由でのインストール手順です。npm経由以外の方法でインストールする場合はこちらのページを参照ください。
最新バージョンの使用をオススメします。

npm install -g postman-cli@latest

# アンインストール
npm uninstall -g postman-cli

# バージョン確認
postman --version
# 1.33.5

最新版の確認方法

Release Notes: https://www.postman.com/release-notes/postman-cli/
npm: https://www.npmjs.com/package/postman-cli

トラブルシューティング

npm経由とそれ以外の方法でインストールされたバイナリが存在しないか確認する。すでにcurlスクリプトでバイナリをインストールしている場合は、そのバイナリをパスから除去すること

Login / Logout

Postman Cloudへのログインに必要な認証を行います。ブラウザ経由またはAPIキーで認証できます。CI/CDパイプラインで実行する場合は --with-api-key を使用してください。

# ブラウザ経由でサインイン
postman login

# APIキーで認証（CI/CDパイプラインでの実行時に推奨）
postman login --with-api-key PMAK-xxxxxxxxxxxxxxxx

# ログアウト
postman logout

[参考] 一度ログインすると、logout コマンドを実行するか、Postman API Key が expire するまでサインイン状態が維持されます。

認証情報は ~/.postman/postmanrc に保存されます：
{
  "login": {
    "_profiles": [
      {
        "alias": "default",
        "postmanApiKey": "PMAK-xxxx-xxxx",
        "username": "your-username"
      }
    ]
  }
}

ワークスペースへの同期

ローカルのコレクション・環境ファイルを検証し、Postman Cloudへ同期するためのコマンドです。このコマンドはネイティブGit連携が有効なワークスペースで使用します。つまり、コレクションや環境といったPostmanの成果物をGitレポジトリで管理する開発ワークフローにおいて、Gitで管理しているPostmanの成果物をPostman Cloudのワークスペースに反映させるために使用します。

# ローカルのコレクション・環境を検証（JSON構造チェック、参照解決、問題検出）
postman workspace prepare

# Postman Cloud へ同期
postman workspace push

# Postman Cloud へ同期の際の確認プロンプトをスキップ（CI向け）
postman workspace push -y

ネイティブGit連携については以下の記事が参照になります。

カスタムディレクトリの指定

ネイティブGit連携において、ローカルファイルシステム上では、コレクションや環境はデフォルトでそれぞれ以下のディレクトリに配置されます。

postman/collections
postman/environments

もし、コレクションや環境がデフォルトのディレクトリにない場合は、それぞれ--collections-dir、--environments-dir でディレクトリを指定できます。

たとえば、モノレポシナリオでは、1つのリポジトリに複数のコレクションが配置される可能性があります。そういった場合は、これらのパラメーターで直接配置ディレクトリを指定することで、指定のディレクトリにあるコレクションや環境をPostman Cloudに同期させることができます。

postman workspace push \
  --collections-dir ./custom/path/collections \
  --environments-dir ./custom/path/environments

コレクションの実行

コレクションに含まれるリクエストとテストスクリプトを順番に実行します。ローカルのパスまたはIDで指定できます。

postman collection run <collection-id|path> [options]

# コレクションのパスを指定 (ネイティブGit連携でのローカルファイル)
postman collection run postman/collections/Poll-API

# コレクションIDを指定（Postmanログインが必要）
postman collection run 27917608-75641c1e-a185-4e90-a693-ec0eefef9efe

# コレクション内の特定フォルダーのみ実行。フォルダーIDまたは名前で指定可能
postman collection run <collection-(id|path)> -i <folder-id|name>

出力例: コレクションIDを指定して実行

環境変数の活用

コレクションの実行時に、環境を指定して変数を切り替えることができます。ローカルの環境のパスまたはIDで指定できます。また、--env-varオプションで個別の変数だけをオーバーライドできます。

# 環境ファイル指定（--environment または -e）。値はIDまたはパス
postman collection run <collection-(id|path)> -e <env-id|path>

# 変数を個別指定して上書き（複数ある場合は --env-var を繰り返す）
postman collection run <collection-(id|path)> --env-var "key=value" [--env-var "key=value"]

実行例

# ローカル環境でコレクションのパス指定で実行
postman collection run ./postman/collections/Poll-API \
  -e ./postman/environments/local.environment.yaml

# ID指定で実行（Postmanログインが必要）
postman collection run 27917608-75641c1e-a185-4e90-a693-ec0eefef9efe \
  -e 27917608-824bfa99-018d-400b-952a-79cc9022703e

特定のキーだけオーバーライドする場合

# 環境の特定変数 (キー名: test) の値だけオーバーライド
postman collection run ./postman/collections/Poll-API \
  -e ./postman/environments/local.environment.yaml \
  --env-var "test=hoge-test"

# 環境指定なしで、--env-varで全ての変数の値を指定することも可能
postman collection run ./postman/collections/Poll-API \
  -e ./postman/environments/local.environment.yaml \
  --env-var "baseUrl=http://localhost:3000" \
  --env-var "test=hoge-test"

[ローカルディレクトリにおけるコレクション・環境の実体]

コレクションディレクトリ: postman/collections/<collection-name>
コレクション配下のAPIリクエスト: postman/collections/<collection-name>/<request-name>.request.yaml
環境ファイル: postman/environments/<env-name>.environment.yaml

データファイル指定（データ駆動テスト）

JSON または CSV ファイルを使い、複数のデータセットで同じリクエストを繰り返し実行できます。テストのパラメーターを変えて実行したい場合などに便利です。

# -d, --iteration-data <path>: JSON または CSV ファイルを指定
postman collection run <collection-(id|path)> -d <data-file-path>

実行例

コレクション内のリクエストで、{{username}} と {{password}} という変数を使用しているとします。これらの変数に対して、複数のユーザーデータをJSONファイルで指定して実行する例です。

# test-data.json の内容
cat test-data.json

[
  {
    "username": "dummyuser1",
    "password": "pass1"
  },
  {
    "username": "dummyuser2",
    "password": "pass2"
  },
  {
    "username": "dummyuser3",
    "password": "pass3"
  }
]

# CSVファイルを指定して実行
postman collection run 27917608-75641c1e-a185-4e90-a693-ec0eefef9efe \
  -d test-data.json

テスト失敗時の挙動制御

テストが失敗した時点でコレクション実行を即座に停止したい時に--bailオプションを使用します。デバッグ時やCIで早期に失敗を検知したい場合に有効です。

# テスト失敗で即終了（--bail）
postman collection run <collection-(id|path)> --bail

Exit Codeと`--suppress-exit-code`オプション

コレクション実行コマンドのExit Codeです。CI/CDパイプラインでの後続処理のハンドリングに使います。

Exit Code	意味
`0`	成功
非ゼロ（通常 `1`）	失敗

失敗となるケース：

テストスクリプトが失敗した場合
リクエストでエラーが発生した場合
コレクション実行が中断された場合

ちなみに、通常、postman collection run が失敗（exit code 0以外）すると、CIのワークフローは中断されますが、--suppress-exit-code オプションを使用することで、失敗してもexit codeを0にしてワークフローを継続させることができます。

postman collection run <collection-(id|path)> --suppress-exit-code

レポーターの設定

--reporters または -r でレポーターを指定できます。ビルトインで cli, json, junit, html をサポートしています。

# 特に--reportersを指定しないと、デフォルトのcliレポーターで実行される
postman collection run 27917608-75641c1e-a185-4e90-a693-ec0eefef9efe

# レポーターにjson を指定し、json結果をファイルに出力
postman collection run 27917608-75641c1e-a185-4e90-a693-ec0eefef9efe \
  --reporters json \
  --reporter-json-export results.json

cli: コマンドラインに実行結果を出力 (default)
json: JSON形式で実行結果を出力（--reporter-json-export でファイル出力も可能）
junit: JUnit XML形式で実行結果を出力（--reporter-junit-export でファイル出力も可能）
html: HTML形式で実行結果を出力（--reporter-html-export でファイル出力も可能）

注意: コレクション v3（マルチプロトコルコレクション）の場合、-r は cli のみをサポートします。ネイティブGit連携でのローカル実行ではコレクションフォーマットはv3になるため、cli のみ利用可能です。

APIリクエストの実行

postman requestで、コレクション全体の実行ではなく、単一のリクエストを実行できます。HTTPメソッド、URL、リクエストボディなどを指定して特定エンドポイントの動作確認やデバッグができます。

postman request [METHOD] <URL> [Options]

実行例

# HTTP メソッドを明示した GET リクエスト (GETはデフォルトなので、METHODを省略しても同じ)
postman request GET https://api.example.com/users

# JSON ボディを指定した POST リクエスト
postman request POST https://api.example.com/users \
  --body '{"name":"Alice","email":"alice@example.com"}'

# ファイルからリクエストボディを読み込む PUT リクエスト
postman request PUT https://api.example.com/users/123 \
  --body @user-data.json

他にも、postman request コマンドは、認証やヘッダーの設定、ヘッダー指定とフォーム送信、Postmanスクリプトの活用、リトライとタイムアウトの制御など、さまざまなオプションをサポートしています。

詳細は以下の記事で紹介しているので、そちらを参照ください。

Specの検証（Lint）

Postmanに設定されたチームのガバナンスルール（セキュリティ・命名規則など）に基づき、OpenAPI Specを静的チェックします。Spec Hubに登録されたSpecや、ローカルのOpenAPI Specファイルを指定できます。CIに組み込むことで、仕様違反を早期検知できます。

postman spec lint <spec-id|path>

実行例

# Spec ID指定で実行 (Postmanログインが必要)
postman spec lint 28f9cda0-ac40-4c34-9761-cd2a30bef4cc

# ローカルのOpenAPI Specファイルを指定
postman spec lint ./postman/specs/openapi.yaml

出力例: ローカルOpenAPI Specファイルを指定して実行し、Warningレベルのガイドライン違反が検出

ちなみにPostmanアプリで、Spec Hubに登録されたSpecを開いたときに、ガバナンスルール違反があると、以下のように警告が表示されます。

より細かな制御

Spec lintの実行時に、失敗とみなすエラーレベルや出力形式を調整できます。

# ERRORのみ失敗とする（Warningは無視）
# --fail-severity <level>: ERROR / WARNING / INFO / HINT（デフォルト: ERROR）
postman spec lint ./postman/specs/openapi.yaml --fail-severity ERROR

# 出力形式を指定（json または csv）
postman spec lint ./postman/specs/openapi.yaml -o json

モックサーバーの起動 (ローカルモック)

ネイティブGit連携を使用している場合は、ローカル環境にモックサーバーを設定できます。モックサーバーを使うことで、テストや開発においてAPIの動作をシミュレートできるため、外部サービスの不安定さや開発中のAPIの未完成による影響を受けずにテストを実行できます。

postman mock runコマンドで、ローカルに設定するモックサーバーを起動できます。このとき、モックサーバーのポート番号、名前、スクリプトなどの情報を含むManifestファイル（JSON形式）を指定して起動します。

# ローカルモックサーバー起動
# <manifestPath>: Manifestファイル (.json)
postman mock run <manifestPath>

# 環境ファイルを指定
postman mock run <manifestPath> -e <path>

実行例

postman mock run postman/mocks/mock-1.json

このManifestファイルについての詳細は、以下のページを参照ください。

Configure local mock server details

なお、本記事では説明しませんが、Postman Cloud上でモックサーバーを作成している場合は、Postman Cloudのモックサーバーを利用することもできます。その場合は、コレクション実行時に環境変数でモックサーバーのURLを指定する形になります。

コレクション実行時にローカルモックを同時起動

ローカルモックサーバーは、コレクション実行時に --mock オプションで指定することもできます。これにより、モックサーバーを個別に起動する必要がなくなり、CIでのモックAPIテストがよりシンプルになります。

postman collection run <collection path> --mock <manifestPath>

実行例

# モックと一緒にコレクション実行
postman collection run ./postman/collections/Poll-API \
  --mock postman/mocks/mock-1.json

モニターの実行

Postman Cloudに設定済みのモニターをCLIからオンデマンドで実行します。ヘルスチェックやデプロイ後のスモークテストとしてスクリプトから呼び出すのに便利です。

postman monitor run <monitor-id>

# タイムアウト時間を設定（デフォルト: 900000ms = 15分）
# 例: タイムアウトを1分に設定
postman monitor run <monitor-id> --timeout 60000

# モニター結果に関わらず exit code を 0 にしてワークフローを継続させる
postman monitor run <monitor-id> --suppress-exit-code

注意: モニター実行時のレクションの指定はIDのみ（ローカルパス不可）

パフォーマンステストの実行

Postmanデスクトップアプリで、コレクションを対象に、パフォーマンステストが実行できることをご存じの方も多いかと思いますが、CLIからも同様にパフォーマンステストを実行できます。

postman performance runコマンドで、指定した仮想ユーザー数・時間・ロードプロファイルでコレクションを負荷実行し、レイテンシやエラー率を測定します。結果はPostman Cloudに自動保存されます。

# 基本実行
postman performance run <collection-id>

# 実行時間を指定（分）
postman performance run <collection-id> -d <minutes>

# 仮想ユーザー数を指定（デフォルト: 20）
postman performance run <collection-id> -d <minutes> --vu-count 30

# ロードプロファイルを指定（fixed / ramp-up / spike / peak、デフォルト: ramp-up）
postman performance run <collection-id> -p ramp-up

注意: パフォーマンステスト実行時のコレクションの指定はIDのみ（ローカルパス不可）

実行例

# オプション無し: 仮想ユーザー20、10分間、デフォルトのfixedプロファイルで実行
postman performance run 27917608-65963e87-c3ff-4be0-b05d-d329c9ddf48e
# 実行時間を1分、ロードプロファイルをramp-upに設定。他はデフォルト
postman performance run 27917608-65963e87-c3ff-4be0-b05d-d329c9ddf48e -d 1 -p ramp-up

出力例

実行時間を1分、ロードプロファイルをramp-upに設定して実行した場合の出力例です。実行中はリアルタイムでRPSや平均レイテンシが表示されます。

実行完了後に次のような結果情報と、Postman Cloudに自動保存された結果のレポートページURLが出力されます。

より細かな制御

環境やデータファイルを組み合わせることで、より実環境に近い負荷テストを実現できます。

# 環境指定
postman performance run <collection-id> -e <env-id>

# データファイル指定（CSV または JSON）
postman performance run <collection-id> --data-file <file-path>

成功条件の指定

レイテンシやエラー率などのメトリクスに基づいてPass/Failを判定する条件を設定できます。

postman performance run <collection-id> --pass-if "<condition>"

条件式	意味
`less_than(metric, value)`	metric が value より少ない
`less_than_eq(metric, value)`	metric が value 以下
`greater_than(metric, value)`	metric が value より大きい
`greater_than_eq(metric, value)`	metric が value 以上

metric に指定可能な値: avg, p90, p95, p99, error_rate, rps

例: --pass-if "less_than(p95, 500)" → 95パーセンタイルが500ms未満の場合にPass

実行例

# ログイン
postman login --with-api-key <API_KEY>

# 仮想ユーザー20、10分間、fixedプロファイル、95th percentile < 500ms でPass
postman performance run 27917608-1dc9ed7e-5aab-46f5-90eb-5cc351269690 \
  --vu-count 20 \
  --duration 10 \
  --load-profile fixed \
  --pass-if "less_than(p95, 500)"

実践的なシナリオ

CIフローでSpec検証、APIテスト、ワークスペースの同期

APIコードの変更をGitリポジトリにマージした際に、CIワークフローをトリガーして一連の処理を自動実行したいケースは多いかと思います。ネイティブGit連携を使用している場合、CIフローでSpec検証 → APIテスト → ワークスペースの同期という流れを自動化するのは典型的なパターンです。

# 1. ログイン
postman login --with-api-key $POSTMAN_API_KEY

# 2. OpenAPI Spec の Lint（ERRORが検出された場合は後続ステップを実行しない）
postman spec lint ./postman/specs/openapi.yaml --fail-severity ERROR

# 3. コレクション実行（APIテスト）
postman collection run ./postman/collections/Poll-API \
  -e ./postman/environments/staging.environment.yaml

# 4. ワークスペースをクラウドに同期
postman workspace push -y

下記の記事では、PostmanのネイティブGit連携でのCIフローの例を紹介しています。こちらも参考にしてください。

ローカルモックを動かしながらテストを実行

上記のCIフローでの実践例では、APIテストの前にローカルモックサーバーを起動して、モックAPIをテストの対象にするパターンも考えられます。以下、ローカルモックを起動しながらAPIテストを実行する例です。

# 1. ログイン
postman login --with-api-key $POSTMAN_API_KEY

# 2. OpenAPI Spec の Lint（ERRORが検出された場合は後続ステップを実行しない）
postman spec lint ./postman/specs/openapi.yaml --fail-severity ERROR

# 3. モックと一緒にコレクション実行
postman collection run ./postman/collections/Poll-API \
  --mock postman/mocks/mock-1.json \
  -e ./postman/environments/local.environment.yaml

# 4. ワークスペースをクラウドに同期
postman workspace push -y

Postman CLIでAPIテストを継続的実行する際の認可トークンの自動更新

Postman CLIでAPIテストを継続的実行する際の認可トークンの自動更新については、以下の記事で紹介しています。APIテストの実行前に、スクリプトで認可トークンを取得して環境変数にセットすることで、常に最新のトークンでAPIテストを実行できます。

Postman CLI References

さいごに

Postman CLIは今後も機能追加や改善が予定されているため、最新のドキュメントやリリースノートを定期的に確認することをオススメします。また、本記事も、Postman CLIのアップデートや有効な情報があれば随時追記していきます。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

Postman CLI 実践コマンドガイド

はじめに

Newmanとの違い

Quick Reference

CLIインストール

Login / Logout

ワークスペースへの同期

カスタムディレクトリの指定

コレクションの実行

環境変数の活用

データファイル指定（データ駆動テスト）

テスト失敗時の挙動制御

Exit Codeと--suppress-exit-codeオプション

レポーターの設定

APIリクエストの実行

Specの検証（Lint）

より細かな制御

モックサーバーの起動 (ローカルモック)

コレクション実行時にローカルモックを同時起動

モニターの実行

パフォーマンステストの実行

より細かな制御

成功条件の指定

実践的なシナリオ

CIフローでSpec検証、APIテスト、ワークスペースの同期

ローカルモックを動かしながらテストを実行

Postman CLIでAPIテストを継続的実行する際の認可トークンの自動更新

Postman CLI References

さいごに

Exit Codeと`--suppress-exit-code`オプション