Move faster. Stay in control.

Name the outcome. Your agent delivers.
dbcli keeps the data safe.

From analysis to interactive reports, your agent gets database work done while dbcli verifies structure, protects sensitive data, and enforces clear boundaries.

See how it works View on GitHub

Example · You and your agent

Find the plan with the highest churn this month and turn it into a chart.
Done. Enterprise-plan churn rose 8.4%, and the shareable report is ready.

dbcli behind the scenes

  • Verifies the actual schema
  • Masks sensitive fields
  • Limits query scope
  • Verifies and records results

A real workflow

One request. Five dependable steps.

Your agent never guesses its way into the data. dbcli connects schema checks, guardrails, execution, and verification in one repeatable flow.

Describe the outcome

State the question and the deliverable you want in plain language.

your request

Confirm structure

Read the real schema first, so fields and types are never guessed.

schema

Apply guardrails

Enforce blacklists, permission levels, and result limits.

blacklist · permission

Execute and verify

Run the query, check the result, and get guided recovery when something fails.

query · recover

Deliver the result

Package the conclusion as a shareable, interactive report.

query --ui
See what the agent ran behind the scenes 
dbcli blacklist list
dbcli schema subscriptions --format json
dbcli query "WITH months AS (SELECT date_trunc('month', CURRENT_DATE) AS month_start UNION ALL SELECT date_trunc('month', CURRENT_DATE) - INTERVAL '1 month'), rates AS (SELECT m.month_start, s.plan, COUNT(*) FILTER (WHERE s.cancelled_at >= m.month_start AND s.cancelled_at < m.month_start + INTERVAL '1 month')::numeric / NULLIF(COUNT(*) FILTER (WHERE s.created_at < m.month_start AND (s.cancelled_at IS NULL OR s.cancelled_at >= m.month_start)), 0) * 100 AS churn_rate FROM months m CROSS JOIN subscriptions s GROUP BY m.month_start, s.plan), compared AS (SELECT plan, churn_rate, LAG(churn_rate) OVER (PARTITION BY plan ORDER BY month_start) AS previous_rate, month_start FROM rates) SELECT plan, ROUND(churn_rate, 1) AS churn_rate_pct, ROUND((churn_rate - previous_rate) / NULLIF(previous_rate, 0) * 100, 1) AS increase_pct FROM compared WHERE month_start = date_trunc('month', CURRENT_DATE) ORDER BY increase_pct DESC" --recovery --ui
dbcli recover

Fast without skipping steps

Turn back-and-forth work into one delivery

01

One request, end to end

Move from query to analysis to report without directing every command.

task workflow
02

Reuse schema and query knowledge

Confirm the schema, then discover and reuse queries your team has saved.

schema · queries
03

Diagnose, then deliver

Failures come with recovery guidance; successful results become interactive reports.

recover · query --ui

Layered protection

Safety is a boundary at every step

Credential isolation

Agents use fixed connection profiles without reading or exposing database passwords.

profile

Sensitive-field blacklist

Fields and tables are protected before query results can expose sensitive content.

blacklist

Permissions and previews

Permission levels limit actions, while dry runs preview writes before execution.

permission · --dry-run

Verification, recovery, and audit

Verify outcomes, offer safe recovery steps, and retain an operational record.

verify · recover · audit
A real recording: a Claude Code agent uses dbcli on a request that both reads and writes. The query omits the blacklisted column, the write is refused because the connection is query-only, and the agent does not raise its own permission. Waiting segments are sped up, and the security notice is briefly paused.

Keep the tools you already use

One workflow for your databases and agents

Databases

PostgreSQLMySQLMariaDB MongoDBRedisElasticsearch

AI Agent

Claude CodeCodexCursor Gemini CLIGitHub CopilotOpenCode Antigravity

Quickstart

Put dbcli in your agent's toolbox

Plugin or Skill is the most direct agent integration. You can also initialize the CLI on its own.

Recommended · Plugin / Skill

Install the complete operating guide

Install the plugin from the Claude Code marketplace, or install the Codex skill after initializing the CLI.

/plugin marketplace add CarlLee1983/dbcli
/plugin install dbcli@carllee1983-dbcli
dbcli skill --install codex

The Skill also supports Claude Code, Cursor, GitHub Copilot, Gemini CLI, Antigravity, and Windsurf. OpenCode works with dbcli but currently has no dedicated selector; do not substitute another platform's install command.

Alternative · CLI

Create a connection profile first

Run the setup wizard with bunx. Your agent can then use the same safe workflow through the Skill.

bunx @carllee1983/dbcli init

After initialization, install the integration for your agent. See the user guide for full platform details.

Use-case guides GitHub source Full English documentation Traditional Chinese

FAQ

Frequently asked questions

I don't write SQL. Is dbcli still for me?

Yes. Ask your agent to work with data in plain language. dbcli has it confirm the real structure with schema, then reuse expert queries from saved queries and task packs. You only need to review the result, not decipher the SQL in between.

Could an agent accidentally delete my data?

The default permission is query-only, which cannot even INSERT. At data-admin, dbcli requires and evaluates an equality-based WHERE grammar for DELETE, rejects unbounded writes, and recommends a dry run first. DDL adds three more gates: admin, --execute, and --force for DROP.

Which databases are supported?

MySQL, PostgreSQL, MariaDB, MongoDB, Redis, and Elasticsearch. A project can hold multiple named connections—for staging, production, or separate tenants—with independent credentials, permissions, and schema caches.

How is this different from using an MCP database server directly?

dbcli builds permissions and data protection into the database operations layer: credential isolation, blacklist masking, permission tiers, dry runs, audit, and recovery are ready to use. It is not tied to one agent protocol or editor, and people can use the same workflow in a terminal. Use an MCP server when its conversational interface and policy model meet your needs; see the visual tool-choice guide for the trade-offs.

How do teams collaborate?

Saved queries can live in .dbcli-shared/ and travel through git. Use --use-env-refs for credentials so every teammate and CI pipeline supplies its own environment variables while the repository remains free of plaintext passwords.

Will dbcli give my database password to the agent?

No. Connection profiles isolate credentials. The agent runs fixed dbcli commands and never needs to read or return the password.

Is dbcli read-only?

No. Available operations depend on the configured permission level. Write workflows can be previewed with a dry run and then executed only with explicit authorization.

Should I use the Plugin or skill --install?

Choose the Plugin when your agent supports a plugin marketplace for centralized installation and updates. If dbcli is already installed globally, or you prefer repository- or user-level guidance, use dbcli skill --install <platform>.

Will the agent start guessing when a query fails?

The workflow confirms the schema first. If a command with recovery enabled fails, dbcli creates a recovery plan so the agent can inspect it and apply only safe remediation steps.