An interactive, production-ready command-line interface for WhoDB with a Claude Code-like experience.

• Interactive TUI - Terminal UI built with Bubble Tea
• Multi-Database Support - PostgreSQL, MySQL/MariaDB, SQLite, MongoDB, Redis, ClickHouse, ElasticSearch
• Table Browser - Navigate schemas and tables with visual grid layout
• WHERE Builder - Build AND-based filters for table browsing
• SQL Editor - Multi-line editor with schema-aware autocomplete
• AI Chat - Optional AI-assisted querying with consent gate (requires configured provider)
• Responsive Data Viewer - Paginated results with horizontal column scrolling
• Column Selection - Choose which columns are visible in results
• Export Capabilities - Export to CSV and Excel formats
• Query History - Persistent history with re-execution
• Shell Completion - Bash/Zsh/Fish install plus PowerShell script generation
• Programmatic Mode - JSON/CSV/plain output for scripting and automation
• MCP Server - Model Context Protocol server for AI assistants (Claude, Cursor, etc.)

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/clidey/whodb/main/cli/install/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/clidey/whodb/main/cli/install/install.ps1 | iex

The native installer:

• Detects your OS and architecture
• Downloads the correct binary from GitHub releases
• Installs to ~/.local/bin (macOS/Linux) or %LOCALAPPDATA%\WhoDB\bin (Windows)
• Adds to PATH if needed

To install a specific version:

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/clidey/whodb/main/cli/install/install.sh | bash -s v0.62.0

# Windows
$env:WHODB_VERSION = "v0.62.0"; irm https://raw.githubusercontent.com/clidey/whodb/main/cli/install/install.ps1 | iex

brew install whodb-cli

npm install -g @clidey/whodb-cli

Or with npx (no install):

npx @clidey/whodb-cli

Requires Go 1.21+:

git clone https://github.com/clidey/whodb.git
cd whodb/cli
go build -o whodb-cli .

Or using the Makefile:

cd cli
make build
make install  # installs to /usr/local/bin

# Build the Docker image (from repo root)
docker build -t whodb-cli:latest -f cli/Dockerfile .

# Or pull pre-built
docker pull clidey/whodb-cli:latest

whodb-cli --version
whodb-cli --help

If you omit required flags, the interactive connection form opens:

whodb-cli connect

whodb-cli connect \
  --type postgres \
  --host localhost \
  --port 5432 \
  --user postgres \
  --database mydb \
  --name my-postgres

printf "%s\n" "$PGPASSWORD" | whodb-cli connect \
  --type postgres \
  --host localhost \
  --port 5432 \
  --user postgres \
  --database mydb \
  --name my-postgres \
  --password

whodb-cli connect \
  --type mysql \
  --host localhost \
  --port 3306 \
  --user root \
  --database mydb \
  --name my-mysql

whodb-cli connect \
  --type sqlite \
  --user sqlite \
  --database /path/to/database.db \
  --name my-sqlite

whodb-cli connect \
  --type mongodb \
  --host localhost \
  --port 27017 \
  --user admin \
  --database mydb \
  --name my-mongo

Commands that accept --connection can also use environment profiles, for example WHODB_POSTGRES='[{"alias":"prod","host":"localhost","user":"user","password":"pass","database":"mydb","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 for advanced settings. port stays at the root level; the CLI also forwards it as the Port advanced key when building plugin credentials, so you do not need to include Port in config. Advanced config keys are plugin-specific; see core/src/plugins/*/db.go for the keys that are read.

# Array format (multiple profiles for a database type)
export WHODB_POSTGRES='[{"alias":"prod","host":"localhost","user":"user","password":"pass","database":"mydb","port":"5432"}]'

# Numbered format (one profile per variable)
export WHODB_MYSQL_1='{"alias":"dev","host":"localhost","user":"user","password":"pass","database":"devdb","port":"3306"}'

# Start the TUI (default behavior)
whodb-cli

whodb-cli query "SELECT * FROM users LIMIT 10" --connection my-postgres

Running whodb-cli without arguments starts the interactive TUI.

whodb-cli [flags]

Flags:

• --debug: Enable debug mode
• --no-color: Disable colored output

Connect to a database and optionally save the connection. If required flags are missing, the interactive connection form opens.

whodb-cli connect [flags]

Flags:

