CLI Reference
ktx status
Check ktx setup and project readiness.
Run the ktx readiness doctor. Inside a ktx project, this checks setup,
project configuration, semantic search, query history, connections, and related
diagnostics. Outside a project, it checks local CLI setup readiness so you know
whether ktx setup can run.
Command signature
ktx status [options]
Options
| Flag | Description | Default |
|---|---|---|
--json | Print JSON output | false |
-v, --verbose | Show every check, including passing ones | false |
--validate | Only validate the ktx.yaml schema; skip readiness checks | false |
--no-input | Disable interactive terminal input | - |
Examples
# Show project status ktx status # Get status as JSON without interactive input ktx status --json --no-input # Show all checks, not only warnings and failures ktx status --verbose # Validate ktx.yaml without running readiness checks ktx status --validate # Check a project from another directory ktx status --project-dir ./analytics
Output
ktx status prints grouped doctor checks. Agents should use
ktx status --json --no-input when they need to branch on readiness state.
For llm.provider.backend: claude-code, ktx status checks that the local
Claude Code session is usable. If auth fails, run the Claude Code CLI login
flow, then rerun ktx status.
{ "title": "ktx project doctor", "checks": [ { "id": "project-config", "label": "Project config", "status": "pass", "detail": "warehouse" } ] }
Common errors
| Error | Cause | Recovery |
|---|---|---|
| No ktx project found | Current directory has no ktx.yaml and KTX_PROJECT_DIR is unset | ktx status runs setup checks; run from a ktx project or set KTX_PROJECT_DIR for project checks |
| Project config check fails | The project directory is missing or has an invalid ktx.yaml | Run ktx setup to resume setup |
| Schema validation fails | ktx.yaml does not match the current config schema | Run ktx status --validate --json for structured issue details, then edit ktx.yaml or rerun ktx setup |
| Semantic search check warns | Embeddings are not configured or the provider probe failed | Run ktx setup or inspect the check's fix field in JSON output |
| Query history check warns | A database has query history enabled but the warehouse prerequisites are missing | Fix the warehouse extension, grants, or history access, then rerun ktx status |