seekdb-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

seekdb-cli — AI-Agent Database CLI

seekdb-cli — 面向AI Agent的数据库命令行工具

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

一款为AI Agent设计的命令行客户端。所有输出均为JSON结构，无状态，并内置安全防护机制。

Prerequisites

前置要求

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

bash

seekdb --version

检查seekdb-cli是否已安装（以下两个命令均可，它们共用同一入口）：

bash

seekdb --version

or, aligned with PyPI package name / for

which

-style checks:

或者，与PyPI包名对齐/用于

which

类检查：

seekdb-cli --version


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

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

```bash

seekdb-cli --version


若未安装，请根据你的环境选择安装方式：

**推荐方式 — pipx（全局可用且不污染系统Python环境）：**

```bash

Install pipx first if needed (Ubuntu/Debian)

若需要，先安装pipx（Ubuntu/Debian系统）

sudo apt install pipx && pipx ensurepath

Then install seekdb-cli

然后安装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" ...

pipx install seekdb-cli


**替代方式 — pip（适用于项目虚拟环境或未启用PEP 668的系统）：**

```bash
pip install seekdb-cli

Ubuntu 23.04+ / Debian 12+ 注意事项： 系统级直接使用
pip install
会被PEP 668阻止。请改用
pipx
— 它会创建独立环境，同时将**
seekdb
和
seekdb-cli
**保留在你的PATH中（二者为同一程序）。

本技能中的示例均使用

seekdb

，你可在所有地方替换为

seekdb-cli

。

嵌入式模式 vs 远程模式： 默认本地存储使用嵌入式模式（基于pyseekdb）。该模式要求系统为Linux（glibc ≥ 2.28）或macOS 15+；其他操作系统请使用远程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

undefined

DSN优先级（优先级从高到低）：

CLI中的
```
--dsn
```
参数（必须出现在子命令之前）
```
SEEKDB_DSN
```
环境变量
当前工作目录下的
```
.env
```
文件（需包含
```
SEEKDB_DSN=...
```
行）
```
~/.seekdb/config.env
```
文件
默认嵌入式路径：
```
embedded:~/.seekdb/seekdb.db
```

若无任何配置，则使用默认嵌入式路径 — 你可直接运行命令。若用户指定了特定DSN，请通过

--dsn

参数传入：

bash

undefined

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的远程模式（URL中包含查询字符串；需对用户名/密码中的特殊字符进行编码）

tls=skip-verify — encrypted, no certificate verification (common for self-signed servers)

tls=skip-verify — 加密连接，不验证证书（常用于自签名服务器）

seekdb --dsn "seekdb://user:pass@host:2881/db?tls=skip-verify" status

tls=required — encrypted with default OS CA verification

tls=required — 使用默认系统CA验证的加密连接

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)

嵌入式模式（路径为数据目录，不存在则自动创建；并非单个SQLite文件）

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

seekdb --dsn "embedded:./seekdb.db" status seekdb --dsn "embedded:~/.seekdb/seekdb.db?database=mydb" sql "SELECT 1"


DSN格式：
- **远程模式：** `seekdb://user:pass@host:port/db`
- **远程+TLS模式：** 追加`?tls=skip-verify|required|verify-ca|verify-identity`（或使用MySQL风格的`sslmode=`参数，如`REQUIRED`、`VERIFY_CA`）。可选查询参数：`ssl_ca`、`ssl_cert`、`ssl_key`、`ssl_key_password`。
- **嵌入式模式：** `embedded:<path>[?database=<db>]`（默认逻辑数据库名称：`test`）

Self-Description for AI Agents

面向AI Agent的自描述指南

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

运行

seekdb ai-guide

可获取包含所有命令、推荐工作流、安全特性及输出格式的结构化JSON指南。执行一次即可了解该CLI的全部功能。

bash

seekdb ai-guide

Recommended Workflow

Command Reference

命令参考

seekdb sql

Execute SQL statements. Default is read-only mode.

bash

undefined

执行SQL语句。默认处于只读模式。

bash

undefined

Read query

只读查询

seekdb sql "SELECT id, name FROM users LIMIT 10"

Read from file

从文件读取SQL

seekdb sql --file query.sql

Pipe or redirect (stdin read automatically when not a TTY; --stdin is optional)

通过管道或重定向输入（非TTY时自动读取标准输入；--stdin为可选参数）

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)

写入操作（需添加--write标志）

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 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"


