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

---
title: "ktx agent"
description: "Machine-readable commands for coding agents."
---

Hidden commands that provide machine-readable JSON output for coding agents. These are the commands that agent integrations (Claude Code, Cursor, Codex, OpenCode) call under the hood — you typically won't use them directly.

All `ktx agent` subcommands require `--json` and produce structured JSON output on stdout.

## Command signature

```bash
ktx agent <subcommand> --json [options]
```

## Subcommands

| Subcommand | Description |
|-----------|-------------|
| `tools` | Print available agent-facing KTX tools |
| `context` | Print project context for agent planning |
| `sl list` | List semantic-layer sources |
| `sl read <sourceName>` | Read one semantic-layer source |
| `sl query` | Run a semantic-layer query from a JSON file |
| `wiki search <query>` | Search KTX wiki pages |
| `wiki read <pageId>` | Read one KTX wiki page |
| `sql execute` | Execute read-only SQL with a row limit |

## Options

### `agent tools`

| Flag | Description | Default |
|------|-------------|---------|
| `--json` | Print JSON output (required) | — |

### `agent context`

| Flag | Description | Default |
|------|-------------|---------|
| `--json` | Print JSON output (required) | — |

### `agent sl list`

| Flag | Description | Default |
|------|-------------|---------|
| `--json` | Print JSON output (required) | — |
| `--connection-id <id>` | Filter by connection id | — |
| `--query <text>` | Search source names and descriptions | — |

### `agent sl read`

| Flag | Description | Default |
|------|-------------|---------|
| `--json` | Print JSON output (required) | — |
| `--connection-id <id>` | Connection id containing the source | — |

### `agent sl query`

| Flag | Description | Default |
|------|-------------|---------|
| `--json` | Print JSON output (required) | — |
| `--connection-id <id>` | Connection id for execution (required) | — |
| `--query-file <path>` | JSON semantic-layer query file (required) | — |
| `--execute` | Execute the compiled query against the connection | `false` |
| `--max-rows <number>` | Maximum rows to return when executing (1-1000) | — |

### `agent wiki search`

| Flag | Description | Default |
|------|-------------|---------|
| `--json` | Print JSON output (required) | — |
| `--limit <number>` | Maximum search results | `10` |

### `agent wiki read`

| Flag | Description | Default |
|------|-------------|---------|
| `--json` | Print JSON output (required) | — |

### `agent sql execute`

| Flag | Description | Default |
|------|-------------|---------|
| `--json` | Print JSON output (required) | — |
| `--connection-id <id>` | Connection id for execution (required) | — |
| `--sql-file <path>` | SQL file to execute (required) | — |
| `--max-rows <number>` | Maximum rows to return, 1-1000 (required) | — |

## Examples

```bash
# List available tools
ktx agent tools --json

# Get project context for planning
ktx agent context --json

# List semantic sources
ktx agent sl list --json

# Search semantic sources by name
ktx agent sl list --json --query "revenue"

# Read a semantic source
ktx agent sl read orders --json --connection-id my-warehouse

# Run a semantic-layer query from a file
ktx agent sl query --json \
  --connection-id my-warehouse \
  --query-file /tmp/query.json \
  --execute \
  --max-rows 100

# Search wiki pages
ktx agent wiki search "churn definition" --json

# Read a specific wiki page
ktx agent wiki read page-abc123 --json

# Execute read-only SQL
ktx agent sql execute --json \
  --connection-id my-warehouse \
  --sql-file /tmp/query.sql \
  --max-rows 500
```

## Output

Every `ktx agent` command writes JSON to stdout and diagnostic text to stderr. Agents should parse stdout as JSON and treat a non-zero exit code as a failed tool call.

```json
{
  "ok": true,
  "data": {
    "type": "agent-response"
  }
}
```

## Common errors

| Error | Cause | Recovery |
|-------|-------|----------|
| Missing JSON output | `--json` was omitted | Re-run the same subcommand with `--json` |
| Unknown connection id | The requested connection is not configured in `ktx.yaml` | Call `ktx agent context --json` or `ktx connection list` to discover valid ids |
| Query file cannot be read | `--query-file` points to a missing or invalid JSON file | Write the query payload to a real file and pass its absolute path |
| SQL execution rejected | SQL is not read-only or `--max-rows` is missing | Use semantic-layer queries first; for direct SQL, pass read-only SQL and an explicit row limit |