• --type: Database type (postgres, mysql, sqlite, mongodb, redis, clickhouse, elasticsearch, mariadb)
• --host: Database host (default: localhost)
• --port: Database port (default varies by type)
• --user: Username
• --database: Database name
• --schema: Preferred schema (optional)
• --name: Connection name (saves for later use)
• --password: Read password from stdin when not using a TTY (pipe a single line)

On a TTY, you will be prompted for the password with input hidden.

Execute a SQL query directly. Use - to read SQL from stdin.

whodb-cli query "SQL" [flags]

Flags:

• --connection, -c: Connection name to use (optional; if omitted, the first available connection is used)
• --format, -f: Output format: auto, table, plain, json, csv
• --quiet, -q: Suppress informational messages

auto uses table output for terminals and plain output for pipes.

Generate or install shell completion scripts.

# Show help
whodb-cli completion

# Print completion script to stdout
whodb-cli completion bash
whodb-cli completion zsh
whodb-cli completion fish
whodb-cli completion powershell

# Install completion (auto-detects shell)
whodb-cli completion install

# Install for specific shell
whodb-cli completion install bash

# Uninstall completion
whodb-cli completion uninstall

Install paths (bash/zsh rc files updated automatically):

• Bash: ~/.local/share/bash-completion/completions/whodb-cli
• Zsh: ~/.zsh/completions/_whodb-cli
• Fish: ~/.config/fish/completions/whodb-cli.fish
• PowerShell: Manual install (see whodb-cli completion powershell)

These commands output structured data for scripting, automation, and AI integration.

List database schemas.

whodb-cli schemas --connection my-postgres --format json

Flags:

• --connection, -c: Connection name (optional; if omitted, the first available connection is used)
• --format, -f: Output format: auto, table, plain, json, csv
• --quiet, -q: Suppress informational messages

List tables in a schema.

whodb-cli tables --connection my-postgres --schema public --format json

Flags:

• --connection, -c: Connection name (optional; if omitted, the first available connection is used)
• --schema, -s: Schema name (default varies by database)
• --format, -f: Output format: auto, table, plain, json, csv
• --quiet, -q: Suppress informational messages

Describe table columns.

whodb-cli columns --connection my-postgres --table users --format json

Flags:

• --connection, -c: Connection name (optional; if omitted, the first available connection is used)
• --table, -t: Table name (required)
• --schema, -s: Schema name
• --format, -f: Output format: auto, table, plain, json, csv
• --quiet, -q: Suppress informational messages

Manage saved connections.

# List connections
whodb-cli connections list --format json

# Test a connection
whodb-cli connections test my-postgres

# Add a connection
whodb-cli connections add --name prod --type postgres --host db.example.com --port 5432 --user app --database mydb

# Remove a connection
whodb-cli connections remove prod

Flags (applies to all subcommands):

• --format, -f: Output format: auto, table, plain, json, csv
• --quiet, -q: Suppress informational messages

Export table data or query results to file.

# Export to CSV
whodb-cli export --connection my-postgres --table users --format csv --output users.csv

# Export to Excel
whodb-cli export --connection my-postgres --table orders --format excel --output orders.xlsx

# Export query results
whodb-cli export --connection my-postgres --query "SELECT * FROM users" --output users.csv

Flags:

• --connection, -c: Connection name (optional; if omitted, the first available connection is used)
• --table, -t: Table name (required unless using --query)
• --query, -Q: SQL query to export results from (use instead of --table)
• --schema, -s: Schema name
• --format, -f: Export format: csv or excel (auto-detected from filename if omitted)
• --output, -o: Output file path (required)
• --delimiter, -d: CSV delimiter (default: comma)
• --quiet, -q: Suppress informational messages

Access query history.

# List recent queries
whodb-cli history list --limit 20 --format json

# Search history
whodb-cli history search "SELECT.*users"

# Clear history
whodb-cli history clear

Flags:

• --limit, -l: Limit number of results (0 = no limit)
• --format, -f: Output format: auto, table, plain, json, csv
• --quiet, -q: Suppress informational messages

WhoDB can run as an MCP (Model Context Protocol) server, enabling AI assistants like Claude, Cursor, and others to query your databases.

# Default: stdio transport (for Claude Desktop, Claude Code, etc.)
whodb-cli mcp serve

