mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-10 08:05:14 +02:00
feat(cli)!: remove ktx agent command
This commit is contained in:
Andrey Avtomonov
parent
46b013e32a
commit
cf424cb09e
41 changed files with 501 additions and 1896 deletions
|
|
@ -1,148 +0,0 @@
|
|||
---
|
||||
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 |
|
||||
|
|
@ -28,6 +28,7 @@ ktx sl <subcommand> [options]
|
|||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--connection-id <id>` | Filter by KTX connection id | — |
|
||||
| `--query <text>` | Search source names and descriptions | — |
|
||||
| `--output <mode>` | Output mode: `pretty` (default in TTY), `plain` (TSV), or `json` | `pretty` |
|
||||
| `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` |
|
||||
|
||||
|
|
@ -36,6 +37,7 @@ ktx sl <subcommand> [options]
|
|||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--connection-id <id>` | KTX connection id (required) | — |
|
||||
| `--json` | Print JSON output | `false` |
|
||||
|
||||
### `sl validate`
|
||||
|
||||
|
|
@ -55,6 +57,7 @@ ktx sl <subcommand> [options]
|
|||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--connection-id <id>` | KTX connection id | — |
|
||||
| `--query-file <path>` | JSON semantic-layer query file | — |
|
||||
| `--measure <measure>` | Measure to query; repeatable (at least one required) | — |
|
||||
| `--dimension <dimension>` | Dimension to include; repeatable | — |
|
||||
| `--filter <filter>` | Filter expression; repeatable | — |
|
||||
|
|
@ -78,9 +81,15 @@ ktx sl list --connection-id my-warehouse
|
|||
# List sources as JSON
|
||||
ktx sl list --json
|
||||
|
||||
# Search sources as JSON
|
||||
ktx sl list --json --query "revenue"
|
||||
|
||||
# Read a source definition
|
||||
ktx sl read orders --connection-id my-warehouse
|
||||
|
||||
# Read a source definition as JSON
|
||||
ktx sl read orders --connection-id my-warehouse --json
|
||||
|
||||
# Validate a source against the live schema
|
||||
ktx sl validate orders --connection-id my-warehouse
|
||||
|
||||
|
|
@ -119,6 +128,13 @@ ktx sl query \
|
|||
--dimension orders.created_date \
|
||||
--execute \
|
||||
--max-rows 1000
|
||||
|
||||
# Execute a query from a JSON file
|
||||
ktx sl query \
|
||||
--connection-id my-warehouse \
|
||||
--query-file query.json \
|
||||
--execute \
|
||||
--max-rows 100
|
||||
```
|
||||
|
||||
## Output
|
||||
|
|
|
|||
|
|
@ -26,19 +26,23 @@ ktx wiki <subcommand> [options]
|
|||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--user-id <id>` | Local user id | `local` |
|
||||
|
||||
### `wiki read`
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--user-id <id>` | Local user id | `local` |
|
||||
|
||||
### `wiki search`
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--user-id <id>` | Local user id | `local` |
|
||||
| `--limit <number>` | Maximum search results | — |
|
||||
|
||||
### `wiki write`
|
||||
|
||||
|
|
@ -58,12 +62,21 @@ ktx wiki <subcommand> [options]
|
|||
# List all wiki pages
|
||||
ktx wiki list
|
||||
|
||||
# List all wiki pages as JSON
|
||||
ktx wiki list --json
|
||||
|
||||
# Read a specific wiki page
|
||||
ktx wiki read revenue-definitions
|
||||
|
||||
# Read a specific wiki page as JSON
|
||||
ktx wiki read revenue-definitions --json
|
||||
|
||||
# Search wiki pages
|
||||
ktx wiki search "monthly recurring revenue"
|
||||
|
||||
# Search wiki pages as JSON
|
||||
ktx wiki search "monthly recurring revenue" --json --limit 10
|
||||
|
||||
# Write a global knowledge page
|
||||
ktx wiki write revenue-definitions \
|
||||
--summary "Canonical revenue metric definitions" \
|
||||
|
|
@ -97,13 +110,16 @@ Wiki commands print local knowledge pages and search results. Agents should sear
|
|||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"key": "revenue-definitions",
|
||||
"summary": "Canonical revenue metric definitions",
|
||||
"score": 0.92
|
||||
}
|
||||
]
|
||||
"kind": "list",
|
||||
"data": {
|
||||
"items": [
|
||||
{
|
||||
"key": "revenue-definitions",
|
||||
"summary": "Canonical revenue metric definitions",
|
||||
"score": 0.92
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,6 @@
|
|||
"ktx-sl",
|
||||
"ktx-wiki",
|
||||
"ktx-status",
|
||||
"ktx-agent",
|
||||
"ktx-dev"
|
||||
]
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue