seekdb-cli — AI-Agent Database CLI

A command-line client designed for AI Agents. All output is JSON-structured, stateless, with built-in safety guardrails.

Prerequisites

Check if seekdb-cli is installed (either command works—they share the same entry point):

bash

seekdb --version
# or, aligned with PyPI package name / for `which`-style checks:
seekdb-cli --version

If not installed, choose the method that matches your environment:

Recommended — pipx (works globally without polluting system Python):

bash

# Install pipx first if needed (Ubuntu/Debian)
sudo apt install pipx && pipx ensurepath
# Then install seekdb-cli
pipx install seekdb-cli

Alternative — pip (when inside a project venv or on systems without PEP 668):

bash

pip install seekdb-cli

Note for Ubuntu 23.04+ / Debian 12+: Direct
pip install
at the system level is blocked by PEP 668. Use
pipx
instead — it creates an isolated environment while keeping seekdb
and seekdb-cli
on your PATH (same program).

Throughout this skill, examples use

seekdb

; you may substitute

seekdb-cli

everywhere.

Embedded vs remote: The default local store uses embedded mode (pyseekdb). That requires Linux (glibc ≥ 2.28) or macOS 15+; on other OSes, connect with a remote DSN:

seekdb --dsn "seekdb://user:pass@host:port/db" ...

Connection

DSN resolution (highest priority wins):

```
--dsn
```
on the CLI (must appear before the subcommand)
```
SEEKDB_DSN
```
environment variable
```
.env
```
in the current working directory (
```
SEEKDB_DSN=...
```
line)
```
~/.seekdb/config.env
```
Default
```
embedded:~/.seekdb/seekdb.db
```

With no config, the default embedded path applies — you can run commands directly. If the user gives a specific DSN, pass it with

--dsn

bash

# Remote mode
seekdb --dsn "seekdb://user:pass@host:port/db" schema tables

# Remote with TLS (query string on the URL; encode special characters in user/password)
# tls=skip-verify — encrypted, no certificate verification (common for self-signed servers)
seekdb --dsn "seekdb://user:pass@host:2881/db?tls=skip-verify" status
# tls=required — encrypted with default OS CA verification
seekdb --dsn "seekdb://user:pass@host:2881/db?tls=required" sql "SELECT 1"

# Embedded mode (path is a data directory, created if missing; not a single SQLite file)
seekdb --dsn "embedded:./seekdb.db" status
seekdb --dsn "embedded:~/.seekdb/seekdb.db?database=mydb" sql "SELECT 1"

DSN formats:

Remote:
```
seekdb://user:pass@host:port/db
```

Remote + TLS: append

?tls=skip-verify|required|verify-ca|verify-identity

(or the same values via MySQL-style

sslmode=

, e.g.

REQUIRED

VERIFY_CA

). Optional query params:

ssl_ca

ssl_cert

ssl_key

ssl_key_password

Embedded:
```
embedded:<path>[?database=<db>]
```
(default logical database name:
```
test
```
)

Self-Description for AI Agents

Run

seekdb ai-guide

to get a structured JSON guide of all commands, recommended workflow, safety features, and output format. Execute this once to learn the full CLI.

bash

seekdb ai-guide

Recommended Workflow

SQL Database Exploration

1. seekdb schema tables              → list all tables (name, column count, row count)
2. seekdb schema describe <table>    → get column names, types, indexes, comments
3. seekdb table profile <table>      → get data statistics (null ratios, distinct, min/max, top values)
4. seekdb relations infer            → infer JOIN relationships between tables
5. seekdb sql "SELECT ... LIMIT N"   → execute SQL with explicit LIMIT

Vector Collection Workflow

1. seekdb collection list            → list all collections
2. seekdb collection info <name>     → get collection details and preview
3. seekdb query <collection> --text "..." → search (default: hybrid = semantic + fulltext)

Command Reference

seekdb sql

Execute SQL statements. Default is read-only mode.

bash

# Read query
seekdb sql "SELECT id, name FROM users LIMIT 10"

# Read from file
seekdb sql --file query.sql

# Pipe or redirect (stdin read automatically when not a TTY; --stdin is optional)
echo "SELECT 1" | seekdb sql
# Explicit stdin (e.g. redirect into the command)
seekdb sql --stdin < query.sql

