mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
148 lines
4.5 KiB
Text
148 lines
4.5 KiB
Text
---
|
|
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 |
|