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 を出力します。情報/進捗の行は 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": "..."}
# Exit 0 even when authenticated=false — agents dispatch on the bool.
# token_env_var names which variable supplied the token when token_source is
# "env"; omitted otherwise. Set when authenticated=false too, so a rejected
# token can be traced to the variable holding it.
# token_shadowed: true is added when an environment token is overriding a
# *different* token saved in vulncheck.yaml — the usual cause of "I logged
# in but nothing changed". Omitted otherwise, so the CI shape (env token
# only, no config file) never reports shadowing.

vulncheck commands
# {"schema_version": 1, "root": {"name":"vulncheck", "subcommands":[...]}, ...}
# Machine-readable dump of the whole command tree — every subcommand,
# every flag (with type + default + usage), aliases, deprecation. Use
# this instead of parsing --help. Auth is not required.

ページネーション

vulncheck token list --json --limit 10 --page 2
vulncheck token list --json --all       # auto-paginate, single combined array
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 にはすべての情報行、プログレスバー、スピナー、プロンプト、警告が出力されます。
• TUI 要素（bubbletea、huh プロンプト）は自動的に抑制されます。

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

利用可能なコマンド

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