# Include table schema in output
seekdb sql "SELECT * FROM orders LIMIT 5" --with-schema

# Disable large-field truncation
seekdb sql "SELECT content FROM articles LIMIT 1" --no-truncate

# Write operation (requires --write flag)
seekdb sql --write "INSERT INTO users (name) VALUES ('Alice')"
seekdb sql --write "UPDATE users SET name = 'Bob' WHERE id = 1"
seekdb sql --write "DELETE FROM users WHERE id = 3"

Output format:

json

{"ok": true, "columns": ["id", "name"], "rows": [{"id": 1, "name": "Alice"}], "affected": 0, "time_ms": 12}

seekdb schema tables

bash

seekdb schema tables

json

{"ok": true, "data": [{"name": "users", "columns": 5, "rows": 1200}, {"name": "orders", "columns": 8, "rows": 50000}]}

seekdb schema describe

bash

seekdb schema describe orders

json

{"ok": true, "data": {"table": "orders", "comment": "Order table", "columns": [{"name": "id", "type": "int", "comment": "Order ID"}, {"name": "status", "type": "varchar(20)", "comment": "0=pending, 1=paid"}], "indexes": ["PRIMARY(id)", "idx_status(status)"]}}

seekdb schema dump

bash

seekdb schema dump

Returns all

CREATE TABLE

DDL statements.

seekdb table profile

Generate statistical summary of a table without returning raw data. Helps understand data distribution before writing SQL.

bash

seekdb table profile <table>

json

{"ok": true, "data": {
  "table": "orders",
  "row_count": 50000,
  "columns": [
    {"name": "id", "type": "int", "null_ratio": 0, "distinct": 50000, "min": 1, "max": 50000},
    {"name": "user_id", "type": "int", "null_ratio": 0, "distinct": 1200, "min": 1, "max": 1500},
    {"name": "amount", "type": "decimal(10,2)", "null_ratio": 0.02, "min": 0.5, "max": 9999.99},
    {"name": "status", "type": "varchar(20)", "null_ratio": 0, "distinct": 4, "top_values": ["paid", "pending", "refunded", "cancelled"]},
    {"name": "created_at", "type": "datetime", "null_ratio": 0, "min": "2024-01-01", "max": "2026-03-10"}
  ],
  "candidate_join_keys": ["user_id"],
  "candidate_time_columns": ["created_at"]
}}

seekdb relations infer

Infer JOIN relationships between tables by analyzing column name patterns (e.g.,

user_id

→

users.id

) and type compatibility.

bash

# Infer all table relationships
seekdb relations infer

# Infer for a specific table only
seekdb relations infer --table orders

json

{"ok": true, "data": [
  {"from": "orders.user_id", "to": "users.id", "confidence": "high"},
  {"from": "orders.product_id", "to": "products.id", "confidence": "high"},
  {"from": "order_items.order_id", "to": "orders.id", "confidence": "high"}
]}

seekdb collection list

bash

seekdb collection list

json

{"ok": true, "data": [{"name": "docs", "count": 1500}, {"name": "faq", "count": 200}]}

seekdb collection create

bash

seekdb collection create my_docs --dimension 384 --distance cosine
seekdb collection create my_docs -d 768 --distance l2

Options:

--dimension

-d

(default: 384),

--distance

cosine | l2 | ip (default: cosine).

seekdb collection delete

bash

seekdb collection delete my_docs

seekdb collection info

bash

seekdb collection info my_docs

json

{"ok": true, "data": {"name": "my_docs", "count": 1500, "dimension": 384, "distance": "cosine", "preview": {"ids": ["doc1", "doc2"], "documents": ["Hello world", "Test doc"], "metadatas": [{"category": "test"}, {}]}}}

dimension

and

distance

are included when available from the collection metadata.

seekdb query

Search a collection using hybrid (default), semantic (vector), or fulltext mode.

bash

# Hybrid search (default: semantic + fulltext, RRF ranking)
seekdb query my_docs --text "how to deploy seekdb"

# Semantic (vector) only
seekdb query my_docs --text "how to deploy seekdb" --mode semantic

# Fulltext search
seekdb query my_docs --text "deployment guide" --mode fulltext

# With metadata filter
seekdb query my_docs --text "performance tuning" --where '{"category": "tech"}'

