The VulnCheck CLI

vulncheck は、コマンドラインから VulnCheck API にアクセスするためのツールです。インデックスの閲覧、バックアップ管理、脆弱性スキャンをターミナルにもたらします。

インストール

提供されているインストールスクリプト

インストールスクリプトを使用して vulncheck を簡単にインストールできます。お使いのオペレーティングシステムに合ったスクリプトと方法を選択してください:

macOS および Linux

ターミナルを開いて実行します:

curl -sSL https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.sh | bash

システム全体へのインストール (sudo が必要) か、ローカルユーザーへのインストールかを選択するプロンプトが表示されます。

[!NOTE] インストールスクリプトは非対話型のインストールオプションもサポートしています:

• --sudo でプロンプトなしのシステム全体へのインストール
• --non-sudo でプロンプトなしのローカルユーザーへのインストール
• --help または -h で利用可能なすべてのオプションを表示

curl -sSL https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.sh | bash -s -- --help

Windows

PowerShell を開いて実行します:

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.ps1'))

タブ補完を有効にするには、PowerShell プロファイルからバンドルされたスクリプトをドットソースで読み込みます:

Add-Content -Path $PROFILE -Value ". '$env:LOCALAPPDATA\Programs\vulncheck\share\powershell\vulncheck.ps1'"

vulncheck のバイナリは MacOS、Linux、Windows 向けにも提供されています。コンパイル済みバイナリは releases ページ からダウンロードできます。

インストールの確認

インストール後、バイナリが目的のバージョンを表示することを確認します:

vulncheck version

バージョン、ビルド日、changelog の URL が表示されるはずです。「command not found」と表示された場合は、シェルを開き直して新しい PATH を反映させてから、再度試してください。

設定

• vulncheck auth login を実行して、VulnCheck アカウントで認証します。
• あるいは vulncheck は VULNCHECK_API_TOKEN 環境変数を尊重します — VulnCheck SDK および MCP サーバーで使用されているのと同じ名前です。レガシーの VC_TOKEN も引き続き機能し、両方が設定されている場合はこちらが優先されます。
• vulncheck auth だけを実行すると、ステータスの確認やログアウトなど、その他のオプションが表示されます。

いずれの環境変数も、保存された設定ファイルよりも優先されます。そのため、いずれかが設定されている間は auth login と auth logout は拒否されます — そうでなければ、実際には何も変わらないのに成功したと報告してしまうからです。vulncheck auth status を実行すると、アクティブなトークンがどのソース、どの変数から来たのかを確認できます。

エージェント / スクリプトによる利用

この CLI は、スクリプトや AI エージェントから安全に操作できるように設計されています。このセクションはその契約です — 以下に示すインターフェースはリリース間で安定していることを意図しています (追加は破壊的変更ではありませんが、名前変更 / 削除は破壊的変更です)。

グローバルフラグ

フラグ	効果
--json	stdout に JSON を出力し、info/進捗行は stderr にルーティングし、エラーは構造化されたエンベロープとして出力します。
--quiet	情報出力を抑制します。エラーとペイロードは引き続き表示されます。
--no-color	ANSI スタイリングを無効にします。NO_COLOR 環境変数も尊重します。
--no-interactive	TUI プロンプトでのブロックを拒否します。プロンプトが必要なコマンドは代わりにエラーを返します。--json、非 TTY の stdin/stdout、および CI / BUILD_NUMBER / RUN_ID 環境変数のいずれかによって暗黙的に有効になります。

環境変数

変数	効果
VULNCHECK_API_TOKEN	API トークンであり、推奨される名前です — VulnCheck SDK および MCP サーバーと共有されます。~/.config/vulncheck/vulncheck.yaml よりも優先されます。設定されている間は、auth login と auth logout は無視されるファイルを書き込むのではなく拒否します。
VC_TOKEN	レガシーのエイリアスで、引き続き完全にサポートされており、両方が設定されている場合は VULNCHECK_API_TOKEN よりも優先されます。そのため、既存のセットアップの認証情報が変わることはありません。両方をクリアすると設定ファイルにフォールバックします。auth status はどちらが使用されているかを報告します。
NO_COLOR	空でない値であれば ANSI スタイリングを無効にします。
CI / BUILD_NUMBER / RUN_ID	これらのいずれかが設定されていると、非対話モード (プロンプトなし) が暗黙的に有効になります。