# HTTP transport (for cloud deployments, Docker, Kubernetes)
whodb-cli mcp serve --transport=http --port=3000

This starts an MCP server that exposes these tools:

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

stdio (default) - For local CLI integration with Claude Desktop, Claude Code, etc.

whodb-cli mcp serve

HTTP - For cloud deployments, Docker, Kubernetes, or shared access.

whodb-cli mcp serve --transport=http --host=0.0.0.0 --port=8080

HTTP mode exposes:

• /mcp - MCP endpoint (streaming HTTP)
• /health - Health check endpoint

Security:

• --safe-mode: Read-only + strict security (for demos/playgrounds)
• --read-only: Block all write operations
• --allow-write: Allow writes without confirmation (use with caution)
• --allow-drop: Allow DROP/TRUNCATE when running with --allow-write
• --security: Validation level (strict, standard, minimal)

Query Limits:

• --timeout: Query timeout (default 30s)
• --max-rows: Limit rows returned per query (0 = unlimited)
• --allow-multi-statement: Allow multiple SQL statements in one query

Transport:

• --transport: stdio (default) or http
• --host: Bind address (default: localhost)
• --port: Listen port (default: 3000)

Connection Scoping:

• --allowed-connections: Comma-separated list of connections to allow (restricts access)
• --default-connection: Default connection when not specified (does not restrict access)

# Restrict AI to specific connections only
whodb-cli mcp serve --allowed-connections prod,staging

# Set default without restricting access
whodb-cli mcp serve --default-connection prod

# Combine: restrict to prod/staging, default to staging
whodb-cli mcp serve --allowed-connections prod,staging --default-connection staging

When --allowed-connections is set:

• whodb_connections only shows allowed connections
• Queries to other connections are rejected
• First allowed connection becomes the default (unless --default-connection is set)

The MCP server uses the same connection sources as the CLI:

Option 1: Environment Profiles (recommended for production)

Use env profiles like WHODB_POSTGRES='[{"alias":"prod","host":"host","user":"user","password":"pass","database":"dbname","port":"5432"}]' or WHODB_MYSQL_1='{"alias":"staging","host":"host","user":"user","password":"pass","database":"dbname","port":"3306"}'. Each object supports alias (connection name), host, user, password, database, port, and optional config.

Use the JSON formats shown above. alias sets the connection name used in MCP tools.

# Array format
export WHODB_POSTGRES='[{"alias":"prod","host":"host","user":"user","password":"pass","database":"dbname","port":"5432"}]'

# Numbered format (one profile per variable)
export WHODB_MYSQL_1='{"alias":"staging","host":"host","user":"user","password":"pass","database":"dbname","port":"3306"}'

If alias is omitted, the CLI assigns a name like postgres-1. Saved connections take precedence if names collide.

Option 2: Saved Connections

Use whodb-cli connect --name mydb ... to save connections that the MCP server can access.

If a tool call omits connection, the MCP server uses the only available connection or returns an error if multiple are available.

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\"}"
        }
      }
    }
  }

docker run -i --rm \
  -e WHODB_POSTGRES_1='{"alias":"prod","host":"host","user":"user","password":"pass","database":"db"}' \
  --network host \
  whodb-cli:latest mcp serve

Select and manage database connections.

Form mode: Tab/Shift+Tab or ↑/↓ to move fields, ←/→ to change database type, Enter to connect.

Navigate schemas and tables in a visual grid layout.

Write and execute SQL queries with schema-aware autocomplete.

Features:

• Schema-aware autocomplete (tables, columns, keywords, snippets)
• Multi-line editing
• Error display

View query results in a responsive, paginated table.

Features:

• Pagination (configurable, default 50 rows)
• Column selection
• Data export (CSV, Excel)

Browse and re-execute past queries.

AI-assisted database chat (requires a configured provider and consent).

Consent gate: press a to accept or Esc to exit.

Export data to CSV or Excel format.

WhoDB CLI stores data in the unified WhoDB config:

• macOS: ~/Library/Application Support/whodb/config.json
• Linux: $XDG_DATA_HOME/whodb/config.json (default: ~/.local/share/whodb/config.json)
• Windows: %APPDATA%\\whodb\\config.json

Development builds append -dev to the data directory name, and EE builds append -ee.

