dbcli — Database CLI for AI Agents

Languages: English | 繁體中文

A unified database CLI tool that enables AI agents (Claude Code, Gemini, Copilot, Cursor) to safely query, discover, and operate on databases.

Core Value: AI agents can safely and intelligently access project databases through a single, permission-controlled CLI tool with sensitive data protection.

Internationalization (i18n)

dbcli supports multiple languages via the DBCLI_LANG environment variable:

# English (default)
dbcli init

# Traditional Chinese
DBCLI_LANG=zh-TW dbcli init

# Or set in .env
export DBCLI_LANG=zh-TW
dbcli init

Supported languages:

• en — English (default)
• zh-TW — Traditional Chinese (Taiwan)

All messages, help text, error messages, and command output respond to the language setting automatically.

Quick Start

Installation

Global Installation (Recommended)

npm install -g @carllee1983/dbcli

Zero-Install (No Installation Needed)

npx @carllee1983/dbcli init
npx @carllee1983/dbcli query "SELECT * FROM users"

Update

# Self-update (recommended)
dbcli upgrade

# Or via npm
npm update -g @carllee1983/dbcli

Development Installation

git clone <repository>
cd dbcli
bun install
bun run dev -- --help

First Steps

# Initialize project with database connection
dbcli init

# List available tables
dbcli list

# View table structure
dbcli schema users

# Query data
dbcli query "SELECT * FROM users"

# Generate AI agent skill
dbcli skill --install claude

---

API Reference

Commands

dbcli init

Initialize a new dbcli project with database connection configuration.

Usage:

dbcli init [OPTIONS]

Options:

• --system <type> — Database system: postgresql, mysql, mariadb
• --host <host> — Database host
• --port <port> — Database port
• --user <user> — Database user
• --password <pass> — Database password
• --name <db> — Database name
• --permission <level> — Permission level: query-only, read-write, data-admin, admin
• --use-env-refs — Store environment variable references instead of actual values in config
• --env-host <var> — Env var name for host (with --use-env-refs)
• --env-port <var> — Env var name for port (with --use-env-refs)
• --env-user <var> — Env var name for user (with --use-env-refs)
• --env-password <var> — Env var name for password (with --use-env-refs)
• --env-database <var> — Env var name for database (with --use-env-refs)
• --skip-test — Skip connection test
• --no-interactive — Non-interactive mode (requires all options)
• --force — Overwrite existing config without confirmation

Behavior:

• Reads .env file if present (auto-fills DATABASE_URL, DB_* variables)
• Prompts for missing values (host, port, user, password, database name, permission level)
• Creates .dbcli JSON config file in project root
• Tests database connection before saving

Examples:

# Interactive initialization
dbcli init

# With environment variables pre-set
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
dbcli init

# Specify permission level
echo "PERMISSION_LEVEL=admin" >> .env && dbcli init

# Store env var references instead of values (interactive)
dbcli init --use-env-refs

# Store env var references (non-interactive)
dbcli init --use-env-refs --system mysql \
  --env-host DB_HOST --env-port DB_PORT \
  --env-user DB_USER --env-password DB_PASSWORD \
  --env-database DB_DATABASE \
  --no-interactive

--use-env-refs: When enabled, the config stores environment variable names (e.g., {"$env": "DB_HOST"}) instead of actual values. This avoids writing sensitive credentials into the config file, making it suitable for multi-environment deployments and CI/CD pipelines. At connection time, dbcli automatically reads the actual values from the referenced environment variables.

---

dbcli list

List all tables in the connected database.

Usage:

dbcli list [OPTIONS]

Options:

• --format json — Output as JSON instead of ASCII table

Examples:

# Table format (human-readable)
dbcli list

# JSON format (for AI parsing)
dbcli list --format json

# Pipe to tools
dbcli list --format json | jq '.data[].name'

---

dbcli schema [table]

Show table structure (columns, types, constraints, foreign keys).

Usage:

dbcli schema [table]
dbcli schema                 # Scan entire database and update .dbcli
dbcli schema users           # Show structure of 'users' table

Options:

• --format json — Output as JSON
• --refresh — Detect and update schema changes incrementally (requires --force for approval)
• --reset — Clear all existing schema data and re-fetch from database (useful after switching DB connections)
• --force — Skip confirmation for schema refresh/overwrite/reset

Examples:

# Show users table structure
dbcli schema users

# JSON output with full metadata
dbcli schema users --format json

# Update schema with new tables (incremental)
dbcli schema --refresh --force

# Clear and re-fetch all schema (after switching DB)
dbcli schema --reset --force

# Scan entire database
dbcli schema

---

dbcli query "SQL"

Execute SQL query and return results.

Usage:

dbcli query "SELECT * FROM users"

Options:

• --format json|table|csv — Output format (default: table)
• --output file — Write to file instead of stdout

Behavior:

• Enforces permission-based restrictions (Query-only mode blocks INSERT/UPDATE/DELETE)
• Auto-limits results to 1000 rows in Query-only mode (notification shown)
• Returns structured results with metadata (row count, execution time)

Examples:

# Table output (human-readable)
dbcli query "SELECT * FROM users"

# JSON (for AI/programmatic parsing)
dbcli query "SELECT * FROM users" --format json

# CSV export
dbcli query "SELECT * FROM users" --format csv --output users.csv

# Pipe to other tools
dbcli query "SELECT * FROM products" --format json | jq '.data[] | .name'

# Large result sets (paginate with LIMIT/OFFSET)
dbcli query "SELECT * FROM users LIMIT 100 OFFSET 0"

---

dbcli insert [table] (Requires Read-Write or Admin permission)

Insert data into table.

Usage:

dbcli insert users --data '{"name": "Alice", "email": "alice@example.com"}'

Options:

• --data JSON — Row data as JSON object (REQUIRED)
• --dry-run — Show SQL without executing
• --force — Skip confirmation

Behavior:

• Validates JSON format
• Generates parameterized SQL (prevents SQL injection)
• Shows confirmation prompt before inserting (unless --force used)

Examples:

# Insert single row
dbcli insert users --data '{"name": "Bob", "email": "bob@example.com"}'

# Preview SQL without executing
dbcli insert users --data '{"name": "Charlie"}' --dry-run

# Skip confirmation
dbcli insert users --data '{"name": "Diana"}' --force

---

dbcli update [table] (Requires Read-Write or Admin permission)

Update existing rows.

Usage:

dbcli update users --where "id=1" --set '{"name": "Alice Updated"}'

Options:

• --where condition — WHERE clause (REQUIRED, e.g., "id=1 AND status='active'")
• --set JSON — Updated columns as JSON object (REQUIRED)
• --dry-run — Show SQL without executing
• --force — Skip confirmation

Examples:

# Update single row
dbcli update users --where "id=1" --set '{"name": "Alice"}'

# Update multiple rows
dbcli update users --where "status='inactive'" --set '{"status":"active"}'

# Preview SQL
dbcli update users --where "id=1" --set '{"name": "Bob"}' --dry-run

# Skip confirmation
dbcli update users --where "id=2" --set '{"email": "new@example.com"}' --force

---

dbcli delete [table] (Requires Admin permission only)

Delete rows (admin-only for safety).

Usage:

dbcli delete users --where "id=1" --force

Options:

• --where condition — WHERE clause (REQUIRED)
• --dry-run — Show SQL without executing
• --force — Required to actually delete (safety guard)

Examples:

# Delete single row (requires --force)
dbcli delete users --where "id=1" --force

# Preview deletion
dbcli delete products --where "status='deprecated'" --dry-run

# Delete multiple rows
dbcli delete orders --where "created_at < '2020-01-01'" --force

---

dbcli export "SQL"

Export query results to file.

Usage:

dbcli export "SELECT * FROM users" --format json --output users.json

Options:

• --format json|csv — Output format
• --output file — Write to file (default: stdout for piping)

Behavior:

• Query-only permission limited to 1000 rows per export
• Generates RFC 4180 compliant CSV
• Creates well-formed JSON arrays

Examples:

# Export to JSON
dbcli export "SELECT * FROM users" --format json --output users.json

# Export to CSV
dbcli export "SELECT * FROM orders" --format csv --output orders.csv

# Pipe compressed export
dbcli export "SELECT * FROM products" --format csv | gzip > products.csv.gz

# Combine with query tools
dbcli export "SELECT * FROM users WHERE active=true" --format json | jq '.data | length'

---

dbcli skill

Generate or install AI agent skill documentation.

Usage:

dbcli skill                           # Output skill to stdout
dbcli skill --output SKILL.md         # Write to file
dbcli skill --install claude          # Install to Claude Code config
dbcli skill --install gemini          # Install to Gemini CLI
dbcli skill --install copilot         # Install to GitHub Copilot
dbcli skill --install cursor          # Install to Cursor IDE

Behavior:

• Dynamically generates SKILL.md from CLI introspection
• Filters commands by permission level (Query-only hides write commands)
• Supports multiple output modes: stdout, file, platform installation

Examples:

# Generate skill for Claude Code
dbcli skill --install claude

# Generate skill manually for documentation
dbcli skill > ./docs/SKILL.md

