ktx/docs-site/content/docs/cli-reference/ktx-status.mdx

---
title: "ktx status"
description: "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

```bash
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

```bash
# 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`.

```json
{
  "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` |