Metadata-Version: 2.4
Name: seekdb-cli
Version: 0.1.6
Summary: AI-Agent-friendly database CLI for seekdb / OceanBase
Author: David Zhang
License: MIT
Project-URL: Homepage, https://github.com/oceanbase/seekdb-ecology-plugins
Project-URL: Repository, https://github.com/oceanbase/seekdb-ecology-plugins
Project-URL: Issues, https://github.com/oceanbase/seekdb-ecology-plugins/issues
Keywords: seekdb,database,cli,ai-agent,oceanbase
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: pymysql>=1.0
Requires-Dist: pyseekdb>=0.1
Requires-Dist: openai>=1.0

# 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

```bash
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:

```bash
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 (default: **hybrid**) |
| `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:

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