# View generated skill (stdout)
dbcli skill

# Install for all platforms
dbcli skill --install claude && \
dbcli skill --install gemini && \
dbcli skill --install copilot && \
dbcli skill --install cursor

---

dbcli blacklist

Manage the data access blacklist to block AI agents from accessing sensitive tables or columns.

Usage:

dbcli blacklist list
dbcli blacklist table add <table>
dbcli blacklist table remove <table>
dbcli blacklist column add <table>.<column>
dbcli blacklist column remove <table>.<column>

Subcommands:

Subcommand	Description
dbcli blacklist list	Show current blacklist (tables and columns)
dbcli blacklist table add <table>	Add table to blacklist (blocks all operations)
dbcli blacklist table remove <table>	Remove table from blacklist
dbcli blacklist column add <table>.<column>	Add column to blacklist (omitted from SELECT results)
dbcli blacklist column remove <table>.<column>	Remove column from blacklist

Behavior:

• Table blacklist blocks all operations on that table (query, insert, update, delete)
• Column blacklist silently omits columns from SELECT results and shows a security notification
• Blacklist rules are stored in .dbcli and apply to all permission levels
• Override for admin use via DBCLI_OVERRIDE_BLACKLIST=true environment variable

Examples:

# View current blacklist
dbcli blacklist list

# Block all access to sensitive tables
dbcli blacklist table add audit_logs
dbcli blacklist table add secrets_vault

# Hide sensitive columns from query results
dbcli blacklist column add users.password_hash
dbcli blacklist column add users.ssn

# Remove a table from blacklist
dbcli blacklist table remove audit_logs

# Remove a column from blacklist
dbcli blacklist column remove users.ssn

# Override blacklist (admin use only)
DBCLI_OVERRIDE_BLACKLIST=true dbcli query "SELECT * FROM secrets_vault"

---

dbcli doctor

Run diagnostic checks on environment, configuration, connection, and data.

dbcli doctor                    # Colored text output
dbcli doctor --format json      # JSON output for AI agents

Checks:

• Environment: Bun version compatibility, dbcli version (compares with npm registry)
• Configuration: Config file exists/valid, permission level, blacklist completeness
• Connection & Data: Database connectivity, schema cache freshness (> 7 days warning), large table warnings (> 1M rows)

Options: --format <text|json> Exit code: 0 = all pass or warnings only, 1 = errors found

---

dbcli completion [shell]

Generate shell completion scripts for tab auto-complete.

dbcli completion bash            # Output bash completion to stdout
dbcli completion zsh             # Output zsh completion to stdout
dbcli completion fish            # Output fish completion to stdout
dbcli completion --install       # Auto-detect shell and install to rc file
dbcli completion --install zsh   # Install for specific shell

Supported shells: bash, zsh, fish

---

dbcli upgrade

Check for updates and self-upgrade dbcli.

dbcli upgrade                   # Check and upgrade if newer version available
dbcli upgrade --check           # Only check, do not upgrade

Options: --check — check only, don't install Background check: dbcli silently checks npm registry once per 24 hours. If a newer version is found, a hint is shown after command output.

---

Global Options

All commands support these global options:

Flag	Description
--config <path>	Path to .dbcli config file (default: .dbcli)
-v, --verbose	Increase verbosity (-v verbose, -vv debug)
-q, --quiet	Suppress non-essential output
--no-color	Disable colored output (respects NO_COLOR env var)

---

Permission Model

dbcli implements a coarse-grained permission system with three levels. Permission level is set during dbcli init and stored in .dbcli config file. The blacklist system works alongside permissions to provide fine-grained protection for sensitive tables and columns (see Data Access Control).

Permission Levels

Level	Allowed Commands	Blocked Commands	Use Case
Query-only	init, list, schema, query, export (limited to 1000 rows)	insert, update, delete	Read-only AI agents, data analysts, reporting
Read-Write	+ insert, update	delete	Application developers, content managers
Admin	All commands	—	Database administrators, schema modifications

Configuration

Permission level is set during initialization:

dbcli init
# Prompts: "Permission level? (query-only / read-write / admin)"
# Stored in ~/.dbcli as: "permissionLevel": "query-only"

Permission-Based Examples

Query-Only Mode (AI Agent)

# Allowed: Read operations
dbcli query "SELECT * FROM users"
dbcli schema users
dbcli export "SELECT * FROM orders" --format json

# Blocked: Write operations
dbcli insert users --data '{...}'  # ERROR: Permission denied
dbcli delete users --where "id=1"  # ERROR: Permission denied

Read-Write Mode (Application Developer)