# Limit results (--limit or -n, default: 10)
seekdb query my_docs --text "seekdb" -n 5

json

{"ok": true, "data": {"results": [
  {"id": "doc1", "score": 0.92, "document": "How to deploy seekdb...", "metadata": {"category": "tech"}},
  {"id": "doc2", "score": 0.85, "document": "seekdb performance tuning...", "metadata": {"category": "tech"}}
], "count": 2}, "time_ms": 35}

seekdb get

Retrieve documents from a collection by IDs or metadata filter.

bash

# Get by IDs
seekdb get my_docs --ids "doc1,doc2"

# Get by metadata filter (--limit or -n, default: 10)
seekdb get my_docs --where '{"category": "tech"}' -n 20

seekdb add

Add data to a collection. Exactly one source is required:

--file

--stdin

, or

--data

. The collection is auto-created if it does not exist.

bash

# From file (JSON array, JSONL, or CSV)
seekdb add my_docs --file data.jsonl
seekdb add my_docs --file articles.csv --vectorize-column content

# Inline: single object or array
seekdb add my_docs --data '{"id":"1","document":"Hello world","metadata":{"source":"cli"}}'
seekdb add my_docs --data '[{"id":"a","document":"Doc A"},{"id":"b","document":"Doc B"}]'

# From stdin (JSON array or JSONL; use with pipes)
echo '{"id":"1","document":"from pipe"}' | seekdb add my_docs --stdin
some_script | seekdb add my_docs --stdin

Record format: Each record may have

id

(optional),

document

text

content

(text to vectorize), and any other fields become metadata. If

embedding

is present, it is used directly.

seekdb export

Export collection data to a file.

bash

seekdb export my_docs --output backup.json
seekdb export my_docs --output backup.jsonl -n 5000

Options:

--output

(required),

--limit

-n

(default: 10000).

seekdb ai model list

List AI models registered in the database (from

DBA_OB_AI_MODELS

/ DBMS_AI_SERVICE). Works in both remote and embedded mode.

bash

seekdb ai model list

json

{"ok": true, "data": [{"name": "my_llm", "type": "completion", "model_name": "THUDM/GLM-4-9B-0414", "model_id": 1}]}

seekdb ai model create

DBMS_AI_SERVICE.CREATE_AI_MODEL

. Create an endpoint separately to use it for completion.

bash

seekdb ai model create my_llm --type completion --model "THUDM/GLM-4-9B-0414"
seekdb ai model create my_embed --type dense_embedding --model "BAAI/bge-m3"
seekdb ai model create my_rerank --type rerank --model "<rerank_model>"

Types:

completion

dense_embedding

rerank

seekdb ai model delete

Drop an AI model. Drop any endpoints that use it first.

bash

seekdb ai model delete my_llm

seekdb ai model endpoint create / delete

Create or drop an endpoint that binds an AI model to a URL and API key (so the database can call the model).

bash

seekdb ai model endpoint create my_ep my_llm \
  --url "https://api.siliconflow.cn/v1/chat/completions" \
  --access-key "<YOUR_API_KEY>" \
  --provider siliconflow

seekdb ai model endpoint delete my_ep

Supported
--provider
values:

Provider	Vendor
`siliconflow`	SiliconFlow (OpenAI-compatible)
`openAI`	OpenAI
`deepseek`	DeepSeek (OpenAI-compatible)
`aliyun-openAI`	Alibaba Cloud (OpenAI-compatible)
`aliyun-dashscope`	Alibaba Cloud DashScope
`hunyuan-openAI`	Tencent Hunyuan (OpenAI-compatible)

Common
--url
values (use the specific interface URL, not the base URL):

Vendor	completion	embedding	rerank
SiliconFlow	`https://api.siliconflow.cn/v1/chat/completions`	`https://api.siliconflow.cn/v1/embeddings`	`https://api.siliconflow.cn/v1/rerank`
DeepSeek	`https://api.deepseek.com/chat/completions`	—	—
Alibaba (OpenAI)	`https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions`	`https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings`	—
Tencent Hunyuan	`https://api.hunyuan.cloud.tencent.com/v1/chat/completions`	`https://api.hunyuan.cloud.tencent.com/v1/embeddings`	—

