CLI & MCP

WhoDB ships a separate CLI alongside the web app. Use it when you want a terminal UI, scriptable database checks, SSH tunneling, assistant integration setup, or an MCP server for local tooling.

Install Or Run

# Run without installing
npx @clidey/whodb-cli --help

# Install from npm
npm install -g @clidey/whodb-cli

# Build from source
cd cli
go build -o whodb-cli .

Running whodb-cli with no subcommand opens the interactive TUI.

Interactive TUI

The TUI includes:

• database connection and saved connection management
• split-pane layouts and theme switching
• schema and table browsing
• SQL editor with autocomplete, formatting, multi-tab buffers, and external editor support
• query results, pagination, column selection, and WHERE builders
• query history, bookmarks, and profiles
• CSV and Excel import/export flows
• ER diagram metadata view
• database-native EXPLAIN
• schema diff between saved connections
• FK-aware mock data generation
• data-quality audit checks
• AI chat when a provider is configured
• SSH tunnel support
• SSL mode and certificate-file support
• Docker database auto-detection
• cloud provider discovery commands when provider support is enabled

Command Surface

The current CLI command tree includes:

Most read/list commands support structured output with --format json; many also support table, plain, ndjson, or csv depending on the command.

Common Examples

# Launch the TUI
whodb-cli

# Connect directly and save the connection
whodb-cli connect \
  --type postgres \
  --host localhost \
  --port 5432 \
  --user alice \
  --database app \
  --name local-postgres

# Use an existing connection
whodb-cli schemas --connection local-postgres --format json
whodb-cli tables --connection local-postgres --schema public --format json
whodb-cli columns --connection local-postgres --schema public --table users --format json

# Run a query
whodb-cli query "SELECT * FROM users LIMIT 10" --connection local-postgres --format table

# Stream query rows
whodb-cli query "SELECT * FROM events" --connection local-postgres --format ndjson --stream

# Export table data or query results
whodb-cli export --connection local-postgres --table users --format csv --output users.csv
whodb-cli export --connection local-postgres --query "SELECT * FROM users" --output users.xlsx

# Import CSV or Excel
whodb-cli import --connection local-postgres --file users.csv --table users
whodb-cli import --connection local-postgres --file orders.xlsx --table orders --sheet Q1 --mode overwrite

# Analyze before generating mock data
whodb-cli mock-data --connection local-postgres --table orders --rows 50 --analyze

# Generate mock data after confirmation
whodb-cli mock-data --connection local-postgres --table orders --rows 50 --yes

# Run quality checks
whodb-cli audit --connection local-postgres --schema public --format json

# Compare environments
whodb-cli diff --from staging --to prod --schema public --format json

# Render relationship metadata
whodb-cli erd --connection local-postgres --schema public --format json

# Emit agent-facing CLI and MCP metadata
whodb-cli agent schema --format json

# Diagnose a connection without exposing secrets
whodb-cli doctor --connection local-postgres --schema public --format json

# Preview a built-in workflow before running it
whodb-cli runbooks run schema-audit --connection local-postgres --dry-run

# Preview assistant integration files without writing them
whodb-cli skills install --target cursor --dry-run

Import And Export

CLI export supports:

• CSV
• Excel .xlsx
• table exports
• query-result exports
• CSV streaming with --stream

CLI import supports:

• CSV
• Excel .xlsx
• delimiter auto-detection or --delimiter
• Excel sheet selection with --sheet
• append, overwrite, and upsert modes
• optional table creation with --create-table
• positional mapping with --header=false --mapping position
• explicit auto-generated column import with --allow-auto-generated

For SQL seed files, use the database-native client for the target engine, such as psql -f seed.sql or mysql database < seed.sql.

Connections

The CLI can use saved connections and environment-defined profiles.

# Saved connection
whodb-cli connections add \
  --name local-postgres \
  --type postgres \
  --host localhost \
  --user alice \
  --database app

# Environment profile
export WHODB_POSTGRES_1='{"alias":"ci-postgres","host":"localhost","user":"postgres","password":"postgres","database":"app_test","port":"5432"}'
whodb-cli tables --connection ci-postgres --format json

Cloud-discovered resources can prefill connect and save flows:

whodb-cli cloud providers list
whodb-cli cloud connections list
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

SSH Tunneling