# Allowed: Read + write
dbcli query "SELECT * FROM users"
dbcli insert users --data '{"name": "Alice"}'
dbcli update users --where "id=1" --set '{"name": "Bob"}'

# Blocked: Delete (safety feature)
dbcli delete users --where "id=1"  # ERROR: Admin only

Admin Mode (Database Administrator)

# Allowed: Everything
dbcli query "SELECT * FROM users"
dbcli insert users --data '{"name": "Eve"}'
dbcli update users --where "id=1" --set '{"status": "active"}'
dbcli delete users --where "id=1" --force  # Only Admin can delete

Best Practices

• AI Agents: Use Query-only for read-only scenarios; prevents accidental data loss
• Applications: Use Read-Write for normal CRUD operations; prevents DROP TABLE accidents
• Maintenance: Use Admin only for schema changes, bulk deletes, or emergency operations
• Principle of Least Privilege: Assign minimum permission level needed for each use case

---

Data Access Control

dbcli provides a blacklist system that works alongside the permission model to prevent AI agents from accessing sensitive tables or columns, regardless of their permission level.

Table-Level Blacklist

Blocking a table prevents all operations on it — queries, inserts, updates, and deletes are all refused with a clear error message.

# Block a table
dbcli blacklist table add secrets_vault

# Attempting access is blocked at all permission levels
dbcli query "SELECT * FROM secrets_vault"
# ERROR: Table 'secrets_vault' is blacklisted

Column-Level Blacklist

Blacklisted columns are silently omitted from SELECT results. A security notification is shown in the output so the agent is aware that the result set has been filtered.

# Blacklist sensitive columns
dbcli blacklist column add users.password_hash
dbcli blacklist column add users.ssn

# Query returns all other columns; notification shown
dbcli query "SELECT * FROM users"
# [Security] Columns omitted by blacklist: password_hash, ssn

Security Notifications

Whenever a blacklist rule filters query output, dbcli appends a notification line to the result. This ensures AI agents do not silently operate on incomplete data without awareness.

Override via Environment Variable

Administrators can bypass the blacklist for emergency or maintenance operations using the DBCLI_OVERRIDE_BLACKLIST=true environment variable:

DBCLI_OVERRIDE_BLACKLIST=true dbcli query "SELECT * FROM secrets_vault"

This override is logged and should only be used by administrators when necessary.

Blacklist Configuration

Blacklist rules are stored in the .dbcli config file and can also be set manually:

{
  "blacklist": {
    "tables": ["audit_logs", "secrets_vault"],
    "columns": {
      "users": ["password_hash", "ssn"]
    }
  }
}

Blacklist vs. Permissions

The blacklist and permission model are complementary layers of access control:

Layer	Controls	Applies To
Permission Model	Operation type (read/write/delete)	All tables
Blacklist	Specific tables and columns	Targeted sensitive data

A Query-only agent cannot write to any table, and also cannot read blacklisted tables or columns — both restrictions apply simultaneously.

---

AI Integration Guide

dbcli generates AI-consumable skill documentation and can be integrated into your favorite AI development tools.

Quick Start

Generate skill for your preferred platform:

# Claude Code (Anthropic's VS Code extension)
dbcli skill --install claude

# Gemini CLI (Google's command-line AI)
dbcli skill --install gemini

# GitHub Copilot CLI
dbcli skill --install copilot

# Cursor IDE (AI-native editor)
dbcli skill --install cursor

After installation, the AI agent will have access to dbcli commands and can use them to query, insert, update, or export data based on your permission level.

Platform-Specific Setup

Claude Code (Anthropic)

1. Install dbcli globally: npm install -g dbcli
2. Initialize: dbcli init (choose permission level)
3. Install skill: dbcli skill --install claude
4. Restart Claude Code extension
5. In Claude Code chat, ask: "Show me the database schema" or "Query active users"

Skill location: ~/.claude/skills/SKILL.md

---

Gemini CLI (Google)

1. Install dbcli globally: npm install -g dbcli
2. Initialize: dbcli init
3. Install skill: dbcli skill --install gemini
4. Start Gemini: gemini start
5. In chat, request: "Query the users table" or "Show database tables"

Skill location: ~/.local/share/gemini/skills/ (Linux) or platform equivalent

---

GitHub Copilot CLI

1. Install dbcli globally: npm install -g dbcli
2. Initialize: dbcli init
3. Install skill: dbcli skill --install copilot
4. Install Copilot CLI: npm install -g @github-next/github-copilot-cli
5. Use copilot preview: copilot --help and explore dbcli integration

Skill location: Per Copilot configuration

---

Cursor IDE

