この記事は、筆者の英語記事 An unofficial tab completion for the Postman CLI の翻訳版です。
英語版を元に Claude Code で日本語に翻訳し、筆者が加筆・修正しました。
なお、記事中で紹介するツールは非公式の個人プロジェクトであって、Postman の公式プロダクトではありません。
コマンド名が思い出せず毎回 postman --helpを叩くつらさ
Postman CLI を触っていて、コマンド名が思い出せずに postman --help を叩いた回数はどのくらいあるでしょうか。
collection、spec、monitor、workspace、flows。
トップレベルだけでも覚えることが多くあります。
さらにその下のサブコマンド、-r cli,json,junit,html のようなフラグの値、そして *.json や *.yaml のファイル引数。
うろ覚えのまま打鍵して失敗し、履歴を遡り、--help を眺め直します。
CLI の操作でよくある、ごく小さな摩擦です。
補完があれば済む話なのですが、Postman CLI には公式のシェル補完がまだ用意されていません。
ツールの概要
その隙間を埋めるために作ったのが postman-cli-completion です。
postman コマンドに対して zsh / bash / fish のタブ補完を提供する、小さな OSS ツールです。
補完できるのは次のとおりです。
-
login、collection、spec、monitor、workspace、flowsなどのトップレベルコマンド - 各コマンドのサブコマンド
- 各コマンドのフラグ（
--environment、--reportersなど） - ローカルファイル引数（コレクションの
*.json、スペックの*.yaml/*.yml/*.json）
一方で、次のことはやりません。
- リモート ID の動的補完（
collection IDやworkspace IDを API から引いてくる） - Postman API への認証やネットワークアクセス
- Postman CLI 本体の機能の代替
ID はコピペで済むことがほとんどなので、あえて踏み込まない設計にしています。
ライセンスは MIT で、npm から入れられます。
使い方
npm でのインストール
npm install -g postman-cli-completion
これで postman-completion というヘルパーコマンドが入ります。
名前は似ていますが本物の postman CLI 本体ではないので、そちらが未インストールなら別途入れておいてください。
npm install -g postman-cli
zsh
postman-completion は、指定したシェル向けの補完スクリプトを標準出力に吐き出すだけの小さなヘルパーです。
いまのシェルで試すだけならこれで済みます。
source <(postman-completion zsh)
新しいターミナルでも効かせたいなら、~/.zshrc に次を追記します。
fpath=("$(postman-completion path zsh --dir)" $fpath)
autoload -Uz compinit && compinit
fpath に補完スクリプトの置き場所を足し、compinit で読み直しているだけの、素直なやり方です。
bash
~/.bashrc に source <(postman-completion bash) と書けば有効になります。
shopt -s extglob を使っているため、bash 4 以上が必要という制約があります。
macOS の標準 bash は 3.2 のままなので、Homebrew で新しい bash を入れておくとよいでしょう。
brew install bash
fish
現在のセッションで試すには次のようにします。
postman-completion fish | source
永続化するなら、fish の補完ディレクトリにシンボリックリンクを張ります。
ln -sf "$(postman-completion path fish)" ~/.config/fish/completions/postman.fish
何がどう補完されるのか
インストールが済んだら、新しいターミナルを開いて挙動を見てみてください。
postman <TAB> を押せばトップレベルコマンドの一覧が出ますし、postman col<TAB> は collection に補完されます。
postman collection run <TAB> はカレントディレクトリの *.json を列挙し、postman collection run -r <TAB> なら cli、json、junit、html が候補になります。
打鍵数が減るだけではありません。
フラグやレポーターの名前をうろ覚えのままでも、--help に戻らずに作業を続けられます。
どうやって最新に追随しているか
補完スクリプトを一度書いて放置すると、Postman CLI 側の更新に置いていかれます。
新しいコマンドやフラグが増えるたびに、補完は少しずつ古くなっていきます。
そこで、更新への追随を GitHub Actions の2本のワークフローに任せています。
一方は毎日 npm を見に行き、postman-cli の最新バージョンの --help の出力を解析します。
差分があれば spec と3シェル分の補完スクリプトを再生成し、自動マージ設定つきの PR を開きます。
もう一方は、spec が main に入ったタイミングで、Postman CLI のバージョンに揃えた GitHub Release を切ります。
補完スクリプトは手書きではありません。
--help の出力を情報源として spec が作られ、その spec から3つのシェル向けスクリプトが導出されます。
もっとも、--help の解析は完全ではありません。
フラグが一気に大幅に減った、既知のコマンドが消えた、バージョンが逆行したといった怪しい差分は検証スクリプトがブロックします。
そのときは自動マージされず、人間のレビュー待ちの PR として残ります。
補完対象のバージョンと手元の CLI が噛み合っているかは、この2つを比べれば確認できます。
node -p "require('./spec/commands.json').postmanCliVersion"
postman --version
まとめ
補完がないだけで、CLI の操作には --help を往復する手間がついて回ります。
postman-cli-completion は、その手間を1コマンドのインストールで取り除きます。
- zsh / bash / fish の3シェルに対応
- コマンド、サブコマンド、フラグ、ローカルファイル引数まで補完
- Postman CLI の新バージョンに CI が自動で追随
リモート ID の補完は対象外、bash は 4 以上が必要、という制約はあります。
気になった方は yokawasa/postman-cli-completion を覗いてみてください。
Issue も PR も大歓迎です。