KATATAN CLI

@katatan/cli is a command-line client for KATATAN that covers the same functionality as the MCP API, without requiring an MCP client to load tool schemas into its context. It's a thin wrapper around the same /mcp JSON-RPC endpoint — authentication, permissions, and rate limits are inherited directly from your MCP access token, and any operation not available as an MCP tool (user management, permission changes, token issuance) is not available in the CLI either.

The CLI is available on every plan — it uses your existing MCP access token, so it has no separate pricing or plan restriction of its own.

• Package: @katatan/cli on npm
• Commands: 37, one per MCP tool (test-spec, test-case, test-report, label, dictionary, image, vulnerability, plus tool and config)
• Auth: the same kat_ access tokens used for MCP

Install

Copy# Run directly with npx — no install needed
npx @katatan/cli test-spec list --token kat_xxxxxxxxxxxx

# Or install globally
npm install -g @katatan/cli
katatan --version

Authenticate

Use a kat_ token issued from Project Settings › MCP Access Tokens — the same token you'd use for an MCP connection.

Copy# Save it as a profile (omit --token afterward)
katatan config set-profile default kat_xxxxxxxxxxxx
katatan test-spec list

# Or pass it per call
katatan test-spec list --token kat_xxxxxxxxxxxx

Resolution order: --token flag > KATATAN_TOKEN environment variable > the active profile in ~/.katatan/config.json. --api-url follows the same order (default: https://mcp.katatan.com/mcp).

Profiles

Copykatatan config set-profile <name> <token> [--endpoint <url>]
katatan config use <name>
katatan config list [--show-token]
katatan config remove <name>

Profiles let you switch between multiple projects or tokens. Tokens are masked by default in config list.

Global options

Option	Description
--token <token>	Access token
--api-url <url>	MCP endpoint URL
--profile <name>	Profile to use
--json	Force JSON output
--table	Force table output
--author <name>	Operator name recorded in the audit log and createdBy/updatedBy (defaults to the token's UUID)

Output format

Detected automatically from process.stdout.isTTY:

• Interactive (TTY) — padded plain-text tables
• Non-interactive (piped, or run by an agent's Bash tool) — JSON

Override with --json / --table. JSON output is the underlying MCP tool response formatted as-is — see the MCP API reference for response schemas. Errors always go to stderr regardless of output format, so stdout stays clean for the success payload.

Deleting resources

delete and batch-delete commands show a [y/N] confirmation prompt only when run interactively (TTY). Pass -y / --yes to skip it. When run non-interactively (for example by an AI agent through a Bash tool), the command executes immediately without prompting, matching the MCP tools it wraps, which have no confirmation step of their own. All deletions are permanent.

Copykatatan test-case delete --spec-id <specId> --case-number 3
katatan test-spec delete <specId> --yes

Errors and exit codes

MCP error codes map to CLI exit codes:

MCP error code	Exit code
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
Unknown / internal error	10
Local validation failure (missing required option, etc.)	1

With --json, errors are written to stderr as {"error": {"code": "...", "message": "...", "details": {...}}}.

Commands

Each command maps 1:1 to an MCP tool. Composite IDs ({projectId}.{specUuid}, etc.) follow the same format as the MCP API.

test-spec

Command	MCP tool
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

Command	MCP tool
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

Command	MCP tool
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

Command	MCP tool
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

Command	MCP tool
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

Command	MCP tool
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 (read-only)

Command	MCP tool
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

There's no MCP tool for registering, running, or deleting scan targets, so the CLI doesn't expose those either — manage targets and scans from the dashboard.

tool (escape hatch)

Command	Description
tool list	Runs tools/list and prints the available MCP tools with their JSON Schema
tool call <name> [--json-args '<json>']	Calls any MCP tool directly by name — useful for a new tool not yet covered by a curated command

config (local only, not an MCP tool)

Command	Description
config set-profile <name> <token> [--endpoint <url>]	Create or update a profile
config use <name>	Switch the active profile
config list [--show-token]	List profiles
config remove <name>	Remove a profile

Using it from an AI coding agent

Unlike MCP, there's no tool-definition (JSON Schema) payload to load into context on every call. An agent can reference katatan <command> --help via its Bash/shell tool only when needed, and parse the default JSON output (used automatically outside a TTY).

Copykatatan test-case list --spec-id proj-abc.550e8400-...
katatan test-report update-result proj-abc.550e8400-....7f000001 --result-id <uuid> --test-result OK