seekdb-cli 0.1.1

AI-Agent-friendly database CLI for seekdb / OceanBase

seekdb-cli

Command-line client for seekdb / OceanBase, built for AI agents. Default JSON output, stateless invocations, and a consistent error format make it easy for agents to run SQL, inspect schema, manage vector collections, and use in-database AI models reliably.

Why seekdb-cli

• Agent-friendly: Any agent that can run shell commands can use seekdb-cli via the seekdb command; output is JSON by default, and the seekdb ai-guide command provides a self-description of seekdb-cli usage for agents.
• Safety: Row limits, write guards, and masking reduce risk when agents or scripts operate on live data.
• Unified interface: One CLI for remote and embedded, SQL and vector collections, plus in-database AI, without interactive prompts or session state.

Features

• JSON by default: All commands emit structured JSON; use --format table|csv|jsonl for human-readable output.
• Row limits: LIMIT required when result exceeds 100 rows.
• Write safeguards: Writes require --write; DELETE/UPDATE without WHERE and DROP/TRUNCATE are disallowed.
• Sensitive-field masking: Columns such as phone, email, password, id_card are auto-masked in query results.
• Operation history: All commands are logged to ~/.seekdb/sql-history.jsonl; for SQL execution, the SQL text is logged with sensitive literals redacted.
• Database AI: Manage models and endpoints via DBMS_AI_SERVICE; use AI_COMPLETE for completion.

Requirements

• Python 3.11+
• seekdb / OceanBase (or any MySQL-protocol–compatible server)

Installation

pip install seekdb-cli

After installation, the seekdb command is available.

Connection

Works out of the box — with no configuration, seekdb-cli uses a default embedded database at ~/.seekdb/seekdb.db.

To connect to a remote server or use a different database path, create a global config file:

mkdir -p ~/.seekdb
# Remote
echo 'SEEKDB_DSN="seekdb://user:pass@host:port/database"' > ~/.seekdb/config.env

# Or embedded with a custom path
echo 'SEEKDB_DSN="embedded:/path/to/data"' > ~/.seekdb/config.env

Also supports --dsn CLI flag, SEEKDB_DSN environment variable, and project .env files, in decreasing priority.

Common commands

Command	Description
seekdb status	Connection status and version
seekdb schema tables	List all tables
seekdb schema describe <table>	Table structure (columns, types, indexes)
seekdb schema dump	Output DDL for all tables (to stdout)
seekdb table profile <table>	Table data profile (row count, nulls, distinct, min/max, candidate JOIN keys and time columns)
seekdb sql "<stmt>"	Execute SQL (read-only by default; use --write for writes; --with-schema adds table schema; --no-truncate keeps large fields intact)
seekdb relations infer [--table <t>]	Infer JOIN relationships between tables
seekdb collection list | create | delete | info	Vector collection management
seekdb query <coll> --text "<query>" [--mode semantic|fulltext|hybrid]	Search a collection
seekdb get <coll> [--ids ...] [--limit n]	Get documents by ID or condition
seekdb add <coll> (--file | --stdin | --data)	Add data to a collection
seekdb export <coll> --output <path>	Export collection data
seekdb ai model list | create | delete	AI model management (DBMS_AI_SERVICE)
seekdb ai model endpoint create | delete	Create or delete AI model endpoints
seekdb ai complete "<prompt>" --model <name>	In-database AI completion (AI_COMPLETE)
seekdb ai-guide	Print structured guide for AI agents (JSON)

Option order

--dsn and --format are global options and must appear before the subcommand:

seekdb --format table sql "SELECT * FROM t LIMIT 5"
seekdb --dsn "seekdb://root:@127.0.0.1:2881/test" schema tables