Why not MCP?

Database CLI built for AI agents. One command to understand any database.

dbcli snap

users(id:INTEGER PK, name:TEXT, email:TEXT, role:TEXT) [1523]
  name:TEXT distinct=1488 sample=[Alice,Bob,Charlie]
  email:TEXT distinct=1523 nulls=0 sample=[[email protected],[email protected]]
  role:TEXT distinct=3 values=[user=1200,admin=300,moderator=23]
orders(id:INTEGER PK, user_id:INTEGER FK->users.id, amount:REAL, status:TEXT) [8491]
  user_id:INTEGER distinct=1102 min=1 max=1523 avg=761.5
  amount:REAL distinct=4853 min=0.99 max=2999.99 avg=87.34
  status:TEXT distinct=4 values=[delivered=5102,shipped=2001,pending=1200,cancelled=188]
---
users -< orders.user_id

Schema, row counts, column profiling, and relationships — in a single call. No other database tool does this.

Why not MCP?

AI agents already have shell access. MCP wastes hundreds of tokens per message on tool schemas and protocol overhead. dbcli is a simple CLI — zero context cost, zero setup, maximum speed.

Install

pip install dbcli

With optional database drivers:

pip install "dbcli[postgres]"      # PostgreSQL
pip install "dbcli[mysql]"         # MySQL
pip install "dbcli[mariadb]"       # MariaDB
pip install "dbcli[duckdb]"        # DuckDB
pip install "dbcli[clickhouse]"    # ClickHouse
pip install "dbcli[sqlserver]"     # SQL Server
pip install "dbcli[all]"           # all drivers

Quick start

# Connect
dbcli connect mydata.db
dbcli connect "postgresql://user:pass@localhost/mydb" --as pg

# Understand the database instantly
dbcli snap

# Query
dbcli q "SELECT * FROM users WHERE role = 'admin'"
dbcli q "SELECT * FROM users" -f json
dbcli q "SELECT * FROM users" --limit 0   # no limit (default: 100)

# Write
dbcli exec "INSERT INTO users (name) VALUES ('Alice')"
dbcli exec-file migrations/001.sql

# Multiple connections
dbcli connect staging.db --as staging
dbcli use staging
dbcli status

Commands

Supported databases

Supabase, Neon, CockroachDB, and any PostgreSQL-compatible database work with the postgres driver.

Agent-first design

Every output is optimized for LLM consumption, not human terminals:

• Compact schema — users(id:INTEGER PK, name:TEXT FK->accounts.id) instead of multi-line \d output
• One-shot context — snap replaces 5-10 exploration commands with one
• Data profiling — profile shows what data means (distributions, ranges, cardinality), not just types
• Default LIMIT 100 — protects agent context from large result sets
• Errors on stderr — error:<type>|<message> format, stdout stays clean for piping
• Semantic exit codes — 0=ok, 1=sql_error, 2=conn_error, 3=no_conn, 4=not_found, 5=usage
• Lazy imports — drivers loaded only when used, no errors if a package isn't installed

Give your agent database access

Claude Code

Add to CLAUDE.md:

Database access: use `dbcli` CLI.
- `dbcli snap` for full DB context
- `dbcli q "SQL"` to query (default limit 100)
- `dbcli exec "SQL"` to write

Cursor / Windsurf

Add to .cursorrules or .windsurfrules:

Database access: use `dbcli` CLI. Run `dbcli snap` for full context, `dbcli q "SQL"` to query, `dbcli exec "SQL"` to write.

Any agent with shell access (LangChain, CrewAI, OpenAI Agents SDK, etc.)

system_prompt += """
Database access: use `dbcli` CLI.
- `dbcli snap` for full DB context
- `dbcli q "SQL"` to query (default limit 100)
- `dbcli exec "SQL"` to write
"""

Or load the full skill for richer context:

from pathlib import Path
skill = Path("skills/dbcli/SKILL.md").read_text()
system_prompt = f"You have database access via dbcli CLI.\n\n{skill}"

CI/CD / Docker

Skip connect — set DBCLI_URL and query immediately:

export DBCLI_URL="postgresql://user:pass@host/db"
dbcli snap  # works without connect

Development

pip install -e ".[dev]"
pytest tests/ -v   # 94 tests