@clidey/whodb-cli

WhoDB CLI - a powerful database management tool with interactive TUI, programmatic commands, and MCP server for AI assistants.

Installation

# Run directly (no install required)
npx @clidey/whodb-cli --help

# Or install globally
npm install -g @clidey/whodb-cli

Features

• Interactive TUI: Full terminal UI for database management
• Programmatic Commands: Query, export, and manage databases from scripts
• MCP Server: Integrate with Claude Desktop, Claude Code, and other MCP clients
• Assistant Integrations: Install ready-to-use MCP configs for Codex, Claude Code, Cursor, VS Code, GitHub Copilot CLI, Gemini CLI, Windsurf, OpenCode, Cline, Zed, Continue, and aider

Supported Databases

• PostgreSQL
• MySQL / MariaDB
• SQLite
• MongoDB
• Redis
• Elasticsearch
• ClickHouse

Usage

Interactive Mode (TUI)

npx @clidey/whodb-cli

Programmatic Commands

# Query a database
npx @clidey/whodb-cli query "SELECT * FROM users LIMIT 10" --connection mydb

# List schemas
npx @clidey/whodb-cli schemas --connection mydb --format json

# List tables
npx @clidey/whodb-cli tables --connection mydb --schema public

# Describe columns
npx @clidey/whodb-cli columns --connection mydb --table users

# Export data
npx @clidey/whodb-cli export --connection mydb --table users --format csv --output users.csv

MCP Server Mode

Start as an MCP server for AI assistant integration:

npx @clidey/whodb-cli mcp serve

Write operations require confirmation by default. Use --allow-write to disable confirmations or --read-only to block writes.

Restrict AI access to specific connections with --allowed-connections:

npx @clidey/whodb-cli mcp serve --allowed-connections prod,staging

MCP Client Configuration (Example)

Example configuration (from whodb-cli mcp serve --help):

{
  "mcpServers": {
    "whodb": {
      "command": "whodb-cli",
      "args": ["mcp", "serve"],
      "env": {
        "WHODB_POSTGRES_1": "{\"alias\":\"prod\",\"host\":\"localhost\",\"user\":\"user\",\"password\":\"pass\",\"database\":\"db\"}"
      }
    }
  }
}

Assistant Integration Installer

Install native assistant configuration with the bundled CLI:

npx @clidey/whodb-cli skills install --target cursor
npx @clidey/whodb-cli skills install --target vscode
npx @clidey/whodb-cli skills install --target gemini-cli
npx @clidey/whodb-cli skills install --target claude-code --include-agents
npx @clidey/whodb-cli skills install --target cursor --dry-run

Supported targets: codex, claude-code, cursor, vscode, github-copilot, gemini-cli, windsurf, opencode, cline, zed, continue, and aider.

Existing JSON and JSONC configuration files are merged in place and rewritten as formatted JSON. Before an existing JSON or YAML assistant config is rewritten, the original file is saved beside it as <filename>.whodb.bak. Use --dry-run to preview created or updated files and any backup paths without writing changes.

Environment Variables

Configure database connections via environment profiles, for example WHODB_POSTGRES='[{"alias":"prod","host":"localhost","user":"user","password":"pass","database":"db","port":"5432"}]' or WHODB_MYSQL_1='{"alias":"dev","host":"localhost","user":"user","password":"pass","database":"devdb","port":"3306"}'. Each object supports alias (connection name), host, user, password, database, port, and optional config.

| Variable | Description | |----------|-------------| | WHODB_<DBTYPE> | JSON array of credential objects for a database type | | WHODB_<DBTYPE>_N | JSON object for a single credential (numbered profiles) |

Use the alias field to set the connection name (e.g., prod). If omitted, the CLI assigns a name like postgres-1.

Available MCP Tools

| Tool | Description | |------|-------------| | whodb_connections | List available database connections | | whodb_schemas | List schemas in a database | | whodb_tables | List tables in a schema | | whodb_columns | Get column details for a table | | whodb_query | Execute SQL queries | | whodb_confirm | Confirm pending write operations (only when confirm-writes is enabled) |

Platform Support

This package automatically installs the correct binary for your platform:

• macOS (Intel and Apple Silicon)
• Linux (x64, ARM64, ARMv7)
• Windows (x64, ARM64)

Links

• GitHub Repository
• Documentation

License

Apache-2.0