**输出格式：**

```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}]}

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)"]}}

bash

seekdb schema describe orders

json

{"ok": true, "data": {"table": "orders", "comment": "订单表", "columns": [{"name": "id", "type": "int", "comment": "订单ID"}, {"name": "status", "type": "varchar(20)", "comment": "0=待支付, 1=已支付"}], "indexes": ["PRIMARY(id)", "idx_status(status)"]}}

seekdb schema dump

bash

seekdb schema dump

Returns all

CREATE TABLE

DDL statements.

bash

seekdb schema dump

返回所有

CREATE TABLE

DDL语句。

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"]
}}

生成表的统计摘要，不返回原始数据。有助于在编写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

undefined

通过分析列名模式（例如

user_id

→

users.id

）和类型兼容性，推断表间JOIN关系。

bash

undefined

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 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}]}

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).

bash

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

可选参数：

--dimension

-d

（默认值：384），

--distance

可选值为cosine | l2 | ip（默认值：cosine）。

seekdb collection delete

bash

seekdb collection delete my_docs

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.

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

和

distance

信息，则会在输出中展示。

seekdb query

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

bash

undefined

使用混合模式（默认）、语义（向量）模式或全文模式搜索集合。

bash

undefined

Hybrid search (default: semantic + fulltext, RRF ranking)

混合搜索（默认：语义搜索 + 全文搜索，RRF排序）

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)

限制结果数量（--limit或-n，默认值：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 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

undefined

通过ID或元数据过滤条件从集合中检索文档。

bash

undefined

Get by IDs

通过ID获取

seekdb get my_docs --ids "doc1,doc2"

Get by metadata filter (--limit or -n, default: 10)

通过元数据过滤获取（--limit或-n，默认值：10）

seekdb get my_docs --where '{"category": "tech"}' -n 20

undefined

seekdb get my_docs --where '{"category": "tech"}' -n 20

undefined

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

undefined

向集合中添加数据。必须指定一个数据源：

--file

、

--stdin

或

--data

。若集合不存在则会自动创建。

bash

undefined

From file (JSON array, JSONL, or CSV)

从文件读取（JSON数组、JSONL或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)

从标准输入读取（JSON数组或JSONL格式；可配合管道使用）

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.

echo '{"id":"1","document":"from pipe"}' | seekdb add my_docs --stdin some_script | seekdb add my_docs --stdin


**记录格式**：每条记录可包含`id`（可选）、`document`/`text`/`content`（需向量化的文本），其他字段将作为元数据。若记录中包含`embedding`字段，则会直接使用该向量。

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).

将集合数据导出到文件。

bash

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

可选参数：

--output

（必填），

--limit

-n

（默认值：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}]}

列出数据库中已注册的AI模型（来自

DBA_OB_AI_MODELS

/ DBMS_AI_SERVICE）。在远程模式和嵌入式模式下均可使用。

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

通过

DBMS_AI_SERVICE.CREATE_AI_MODEL

注册AI模型。需单独创建端点才能将其用于补全任务。

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>"

类型可选值：

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

删除AI模型。删除前需先删除所有使用该模型的端点。

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

创建或删除将AI模型绑定到URL和API密钥的端点（以便数据库调用该模型）。

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

支持的
--provider
值：

Provider	厂商
`siliconflow`	SiliconFlow（兼容OpenAI接口）
`openAI`	OpenAI
`deepseek`	DeepSeek（兼容OpenAI接口）
`aliyun-openAI`	阿里云（兼容OpenAI接口）
`aliyun-dashscope`	阿里云DashScope
`hunyuan-openAI`	腾讯混元（兼容OpenAI接口）

常见
--url
值（需使用具体接口URL，而非基础URL）：

厂商	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`	—	—
阿里云（OpenAI兼容）	`https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions`	`https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings`	—
腾讯混元	`https://api.hunyuan.cloud.tencent.com/v1/chat/completions`	`https://api.hunyuan.cloud.tencent.com/v1/embeddings`	—

完整参数说明：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}

使用数据库的

AI_COMPLETE

函数运行文本补全。需先注册completion类型的模型并创建对应的端点。在远程模式和嵌入式模式下均可使用。

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

输出面向AI Agent的结构化JSON指南，包含所有命令、参数、工作流及安全规则。执行一次即可了解该CLI的全部功能。

bash

seekdb ai-guide

seekdb status

bash

seekdb status

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

bash

seekdb status

