Troubleshooting and versions

Capture the version and error

node --version
kitta --version
kitta auth status --json

Include CLI and Node versions, operating system, a redacted command, exit code and requestId/taskId from diagnostics when contacting support. Do not include API keys, complete customer text or credential-bearing URLs.

Common problems

Symptom	Next action
kitta not found	Check Node.js 22+, npm's global executable directory and PATH; reopen the terminal.
Invalid input, exit 2	Run the command's --help and --schema; replace placeholders.
Authentication failure, exit 3	Check origin and account key. Environment overrides keyring; logout does not clear the environment.
Insufficient quota, exit 4	Check API quota in your account; do not assume a web subscription implies available API quota.
Wait timeout, exit 5	Keep the task ID and query it; do not immediately create another task.
Output file exists	Choose a new output path; the CLI does not overwrite files.
Transcription URL inaccessible	Ensure the remote service can access the audio; local paths and localhost URLs are not usable.
Incomplete voice list	Use --all and inspect complete, nextPage and the exit code.

Upgrades and compatibility

npm install -g @kittaai/cli@latest
kitta --version

Pin a version you have verified for automated deployments. CLI and HTTP API versions are independent; do not infer endpoint paths from the package version. Additive response fields are accepted, but missing required fields or unknown statuses may fail client validation.

npm versions

CLI documentation changelog

2026-09-22 — Public documentation

Added bilingual installation, quickstart, audio workflows, recovery, automation, coding-agent and SDK guides.
Command reference and SDK examples were checked against CLI/SDK 0.1.0. Documentation publication does not imply a new package version.
Verified CLI TTS generation/recovery and the standalone SDK example on Windows. Shell wrappers were checked with PowerShell and Git Bash; native macOS/Linux end-to-end acceptance is not established by these checks.
Added an explicitly labeled synthetic voice-design sample. It is not the output of the separate TTS placeholder command.

For support, use the Support link on the Kitta CLI product page. Send redacted request/task IDs privately, not in public reports.

Next: recovery and billing.