Full parameter spec: CREATE_AI_MODEL_ENDPOINT

seekdb ai complete

Run text completion using the database

AI_COMPLETE

function. Requires a registered completion model and an endpoint. Supported in both remote and embedded mode.

bash

seekdb ai complete "Summarize this table structure" --model my_llm

json

{"ok": true, "data": {"model": "my_llm", "response": "The table has..."}, "time_ms": 1200}

seekdb ai-guide

Output a structured JSON guide for AI Agents containing all commands, parameters, workflow, and safety rules. Execute once to learn the full CLI.

bash

seekdb ai-guide

seekdb status

bash

seekdb status

Returns CLI version, server version, database name, and connectivity.

Safety Features

Row Protection

Queries without

LIMIT

are automatically probed. If result exceeds 100 rows, execution is blocked:

json

{"ok": false, "error": {"code": "LIMIT_REQUIRED", "message": "Query returns more than 100 rows. Please add LIMIT to your SQL."}}

Action: Add an explicit

LIMIT

clause and retry.

Write Protection

Write operations (INSERT/UPDATE/DELETE) are blocked by default:

json

{"ok": false, "error": {"code": "WRITE_NOT_ALLOWED", "message": "Write operations require --write flag."}}

Action: Add

--write

flag to enable write operations.

Even with

--write

DELETE

UPDATE

without a

WHERE

clause are blocked.

Error Auto-Correction

On SQL errors, the CLI automatically attaches schema hints:

Column not found → returns the table's column list and indexes:

json

{"ok": false, "error": {"code": "SQL_ERROR", "message": "Unknown column 'username'"}, "schema": {"table": "users", "columns": ["id", "name", "email"], "indexes": ["PRIMARY(id)"]}}

Table not found → returns available table names:

json

{"ok": false, "error": {"code": "SQL_ERROR", "message": "Table 'user' does not exist"}, "schema": {"tables": ["users", "orders", "products"]}}

Action: Use the schema info to correct the SQL and retry.

Large Field Truncation

TEXT/BLOB fields are truncated to 200 characters by default, with original length noted:

json

{"content": "First 200 characters of content...(truncated, 8520 chars)"}

Use

--no-truncate

to get full content when needed.

Sensitive Field Masking

Columns matching sensitive patterns are automatically masked:

Pattern	Example Output
phone/mobile/tel	`138****5678`
email	`z***@gmail.com`
password/secret/api_key	`******`
id_card / national_id / similar	`110***********1234`

Output Formats

Default is JSON. Switch with

--format

(global option; must appear before the subcommand):

bash

seekdb --format table sql "SELECT id, name FROM users LIMIT 5"
seekdb --format csv sql "SELECT id, name FROM users LIMIT 5"
seekdb --format jsonl sql "SELECT id, name FROM users LIMIT 5"

All formats now work with non-row data (e.g.,

schema tables

collection list

). CSV and JSONL will auto-detect list-of-dict data in the

data

field.

Exit Codes

Code	Meaning
0	Success
1	Business error (SQL error, connection error, etc.)
2	Usage error (missing arguments, invalid options)

Operation Logging

All commands are logged to

~/.seekdb/sql-history.jsonl

for audit (SQL invocations include a redacted

sql

field when applicable):

json

{"ts": "2026-03-12T14:23:01", "command": "sql", "sql": "SELECT id FROM users LIMIT 10", "ok": true, "rows": 10, "time_ms": 12}

seekdb-cli

NPX Install

Tags

SKILL.md Content

seekdb-cli — AI-Agent Database CLI

Prerequisites

Connection

Self-Description for AI Agents

Recommended Workflow

SQL Database Exploration

Vector Collection Workflow

Command Reference

seekdb sql

seekdb schema tables

seekdb schema describe

seekdb schema dump

seekdb table profile

seekdb relations infer

seekdb collection list

seekdb collection create

seekdb collection delete

seekdb collection info

seekdb query

seekdb get

seekdb add

seekdb export

seekdb ai model list

seekdb ai model create

seekdb ai model delete

seekdb ai model endpoint create / delete

seekdb ai complete

seekdb ai-guide

seekdb status

Safety Features

Row Protection

Write Protection

Error Auto-Correction

Large Field Truncation

Sensitive Field Masking

Output Formats

Exit Codes

Operation Logging