返回CLI版本、服务器版本、数据库名称及连接状态。

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.

未添加

LIMIT

的查询会自动进行探测。若结果超过100行，执行将被阻止：

json

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

解决方法： 添加显式

LIMIT

子句后重试。

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.

写入操作（INSERT/UPDATE/DELETE）默认被阻止：

json

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

解决方法： 添加

--write

标志以启用写入操作。

即使添加了

--write

标志，不带

WHERE

子句的

DELETE

UPDATE

操作仍会被阻止。

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.

当出现SQL错误时，CLI会自动附加结构提示信息：

列不存在 → 返回该表的列列表及索引：

json

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

表不存在 → 返回可用表名：

json

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

解决方法： 使用结构提示信息修正SQL后重试。

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.

TEXT/BLOB字段默认会被截断为200字符，并标注原始长度：

json

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

如需获取完整内容，可使用

--no-truncate

参数。

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`

匹配敏感模式的列会被自动掩码处理：

模式	示例输出
phone/mobile/tel	`138****5678`
email	`z***@gmail.com`
password/secret/api_key	`******`
id_card / national_id / 类似字段	`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.

默认输出格式为JSON。可通过

--format

全局参数切换格式（该参数必须出现在子命令之前）：

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"

所有格式均支持非行数据（例如

schema tables

、

collection list

）。CSV和JSONL格式会自动检测

data

字段中的字典列表数据。

Exit Codes

退出码

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

代码	含义
0	执行成功
1	业务错误（SQL错误、连接错误等）
2	使用错误（缺少参数、无效选项等）

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/sql-history.jsonl

文件用于审计（SQL调用会包含经过脱敏的

sql

字段，如适用）：

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

Original

Translation

seekdb-cli — AI-Agent Database CLI

seekdb-cli — 面向AI Agent的数据库命令行工具

Prerequisites

前置要求

or, aligned with PyPI package name / for which-style checks:

或者，与PyPI包名对齐/用于which类检查：

Install pipx first if needed (Ubuntu/Debian)

若需要，先安装pipx（Ubuntu/Debian系统）

Then install seekdb-cli

然后安装seekdb-cli

Connection

连接配置

Remote mode

远程模式

Remote with TLS (query string on the URL; encode special characters in user/password)

带TLS的远程模式（URL中包含查询字符串；需对用户名/密码中的特殊字符进行编码）

tls=skip-verify — encrypted, no certificate verification (common for self-signed servers)

tls=skip-verify — 加密连接，不验证证书（常用于自签名服务器）

tls=required — encrypted with default OS CA verification

tls=required — 使用默认系统CA验证的加密连接

Embedded mode (path is a data directory, created if missing; not a single SQLite file)

嵌入式模式（路径为数据目录，不存在则自动创建；并非单个SQLite文件）

Self-Description for AI Agents

面向AI Agent的自描述指南

Recommended Workflow

推荐工作流

SQL Database Exploration

SQL数据库探索

Vector Collection Workflow

向量集合工作流

Command Reference

命令参考

seekdb sql

seekdb sql

Read query

只读查询

Read from file

从文件读取SQL

Pipe or redirect (stdin read automatically when not a TTY; --stdin is optional)

通过管道或重定向输入（非TTY时自动读取标准输入；--stdin为可选参数）

Explicit stdin (e.g. redirect into the command)

显式指定标准输入（例如将文件内容重定向到命令）

Include table schema in output

在输出中包含表结构

Disable large-field truncation

禁用大字段截断

Write operation (requires --write flag)

写入操作（需添加--write标志）

seekdb schema tables

seekdb schema tables

seekdb schema describe

seekdb schema describe

seekdb schema dump

seekdb schema dump

seekdb table profile

seekdb table profile

seekdb relations infer

seekdb relations infer

Infer all table relationships

推断所有表间关系

Infer for a specific table only

仅推断指定表的关系

seekdb collection list

seekdb collection list

seekdb collection create

seekdb collection create

seekdb collection delete

seekdb collection delete

seekdb collection info

seekdb collection info

seekdb query

seekdb query

Hybrid search (default: semantic + fulltext, RRF ranking)

混合搜索（默认：语义搜索 + 全文搜索，RRF排序）

Semantic (vector) only

仅语义（向量）搜索

Fulltext search

or, aligned with PyPI package name / for
`which`
-style checks:

或者，与PyPI包名对齐/用于
`which`
类检查：