1. Install dbcli globally: npm install -g dbcli
2. Initialize: dbcli init
3. Install skill: dbcli skill --install cursor
4. Open Cursor editor
5. Use Cursor's Composer: "Insert a new user" or "Export user data"

Skill location: ~/.cursor/skills/

---

Example: AI Agent Workflow

Scenario: You want an AI agent to analyze user engagement data.

# 1. Install and initialize
npm install -g dbcli
dbcli init  # Choose "query-only" for safety

# 2. Install skill to Claude Code
dbcli skill --install claude

# 3. In Claude Code chat, ask:
# "Analyze the last 7 days of user activity and summarize insights"

# Claude Code will:
# - Use: dbcli schema users, dbcli query "SELECT ..."
# - Parse JSON output
# - Provide analysis

Skill Refresh

dbcli dynamically generates skills based on your current configuration:

# When permission level changes, skill updates automatically
# Edit ~/.dbcli and change "permissionLevel" to "admin"
dbcli skill  # Now shows delete and admin commands

# Re-install to push changes to AI platform
dbcli skill --install claude

---

Troubleshooting

Connection Issues

"ECONNREFUSED: Connection refused"

Database is not running or host/port is incorrect.

Solutions:

# Verify database is running
psql --version  # PostgreSQL installed?
mysql --version  # MySQL installed?

# Check connection string
dbcli init  # Re-run initialization to verify credentials

# Verify host/port from command line
psql -h localhost -U postgres  # PostgreSQL test
mysql -h 127.0.0.1 -u root      # MySQL test

"ENOTFOUND: getaddrinfo ENOTFOUND hostname"

Hostname resolution failed (typo or DNS issue).

Solutions:

# Verify hostname in .dbcli
cat ~/.dbcli | grep host

# Test DNS resolution
ping your-hostname.com

# Use 127.0.0.1 instead of localhost if issues persist
dbcli init  # Re-initialize with correct host

---

Permission Errors

"Permission denied: INSERT requires Read-Write or Admin"

Trying to write with Query-only permission level.

Solution: Re-initialize with higher permission level:

rm ~/.dbcli  # Remove old config
dbcli init  # Re-run, choose "read-write" or "admin"

"Permission denied: DELETE requires Admin"

Only Admin can delete rows (safety feature).

Solution: Re-initialize with Admin permission, or ask administrator.

dbcli init  # Choose "admin"
dbcli delete users --where "id=1" --force

---

Query Errors

"Table not found: users"

Table doesn't exist or name is misspelled.

Solution:

# Show all available tables
dbcli list

# Check spelling and retry
dbcli query "SELECT * FROM user" --format json

"Syntax error near SELECT"

SQL syntax error in query.

Solution:

# Test query in native database client first
psql  # Or mysql
# SELECT * FROM users;  <- Test here first

# Then use in dbcli
dbcli query "SELECT * FROM users"

---

Performance Issues

"Query returns 1000 rows instead of full result set"

Query-only permission auto-limits results for safety.

Solution: Increase permission level or fetch data in chunks:

# Re-initialize with higher permission
dbcli init  # Choose "read-write" or "admin"

# OR fetch data in chunks
dbcli query "SELECT * FROM users LIMIT 100 OFFSET 0"
dbcli query "SELECT * FROM users LIMIT 100 OFFSET 100"

"CLI startup takes 30+ seconds (first run)"

npx is downloading and caching package.

Solution: This is normal on first run. Subsequent runs are instant:

npx dbcli init  # First run: 30s (downloads)
npx dbcli init  # Second run: <1s (cached)

# Or install globally for faster startup
npm install -g dbcli
dbcli init  # All future runs: <1s

---

Cross-Platform Issues

Windows: "Command not found: dbcli"

npm .cmd wrapper not created or PATH not updated.

Solutions:

# Restart terminal to refresh PATH
# OR reinstall globally
npm uninstall -g dbcli
npm install -g dbcli

# Verify installation
where dbcli  # Windows command to find executable

macOS/Linux: "Permission denied: ./dist/cli.mjs"

Executable bit not set.

Solution:

chmod +x dist/cli.mjs
./dist/cli.mjs --help

---

System Requirements

Database Support

• PostgreSQL: 12.0+
• MySQL: 8.0+
• MariaDB: 10.5+

Runtime

• Node.js: 18.0.0+
• Bun: 1.3.3+

Platforms

• macOS: Intel and Apple Silicon
• Linux: x86_64 (Ubuntu, Debian, CentOS, etc.)
• Windows: 10+ (via npm .cmd wrapper)

---

Development

See CONTRIBUTING.md for development setup, testing, and release process.

---

License

See LICENSE file for details.