CLI and MCP

Use the CLI when database work belongs in a terminal or script. You can inspect a source interactively, run a repeatable command that returns structured output, or expose database tools to an assistant through MCP.

These are different ways to work with the same local CLI. Choose the one that fits the task before configuring an integration.

Install#

Install the CLI package and confirm its available commands:

npm install -g @clidey/whodb
whodb --help

You can also inspect it without a global installation:

npx @clidey/whodb --help

Run whodb without a subcommand to open the interactive terminal UI. Use explicit subcommands when you need a scriptable operation.

Connect and inspect#

This example creates a named PostgreSQL connection, then inspects its schemas, tables, and fields:

whodb connect --type postgres --host localhost --port 5432 \
  --user alice --database app --name local-postgres

whodb schemas --connection local-postgres --format json
whodb tables --connection local-postgres --schema public --format json
whodb columns --connection local-postgres --schema public --table users --format json

Replace the endpoint, account, and database with your own values. Use the password input method documented by --help rather than embedding a secret in a command you will share or commit.

A named connection makes repeated commands easier to read. Before automating a write, verify which endpoint that name resolves to and use an account with the intended database permissions.

Choose a command#

Use whodb <command> --help for required arguments and output formats. whodb guide prints the broader command guide.

Work interactively#

The TUI provides schema browsing, a query editor, result grids, history, bookmarks, themes, split panes, and saved connections. Use it when you want to move between objects and queries without building a shell command for each step.

The CLI/TUI also supports SSH tunnels for databases reached through a bastion. This tunnel management belongs to the terminal workflow; it is not a setting in the CE browser form.

Diagnose a connection#

Use diagnostics before treating a missing table or failed query as a data problem:

whodb doctor --connection local-postgres --schema public --format json
whodb runbooks list
whodb runbooks describe schema-audit
whodb runbooks run connection-doctor --connection local-postgres --dry-run
whodb agent schema --format json

Built-in runbooks cover connection diagnostics, schema audits, and schema comparisons. Read a runbook's description and preview it before execution so you understand its intended scope.

Connect an assistant with MCP#

Start the MCP server with the query mode needed for the task:

# Review queries outside the automatically accepted read subset.
whodb mcp serve

# Limit the assistant to accepted reads.
whodb mcp serve --read-only

# Use read-only execution with strict validation.
whodb mcp serve --safe-mode

Tools include connection and schema discovery, table and column inspection, query execution, confirmation, explain, relationships, schema diff, audits, and suggestions. Review MCP permissions before allowing writes.

For HTTP transport, set an authentication token and keep the listener limited to the clients that need it:

whodb mcp serve --transport=http --host=127.0.0.1 --port=3001 \
  --auth-token "$WHODB_MCP_AUTH_TOKEN"

Set WHODB_MCP_AUTH_TOKEN to a secret before running that command. HTTP transport exposes /mcp and /health. Check the host, enabled tools, and allowed connections before exposing it beyond the local machine.

Install an assistant integration#

Preview the files an integration will create before installing it:

whodb skills list
whodb skills install --target cursor --dry-run
whodb skills install --target cursor

Use whodb skills install --help for supported targets. The command can install bundled skills and native MCP configuration for compatible assistants. Check the preview's file and backup paths so you know which assistant configuration will change.

Next: CI/CD workflows · Cloud discovery