seekdb-cli

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

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

# 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):

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

1. --dsn on the CLI (must appear before the subcommand)
2. SEEKDB_DSN environment variable
3. .env in the current working directory (SEEKDB_DSN=... line)
4. ~/.seekdb/config.env
5. 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:

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