終了コード

コード	意味
0	成功。
1	一般的な / 内部エラー。
2	検証失敗 (不正な引数、必須フラグの欠落、不正なリクエスト)。
3	認証失敗 (トークンなし、またはサーバーがトークンを拒否)。
4	リソースが見つからない (HTTP 404、そのようなインデックスは存在しない)。
5	レート制限 (HTTP 429)。
6	ネットワーク障害 (DNS、接続拒否、タイムアウト)。
130	SIGINT によるキャンセル (POSIX 128 + 2)。

エラーエンベロープ

--json モードでは、エラーは stdout に次のように出力されます:

{
  "schema_version": 1,
  "error": {
    "code": "auth_required",
    "message": "...",
    "http_status": 401,
    "hint": "..."
  }
}

code は次のいずれかです: internal、validation、auth_required、auth_invalid、not_found、rate_limited、network、bad_request、cancelled。http_status は HTTP 以外のエラーでは省略されます。hint はオプションの修復コンテキストで、メッセージだけでは対応できない場合にのみ存在します (例: 拒否されたトークンを提供した変数名を示す)。--json モード以外では stderr に hint: ... として表示されます。

プローブコマンド

作業をディスパッチする前に、CLI 自体を検査するにはこれらを使用します:

vulncheck version --json
# {"schema_version": 1, "version": "...", "build_date": "...", "changelog_url": "..."}

vulncheck auth status --json
# {"schema_version": 1, "authenticated": true, "token_source": "env",
#  "token_env_var": "VC_TOKEN", "user": "...", "email": "..."}
# authenticated=false でも終了コード 0 — エージェントは bool でディスパッチします。
# token_env_var は token_source が "env" の場合にトークンを提供した変数名を示し、
# それ以外では省略されます。authenticated=false の場合も設定されるため、
# 拒否されたトークンがどの変数に保持されているかを追跡できます。
# token_shadowed: true は、環境トークンが vulncheck.yaml に保存された
# *別の* トークンを上書きしている場合に追加されます — これは「ログインしたのに
# 何も変わらない」というよくある原因です。それ以外では省略されるため、
# CI の形 (環境トークンのみ、設定ファイルなし) ではシャドーイングが報告されることはありません。

vulncheck commands
# {"schema_version": 1, "root": {"name":"vulncheck", "subcommands":[...]}, ...}
# コマンドツリー全体の機械可読ダンプ — すべてのサブコマンド、
# すべてのフラグ (型 + デフォルト + 使用法)、エイリアス、非推奨情報。
# --help を解析する代わりにこれを使用してください。認証は不要です。

ページネーション

vulncheck token list --json --limit 10 --page 2
vulncheck token list --json --all       # 自動ページネーション、単一の結合配列
vulncheck index list <index> --json --all

バッチ入力

purl、cpe、tag、pdns は、位置引数、stdin (パイプ経由の場合)、または --from-file <path> を介して複数の入力を受け付けます。ファイル内の空行と # で始まるコメントは無視されます。バッチモードには --json が必要です。

# Stdin
cat purls.txt | vulncheck purl --json

# File
vulncheck cpe --from-file ./cpes.txt --json

バッチエンベロープは安定した配列で、入力ごとに 1 行、入力順に並びます:

[
  {"input": "pkg:npm/[email protected]", "data": { ... }},
  {"input": "pkg:bad/string", "error": "no result returned for this purl"}
]

キャンセル

SIGINT / SIGTERM は、コンテキスト伝播を介して進行中の HTTP リクエストをクリーンにキャンセルします。長時間実行される操作 (scan、offline sync、backup download) はキャンセルを尊重し、該当する場合は終了時に部分的なファイルが削除されます。

JSON 出力の規律

--json が設定されている場合:

• stdout は JSON ペイロードのみ (または上記のエラーエンベロープ) を運びます。
• stderr はすべての info 行、プログレスバー、スピナー、プロンプト、警告を運びます。
• TUI 要素 (bubbletea、huh プロンプト) は自動的に抑制されます。

つまり、vulncheck <cmd> --json | jq は常に機能します — tail/sed によるクリーンアップは不要です。

利用可能なコマンド

以下のすべてのコマンドは グローバルフラグ (--json、--quiet、--no-color、--no-interactive、--help/-h) を受け付けます。コマンドごとのフラグ表には、そのコマンドに固有のものだけを記載しています。