Built-in SSH tunneling belongs to the CLI/TUI surface in this codebase. If your database sits behind a bastion host and you want WhoDB tooling to manage the tunnel, use the CLI rather than the web login page. SSH passwords for saved connections are stored in the OS keyring, with a 0600 plaintext config fallback only when no keyring is available.

Agent Metadata, Diagnostics, And Runbooks

The CLI includes command surfaces designed for operators and AI agents that need a stable, scriptable view of WhoDB capabilities.

# Machine-readable command, source, MCP, workflow, and safety metadata
whodb-cli agent schema --format json

# Redacted diagnostics for one connection
whodb-cli doctor --connection local-postgres --schema public --format json

# List and inspect built-in workflows
whodb-cli runbooks list
whodb-cli runbooks describe schema-audit

# Preview or run workflows
whodb-cli runbooks run connection-doctor --connection local-postgres --dry-run
whodb-cli runbooks run schema-audit --connection local-postgres --schema public --format json
whodb-cli runbooks run schema-diff --from staging --to prod --format json

Built-in runbooks are intentionally limited to WhoDB operations:

• connection-doctor: runs the same diagnostics as doctor
• schema-audit: loads storage units and runs data-quality checks
• schema-diff: compares schema metadata between two connections

Assistant Integrations

The CLI can install bundled WhoDB assistant skills and native assistant configuration files.

# List bundled skills and agents
whodb-cli skills list
whodb-cli skills list --format json

# Install all bundled skills into an explicit skills directory
whodb-cli skills install --target-dir ~/.codex/skills

# Install skills and bundled Markdown agents for Claude Code
whodb-cli skills install --target claude-code --include-agents

# Install native MCP configuration for an assistant
whodb-cli skills install --target cursor
whodb-cli skills install --target vscode
whodb-cli skills install --target gemini-cli

# Preview files and backup paths without modifying disk
whodb-cli skills install --target cursor --dry-run

Supported assistant targets:

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.

MCP Server

The CLI can run as an MCP server:

whodb-cli mcp serve

Current MCP tools include:

• whodb_connections
• whodb_schemas
• whodb_tables
• whodb_columns
• whodb_query
• whodb_confirm
• whodb_pending
• whodb_explain
• whodb_diff
• whodb_erd
• whodb_audit
• whodb_suggestions

Writes require confirmation by default. Use the mode that matches your risk level:

# Default: writes require confirmation
whodb-cli mcp serve

# Read-only plus strict validation
whodb-cli mcp serve --safe-mode

# Read-only mode
whodb-cli mcp serve --read-only

# Allow writes without confirmation
whodb-cli mcp serve --allow-write

# Allow DROP/TRUNCATE as well
whodb-cli mcp serve --allow-write --allow-drop

Useful MCP options:

• --transport stdio|http
• --host
• --port
• --auth-token (or WHODB_MCP_AUTH_TOKEN) — require a Bearer token on /mcp requests; strongly recommended when binding to a network interface
• --confirm-writes (default on)
• --timeout
• --max-rows
• --allow-multi-statement
• --security strict|standard|minimal
• --tools
• --disable-tools
• --default-connection
• --allowed-connections
• --no-analytics

HTTP mode is part of the CLI MCP server, not the WhoDB web app:

whodb-cli mcp serve --transport=http --host=0.0.0.0 --port=3000 --auth-token your-secret-token

It exposes:

• /mcp
• /health

Hosted Platform MCP

Hosted WhoDB platform MCP mode is opt-in and uses the existing CLI hosted login:

whodb-cli login
whodb-cli use --org <org-id-or-slug> --project <project-id-or-slug>
whodb-cli mcp serve --platform

When --platform is set, the MCP server exposes hosted platform tools only. Local database tools such as whodb_query and whodb_connections are not registered.

Platform MCP clients should read these resources before selecting tools:

• whodb://platform/workspace for the current host, signed-in user, organization, project, and readiness state
• whodb://platform/schema for enabled tools, resources, prompts, generic write specs, and payload shapes
• whodb://platform/tool-guide for read/write behavior, confirmation behavior, row limits, and field projection guidance

For tools that accept fields, request only the fields needed for the current answer and request more only when needed. Hosted platform writes return a confirmation token by default and execute only after confirmation.

See .agents/docs/hosted-platform-cli.md in the repository for the full hosted platform CLI and MCP workflow.

Related Pages