KATATAN CLI
@katatan/cli は、MCPクライアントによるツール定義(JSON Schema)の読み込みを必要とせずに、MCP APIと同等の機能をコマンドラインから利用できるKATATAN公式CLIです。既存の /mcp JSON-RPCエンドポイントに直接アクセスする薄いクライアントとして実装されており、認証・権限・レート制限はMCPアクセストークンからそのまま継承されます。MCPツールとして提供されていない操作(ユーザー管理、権限変更、トークン発行など)は、CLIにも実装されていません。
CLIはすべてのプランで利用できます。既存のMCPアクセストークンを使う仕組みのため、CLI専用の料金体系やプラン制限はありません。
- パッケージ: npm
@katatan/cli - コマンド数: 37(MCPツールと1対1で対応。
test-spec/test-case/test-report/label/dictionary/image/vulnerability、およびtool/config) - 認証: MCPと同じ
kat_アクセストークン
インストール
# インストール不要でnpx実行
npx @katatan/cli test-spec list --token kat_xxxxxxxxxxxx
# またはグローバルインストール
npm install -g @katatan/cli
katatan --version認証
プロジェクト設定 › MCP Access Tokens で発行した kat_ トークン(MCP接続で使うものと同じ)を使用します。
# プロファイルとして保存(以降は--token省略可)
katatan config set-profile default kat_xxxxxxxxxxxx
katatan test-spec list
# または呼び出しごとに指定
katatan test-spec list --token kat_xxxxxxxxxxxx優先順位: --token フラグ > KATATAN_TOKEN 環境変数 > ~/.katatan/config.json のカレントプロファイル。--api-url も同様の優先順位(デフォルト: https://mcp.katatan.com/mcp)。
プロファイル
katatan config set-profile <name> <token> [--endpoint <url>]
katatan config use <name>
katatan config list [--show-token]
katatan config remove <name>複数のプロジェクト・トークンをプロファイルとして切り替えられます。config list ではトークンがデフォルトでマスク表示されます。
共通オプション
| オプション | 説明 |
|---|---|
--token <token> |
アクセストークン |
--api-url <url> |
MCPエンドポイントURL |
--profile <name> |
使用するプロファイル名 |
--json |
JSON形式で出力を強制 |
--table |
テーブル形式で出力を強制 |
--author <name> |
監査ログおよび createdBy/updatedBy に記録される操作者名(省略時はトークンのUUID) |
出力フォーマット
process.stdout.isTTY により自動判定されます。
- 対話実行(TTY): パディング済みのプレーンテキストテーブル
- 非対話実行(パイプ、AIエージェントのBashツール経由など): JSON
--json/--table で明示的に上書きできます。JSON出力はMCPツールのレスポンスをそのまま整形したもので、レスポンス型の詳細はMCP APIリファレンスを参照してください。エラーは出力フォーマットに関わらず常にstderrに出力されるため、stdoutは成功時のペイロードのみに保たれます。
削除操作について
delete/batch-delete コマンドは、対話実行時(TTY)のみ [y/N] の確認プロンプトを表示します。-y/--yes で確認をスキップできます。非対話実行時(AIエージェントがBashツール経由で実行する場合など)は、確認なしで即実行されます。これは、対応するMCPツール自体に確認機構がないことと一貫性を保つための挙動です。削除操作はすべて取り消せません。
katatan test-case delete --spec-id <specId> --case-number 3
katatan test-spec delete <specId> --yesエラーと終了コード
MCPのエラーコードは、CLIの終了コードに以下のようにマッピングされます。
| MCPエラーコード | 終了コード |
|---|---|
AUTHENTICATION_ERROR |
2 |
AUTHORIZATION_ERROR |
3 |
VALIDATION_ERROR |
4 |
NOT_FOUND |
5 |
CONFLICT |
6 |
RATE_LIMIT_EXCEEDED |
7 |
QUOTA_EXCEEDED |
8 |
FEATURE_NOT_AVAILABLE |
9 |
| 不明なエラー・内部エラー | 10 |
| ローカルバリデーション失敗(必須オプション欠落など) | 1 |
--json時のエラー出力は {"error": {"code": "...", "message": "...", "details": {...}}} の形式でstderrに書き出されます。
コマンド一覧
各コマンドはMCPツールと1対1で対応します。複合ID({projectId}.{specUuid} 等)の形式はMCP APIと共通です。
test-spec
| コマンド | MCPツール |
|---|---|
test-spec list |
list_test_specs |
test-spec get <id> |
get_test_spec |
test-spec create --name <name> [...] |
create_test_spec |
test-spec update <id> [...] |
update_test_spec |
test-spec delete <id> |
delete_test_spec |
test-case
| コマンド | MCPツール |
|---|---|
test-case list [--spec-id <id>] |
list_test_cases_by_spec / list_test_cases |
test-case get --spec-id <id> --case-number <n> |
get_test_case |
test-case create --spec-id <id> [...] |
create_test_case |
test-case batch-create --spec-id <id> --file <path> |
batch_create_test_cases |
test-case update --spec-id <id> --case-number <n> [...] |
update_test_case |
test-case delete --spec-id <id> --case-number <n> |
delete_test_case |
test-case batch-delete --spec-id <id> --file <path> |
batch_delete_test_cases |
test-report
| コマンド | MCPツール |
|---|---|
test-report start --spec-id <id> --report-name <name> |
start_test |
test-report list |
list_test_reports |
test-report get <id> |
get_test_report |
test-report update-result <reportId> --result-id <id> [...] |
update_test_report_result |
test-report batch-update-results <reportId> --file <path> |
batch_update_test_results |
test-report abort <id> |
abort_test_report |
test-report reopen <id> |
reopen_test_report |
test-report force-complete <id> |
force_complete_test_report |
test-report delete <id> |
delete_test_report |
test-report summary |
get_completion_summary |
label
| コマンド | MCPツール |
|---|---|
label create --workspace-id <id> --name <name> --color <color> |
create_label |
label list --workspace-id <id> |
list_labels |
label assign --spec-id <id> --case-number <n> [--label-id ...] |
assign_labels_to_test_case |
label delete --id <id> --workspace-id <id> |
delete_label |
dictionary
| コマンド | MCPツール |
|---|---|
dictionary create --key <key> --value <value> |
create_dictionary_entry |
dictionary list |
list_dictionary_entries |
dictionary get <key> |
get_dictionary_entry |
dictionary update <key> --value <value> |
update_dictionary_entry |
dictionary delete <key> |
delete_dictionary_entry |
image
| コマンド | MCPツール |
|---|---|
image upload --spec-id <id> --case-number <n> --file <path> |
upload_test_case_image |
image delete --spec-id <id> --case-number <n> --image-id <id> |
delete_test_case_image |
vulnerability(参照専用)
| コマンド | MCPツール |
|---|---|
vulnerability target list |
list_vulnerability_targets |
vulnerability report list --target-id <id> |
list_vulnerability_reports |
vulnerability report get <reportId> --target-id <id> |
get_vulnerability_report |
スキャン対象の登録・実行・削除に相当するMCPツールは存在しないため、CLIにも実装されていません。これらはダッシュボードから操作してください。
tool(汎用エスケープハッチ)
| コマンド | 説明 |
|---|---|
tool list |
tools/list を実行し、利用可能なMCPツール一覧とJSON Schemaを表示 |
tool call <name> [--json-args '<json>'] |
指定したツール名を直接呼び出す。キュレーテッドコマンドが未対応の新規ツールにも即座にアクセスできる |
config(ローカル設定、MCPツールではない)
| コマンド | 説明 |
|---|---|
config set-profile <name> <token> [--endpoint <url>] |
プロファイルを作成/更新 |
config use <name> |
カレントプロファイルを切り替え |
config list [--show-token] |
プロファイル一覧を表示 |
config remove <name> |
プロファイルを削除 |
AIコーディングエージェントからの利用
MCPと異なり、ツール定義(JSON Schema)を毎回コンテキストに読み込む必要がありません。エージェントはBash/シェルツール経由で katatan <command> --help を必要な時だけ参照し、非TTY実行時のデフォルト出力(JSON)をそのままパースできます。
katatan test-case list --spec-id proj-abc.550e8400-...
katatan test-report update-result proj-abc.550e8400-....7f000001 --result-id <uuid> --test-result OK