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 (the seekdb-cli command is the same entry point, useful for which seekdb-cli–style checks); 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 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. The same program is also installed as seekdb-cli (e.g. for tooling that probes the binary name matching the PyPI package).

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.

TLS (remote DSN only): set it in the URL query string — for example seekdb://user:pass@host:2881/db?tls=skip-verify (encrypted, no cert verification — typical for self-signed) or ?tls=required (encrypted with default CA verification). PEM paths: ssl_ca, ssl_cert, ssl_key. That is enough to define the connection; no separate TLS env vars are required.

Common commands

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