Query history is stored alongside the config as history.json. If a legacy ~/.whodb-cli/config.yaml exists, it is migrated automatically.

{
  "cli": {
    "connections": [
      {
        "name": "local-postgres",
        "type": "Postgres",
        "host": "localhost",
        "port": 5432,
        "username": "postgres",
        "database": "mydb",
        "schema": "public"
      }
    ],
    "history": {
      "max_entries": 1000,
      "persist": true
    },
    "display": {
      "theme": "dark",
      "page_size": 50
    },
    "ai": {
      "consent_given": false
    },
    "query": {
      "timeout_seconds": 30
    }
  }
}

Passwords are stored in the OS keyring when available. If not available, they are written to config.json (new files are created with 0600 permissions).

export WHODB_CLI_DEBUG=true
export WHODB_CLI_NO_COLOR=true
export NO_COLOR=1

docker run -it --rm whodb-cli:latest

docker run -it --rm --network host whodb-cli:latest connect \
  --type postgres \
  --host localhost \
  --user postgres \
  --database mydb

docker run -it --rm --network host whodb-cli:latest query "SELECT version()"

docker run -it --rm \
  -v ~/.local/share/whodb:/root/.local/share/whodb \
  --network host \
  whodb-cli:latest

• TERM=xterm-256color - Proper terminal colors (set by default)
• WHODB_CLI_DEBUG / WHODB_CLI_NO_COLOR / NO_COLOR - Control CLI output

"Cannot connect to database"

# Verify database is running
pg_isready -h localhost -p 5432  # PostgreSQL
mysql -h localhost -u root -p     # MySQL

"Plugin not found"

Supported database types: postgres, mysql, sqlite, mongodb, redis, clickhouse, elasticsearch, mariadb

"Garbled text / incorrect colors"

# Set terminal type
export TERM=xterm-256color

Recommended terminals: iTerm2, Alacritty, Windows Terminal, Kitty

"Config not found"

mkdir -p ~/.local/share/whodb
whodb-cli connect --type postgres --host localhost --name test

Adjust the path for your OS (see Configuration).

"Permissions error"

chmod 700 ~/.local/share/whodb
chmod 600 ~/.local/share/whodb/config.json ~/.local/share/whodb/history.json

whodb-cli --debug

cli/
├── cmd/                # CLI commands (Cobra)
│   ├── root.go         # Main entry, starts TUI
│   ├── connect.go      # Database connection
│   ├── query.go        # Direct query execution
│   ├── schemas.go      # List schemas
│   ├── tables.go       # List tables
│   ├── columns.go      # Describe columns
│   ├── connections.go  # Connection management
│   ├── export.go       # Data export
│   ├── history.go      # Query history
│   ├── mcp.go          # MCP server command
│   └── completion.go   # Shell completion
├── internal/
│   ├── tui/            # Terminal UI (Bubble Tea)
│   │   ├── model.go
│   │   ├── connection_view.go
│   │   ├── browser_view.go
│   │   ├── editor_view.go
│   │   ├── results_view.go
│   │   ├── history_view.go
│   │   ├── chat_view.go
│   │   ├── export_view.go
│   │   ├── where_view.go
│   │   ├── columns_view.go
│   │   ├── schema_view.go
│   │   └── messages.go
│   ├── config/         # Unified config.json + keyring storage
│   ├── database/       # Database manager
│   └── history/        # Query history
├── pkg/
│   ├── mcp/            # MCP server implementation
│   │   ├── server.go   # Server setup
│   │   ├── tools.go    # Tool handlers
│   │   └── credentials.go # Connection resolution
│   ├── output/         # Programmatic output formatting
│   ├── styles/         # UI styling (Lipgloss)
│   ├── version/        # Build/version info
│   └── crash/          # Panic handler and crash report
├── skills/             # Claude Code skills
│   ├── whodb/          # Main database skill
│   ├── query-builder/  # Natural language → SQL
│   └── schema-designer/ # Schema design assistance
├── agents/             # Claude Code agents
│   ├── database-analyst.md
│   ├── query-optimizer.md
│   └── report-generator.md
└── plugin.json         # Plugin manifest

# Run in development mode
go run .

# Run tests
go test ./...

# Build with race detector
go build -race -o whodb-cli .

# Lint
golangci-lint run ./...

Apache License 2.0 - See LICENSE file for details.