clidey/whodb-cli repository overview

⁠WhoDB CLI

An interactive, production-ready command-line interface for WhoDB.

Please check https://github.com/clidey/whodb/blob/main/cli/README.md⁠ for the most up-to-date docs.

⁠Features

• 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
• Schema Diff - Compare schema metadata across environments in the CLI and TUI
• Cloud Discovery - Inspect configured cloud providers and discovered cloud-managed resources from the CLI
• Discovered Connect - Prefill connect/save flows directly from discovered cloud resources
• ERD Graph Output - Inspect backend graph metadata from the CLI or TUI
• Explain Plans - Run database-native EXPLAIN from the CLI or TUI
• Backend Query Suggestions - Shared onboarding suggestions in the CLI and TUI editor
• Bookmarks and Profiles - Shared saved queries and connection profiles across CLI and TUI
• Workspace Restore - Resume your last reconnectable TUI session on startup
• Query History - Persistent history with re-execution
• Shell Completion - Bash/Zsh/Fish install plus PowerShell script generation
• Programmatic Mode - JSON/NDJSON/CSV/plain output plus streamed query/export paths for scripting and automation
• MCP Server - Model Context Protocol server for AI assistants (Claude, Cursor, etc.)

⁠Installation

⁠Native Install (Recommended)

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

⁠Homebrew (macOS/Linux)

brew install whodb-cli

⁠npm

npm install -g @clidey/whodb-cli

Or with npx (no install):

npx @clidey/whodb-cli

⁠From Source

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

⁠Using Docker

# 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

⁠Verify Installation

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

⁠Quick Start

⁠1. Connect to a Database

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

whodb-cli connect

⁠PostgreSQL

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

⁠PostgreSQL (non-interactive password)

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

⁠PostgreSQL with SSL

whodb-cli connect \
  --type postgres \
  --host localhost \
  --port 5432 \
  --user postgres \
  --database mydb \
  --ssl-mode verify-ca \
  --ssl-ca ./ca.pem

⁠Discovered Cloud Resource

# Open the TUI form prefilled from discovery
whodb-cli connect --discovered aws-prod-us-west-2/prod-db

# One-shot connect when you already know the missing credentials
whodb-cli connect \
  --discovered aws-prod-us-west-2/prod-db \
  --user postgres \
  --database app

⁠MySQL

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

⁠SQLite

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

⁠MongoDB

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

⁠1b. Use Environment Profiles

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

⁠2. Start Interactive Mode

# Start the TUI (default behavior)
whodb-cli

⁠3. Execute a Quick Query

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

⁠Commands

⁠Root Command (Interactive Mode)

Running whodb-cli without arguments starts the interactive TUI.

whodb-cli [flags]

Flags:

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

⁠connect

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)
• --ssl-mode: SSL mode for the selected database type
• --ssl-ca: Path to a CA certificate PEM file
• --ssl-cert: Path to a client certificate PEM file
• --ssl-key: Path to a client private key PEM file
• --ssl-server-name: Override server name used for SSL hostname verification

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

⁠query

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, ndjson, csv
• --stream: Stream result rows incrementally (supported for plain, json, ndjson, and csv)
• --quiet, -q: Suppress informational messages

auto uses table output for terminals and plain output for pipes. ndjson writes one JSON object per result row.

⁠suggestions

Show backend-generated query suggestions for a connection.

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

Flags:

• --connection, -c: Connection name to use
• --schema, -s: Schema to use for suggestion generation
• --format, -f: Output format: table, plain, json, ndjson, csv
• --quiet, -q: Suppress informational messages

⁠completion

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)

⁠Programmatic Commands

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

• Query and list commands such as query, schemas, tables, columns, connections list, and history list/search keep their existing raw JSON array output.
• Action and analysis commands such as connections add/remove/test, history clear, audit, mock-data, diff, erd, bookmarks save/delete, and profiles save/delete return a JSON envelope with command, success, and data when you pass --format json.
• query --stream supports plain, json, ndjson, and csv. export --stream supports CSV only.

⁠explain

Run EXPLAIN using the current database plugin's native explain prefix.

whodb-cli explain --connection my-postgres "SELECT * FROM users"
whodb-cli explain --connection my-postgres --format json "SELECT * FROM users"

Flags:

• --connection, -c: Connection name to use
• --format, -f: Output format: auto, table, plain, json, ndjson, csv
• --quiet, -q: Suppress informational messages

⁠schemas

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

⁠tables

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

⁠columns

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

⁠connections

Manage saved connections.

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

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

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

# Remove a connection
whodb-cli connections remove prod --format json

Flags (applies to all subcommands):

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

⁠cloud

Inspect configured cloud providers and discovered resources.

Cloud provider support follows the shared provider flags:

• WHODB_ENABLE_AWS_PROVIDER=true
• WHODB_ENABLE_AZURE_PROVIDER=true
• WHODB_ENABLE_GCP_PROVIDER=true

# List configured providers
whodb-cli cloud providers list

# Test or refresh providers
whodb-cli cloud providers test aws-prod-us-west-2
whodb-cli cloud providers refresh --all

# List discovered resources
whodb-cli cloud connections list
whodb-cli cloud connections list --provider aws-prod-us-west-2

# Use a discovered resource in the normal connect/save flows
whodb-cli connect --discovered aws-prod-us-west-2/prod-db
whodb-cli connections add --from-discovered aws-prod-us-west-2/prod-db --user alice --database app

⁠diff

Compare schema metadata between two connections.

By default, diff uses each connection's configured schema when one exists. For database-scoped connections such as MySQL and MariaDB, it uses the connection's configured database when no schema flag is provided.

# Compare two connections using their default schemas
whodb-cli diff --from staging --to prod

# Compare the same schema on both sides
whodb-cli diff --from staging --to prod --schema public

# Compare Postgres to MySQL using each connection's configured namespace
whodb-cli diff --from dev-e2e_postgres-1 --to dev-e2e_mysql-1

# Emit machine-readable JSON
whodb-cli diff --from staging --to prod --format json

Flags:

• --from: Source connection name (required)
• --to: Target connection name (required)
• --schema: Schema name to compare on both sides
• --from-schema: Source schema name
• --to-schema: Target schema name
• --format, -f: Output format: table or json
• --quiet, -q: Suppress informational messages

⁠erd

Render the same backend graph metadata used by the TUI ER diagram view.

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

Flags:

• --connection, -c: Connection name to use
• --schema, -s: Schema name
• --format, -f: Output format: text or json
• --quiet, -q: Suppress informational messages

⁠export

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)
• --stream: Stream CSV exports incrementally to the output file
• --quiet, -q: Suppress informational messages

⁠history

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 --format json

Flags:

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

⁠bookmarks

Manage the same saved query bookmarks used by the TUI editor.

whodb-cli bookmarks list
whodb-cli bookmarks save recent-users "SELECT * FROM users ORDER BY id DESC"
whodb-cli bookmarks load recent-users
whodb-cli bookmarks delete recent-users --format json

⁠profiles

Manage the same saved connection profiles used by the TUI.

whodb-cli profiles list
whodb-cli profiles save production --connection prod --theme Dracula --page-size 100 --timeout 30
whodb-cli profiles show production --format json
whodb-cli profiles delete production --format json
whodb-cli --profile production

⁠MCP Server

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

⁠Start the MCP Server

# 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.

⁠Transport Modes

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 Modes

⁠MCP Flags

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)

⁠Configure Connections

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.

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

⁠Docker MCP Server

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

⁠License

Apache License 2.0 - See LICENSE file for details.