whodb Documentation

Technical Documentation: clidey/whodb

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

WhoDB gives you one place to explore your databases, edit data, run queries, and understand how a schema fits together. It runs in the browser, is easy to self-host, and is available as a desktop app or terminal CLI too.

Use it when you want to inspect a local database, help a teammate explore unfamiliar data, or work without installing a heavyweight database client. AI features are optional: connect Ollama, OpenAI, Anthropic, LM Studio, or another OpenAI-compatible provider if you want to ask questions in plain English.

Quick start Copy Chapter

Run WhoDB with Docker:

docker run --rm -it -p 8080:8080 clidey/whodb

Then open http://localhost:8080 and enter your database connection details.

Want to look around first? Try the live demo or watch the video walkthrough.

What you can do Copy Chapter

• Browse and edit data in a spreadsheet-style grid with sorting, filtering, pagination, and inline editing.
• Understand a schema visually with an interactive graph of tables and relationships.
• Work through queries in a scratchpad with multiple cells, autocomplete, history, and results kept alongside each query.
• Move data in and out with imports, exports, and mock-data generation for development and testing.
• Ask questions in plain English using a local or hosted AI provider that you choose.
• Work from your terminal through the WhoDB CLI and its MCP server.

Supported databases Copy Section

WhoDB Community supports:

• PostgreSQL, CockroachDB, YugabyteDB, and QuestDB
• MySQL, MariaDB, and TiDB
• SQLite and DuckDB
• MongoDB and FerretDB
• Redis, Valkey, and Dragonfly
• Elasticsearch and OpenSearch
• ClickHouse and Memcached

Support varies by database because not every system has the same concepts or capabilities. The connection screen shows the options available for each source.

Installation options Copy Chapter

Docker with persistent sessions Copy Section

The one-line Docker command is ideal for trying WhoDB. To keep encrypted login sessions when the container is replaced, first generate a key and save it somewhere secure:

openssl rand -hex 32

Then mount /data and reuse that key whenever you start the container:

docker run -it -p 8080:8080 \
  -v whodb-data:/data \
  -e WHODB_ENCRYPTION_KEY=your_saved_64_character_hex_key \
  clidey/whodb

Keep that key somewhere safe. Changing it invalidates existing sessions. If WhoDB is served through an HTTPS reverse proxy, also set WHODB_SECURE=true so browsers only send the session cookie over HTTPS.

See the documentation for Docker Compose, connection profiles, SSL, AI providers, and other configuration options.

Desktop Copy Section

• macOS
• Windows
• Snap

CLI and MCP server Copy Section

The CLI includes an interactive terminal UI and an MCP server for AI tools:

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

# or install with npm
npm install @clidey/whodb

whodb             # open the terminal UI
whodb mcp serve   # start the MCP server

See the CLI guide for connection examples and the full command reference.

AI providers Copy Chapter

You can add a hosted AI provider directly from WhoDB—no backend configuration or restart is required. Open Chat, choose Add Provider from the provider menu, then select OpenAI, Anthropic, or Gemini and enter your API key. WhoDB will fetch the available models from that provider.

Ollama and LM Studio are available as local options in WhoDB Community. By default, the backend looks for Ollama at localhost:11434 and LM Studio at localhost:1234/v1, with local addresses adjusted automatically for Docker and WSL. Use WHODB_OLLAMA_HOST, WHODB_OLLAMA_PORT, or WHODB_LMSTUDIO_BASE_URL only when those defaults are not suitable for your setup.

Optional backend provider configuration Copy Section

Environment variables let deployment administrators declare providers when the server starts. This is useful for preconfiguring OpenAI or Anthropic, changing provider endpoints, or adding an OpenAI-compatible service for everyone using that deployment:

• WHODB_OPENAI_* for OpenAI
• WHODB_ANTHROPIC_* for Anthropic
• WHODB_OLLAMA_* for Ollama connection settings
• WHODB_LMSTUDIO_* for LM Studio connection settings
• WHODB_AI_GENERIC__* for OpenAI-compatible providers

See the installation guide for the complete environment variable list and the AI provider guide for setup examples.

WhoDB Community and WhoDB Platform Copy Chapter

This repository contains WhoDB Community, the Apache-2.0-licensed database workspace described above. It is free to self-host and is the best place to start if you want to explore and work with databases.

WhoDB Platform is the commercial, self-hosted edition for organizations that need shared projects, more data sources, SSO, fine-grained access controls, audit logs, pipelines, reporting, and internal apps. You can read the WhoDB overview or compare plans on the pricing page.

Development Copy Chapter

WhoDB has a Go backend and a React/TypeScript frontend. For local development, run them in separate terminals.

Requirements:

• Go
• Node.js and pnpm

Start the backend:

cd core
go run ./cmd/whodb

Start the frontend:

cd frontend
pnpm install
pnpm start

The frontend opens at http://localhost:3000 and talks to the backend on port 8080. See the CE build and run guide for generation and build commands.

Contributing Copy Chapter

Bug reports, feature ideas, documentation improvements, and code contributions are all welcome.

• Open an issue for a bug or concrete request.
• Start a discussion for questions and ideas.
• Read CONTRIBUTING.md before sending a pull request.

More screenshots Copy Chapter

See WhoDB in action

Query scratchpad Copy Section

Add and edit records Copy Section

Build filters visually Copy Section

Export data Copy Section

Support Copy Chapter

• Documentation
• GitHub Issues
• [email protected]

WhoDB is licensed under the Apache License 2.0.

Overview (`.agents/README.md`) Copy Section

Agent Instructions Index

This directory contains shared agent guidance for WhoDB. It is intentionally tool-neutral so Codex, Claude Code, opencode, Pi, and other coding agents can use the same source of truth.

Start with ../AGENTS.md. Use this index only to find the one or two deeper references that match the task.

Directory Layout Copy Chapter

If ee/ is present, also read ee/AGENTS.md for Enterprise Edition boundaries and use ee/.agents/ for EE-specific rules, workflows, and docs.

Common Workflows Copy Chapter

Usage Rules Copy Chapter

• Do not read the whole .agents tree by default. Start with AGENTS.md, then open only the relevant rule, workflow, or doc.
• Keep tool-specific instructions in adapter files such as CLAUDE.md; keep shared behavior here.
• Do not move user-facing product documentation into this directory. Public docs belong under docs/.
• When adding new agent guidance, prefer a focused workflow or rule over expanding always-loaded instructions.
• After changing agent instructions, run dev/check-agent-instructions.sh.

Overview (`cli/README.md`) Copy Section

WhoDB CLI

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

Features Copy Chapter

• 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
• Hosted Platform Commands - Browser login, workspace selection, manifest inspection, and hosted source management
• Agent Manifest - Machine-readable command, source, MCP, workflow, and safety metadata
• Database Doctor - Redacted connection and metadata diagnostics for support and AI agents
• Built-in Runbooks - Repeatable workflows for connection checks, schema audits, and schema diffs
• Assistant Integration Installer - Install bundled WhoDB skills, agents, MCP configs, and rule files into local assistant directories
• MCP Server - Model Context Protocol server for AI assistants (Claude, Cursor, etc.)

Installation Copy Chapter

Native Install (Recommended) Copy Section

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

Linux note: if the WhoDB desktop snap is installed, it also provides a whodb command at /snap/bin/whodb. Which one runs depends on your PATH order.

Renamed from whodb-cli: the command used to be whodb-cli. The installer, Homebrew formula, npm package, and Docker image all still provide a deprecated whodb-cli alias that prints a warning and forwards to whodb. The alias will be removed in a future release — update any scripts or configs to use whodb.

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) Copy Section

brew install whodb-cli

The formula is named whodb-cli (the whodb name is used by the desktop app cask), but it installs the whodb command.

npm Copy Section

npm install @clidey/whodb

Or with npx (no install):

npx @clidey/whodb

From Source Copy Section

Requires Go 1.21+:

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

Or using the Makefile:

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

Using Docker Copy Section

# 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 Copy Section

whodb --version
whodb --help

Quick Start Copy Chapter

For hosted WhoDB platform login and source management, see
the hosted platform CLI guide.
For task-oriented MCP catalogs, unattended service-account jobs and security
ledger access, see platform operations.

1. Connect to a Database Copy Section

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

whodb connect

PostgreSQL

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

PostgreSQL (non-interactive password)

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

PostgreSQL with SSL

whodb 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 connect --discovered aws-prod-us-west-2/prod-db

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

MySQL

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

SQLite

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

MongoDB

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

1b. Use Environment Profiles Copy Section

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 Copy Section

# Start the database TUI
whodb --tui

3. Execute a Quick Query Copy Section

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

Commands Copy Chapter

Root Command (Interactive Mode) Copy Section

Running whodb without arguments starts the interactive TUI.

whodb [flags]

Flags:

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

connect Copy Section

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

whodb 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 Copy Section

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

whodb 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 Copy Section

Show backend-generated query suggestions for a connection.

whodb suggestions --connection my-postgres
whodb 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 Copy Section

Generate or install shell completion scripts.

# Show help
whodb completion

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

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

# Install for specific shell
whodb completion install bash

# Uninstall completion
whodb completion uninstall

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

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

Programmatic Commands Copy Chapter

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.

agent schema Copy Section

Emit a machine-readable manifest of WhoDB's agent-facing surface. The manifest includes source types, connection fields, programmatic commands, MCP tools, platform MCP prompts/resources, safety modes, and built-in workflows.

whodb agent schema --format json

Flags:

• --format, -f: Output format: json

doctor Copy Section

Run redacted connection, schema, and metadata diagnostics for one connection.

whodb doctor --connection my-postgres
whodb doctor --connection my-postgres --schema public --format json

Flags:

• --connection, -c: Connection name to inspect
• --schema, -s: Schema override for metadata checks
• --format, -f: Output format: table or json
• --quiet, -q: Suppress informational messages

runbooks Copy Section

List, describe, and run built-in database workflows. Built-in runbooks are intentionally limited to WhoDB operations.

# List available workflows
whodb runbooks list

# Inspect a workflow
whodb runbooks describe schema-audit

# Show planned steps without executing
whodb runbooks run schema-audit --connection my-postgres --dry-run

# Run a schema audit
whodb runbooks run schema-audit --connection my-postgres --schema public --format json

# Compare two environments
whodb runbooks run schema-diff --from staging --to prod --format json

Built-in runbooks:

• 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

Flags:

• --format, -f: Output format: table or json
• --quiet, -q: Suppress informational messages
• run --connection, -c: Connection name for connection-doctor and schema-audit
• run --schema, -s: Schema override
• run --from: Source connection for schema-diff
• run --to: Target connection for schema-diff
• run --from-schema: Source schema override for schema-diff
• run --to-schema: Target schema override for schema-diff
• run --dry-run: Show planned steps without executing

skills Copy Section

List bundled WhoDB assistant skills and install native assistant integrations.

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

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

# Install one skill
whodb skills install query-builder --target-dir ~/.codex/skills

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

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

# Preview files without modifying disk
whodb skills install --target cursor --dry-run

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

Flags:

• --format, -f: Output format: table or json
• --quiet, -q: Suppress informational messages
• install --target: Assistant target to install. Supported values are listed above
• install --target-dir: Directory where skills should be installed
• install --agents-dir: Directory where agents should be installed
• install --include-agents: Install bundled Markdown agents as well as skills. With --target, this is supported for claude-code; use --agents-dir for any custom agent destination
• install --force: Overwrite existing installed files
• install --dry-run: Show files that would be written without modifying disk

explain Copy Section

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

whodb explain --connection my-postgres "SELECT * FROM users"
whodb 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 Copy Section

List database schemas.

whodb 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 Copy Section

List tables in a schema.

whodb 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 Copy Section

Describe table columns.

whodb 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 Copy Section

Manage saved connections.

# List connections
whodb connections list --format json

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

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

# Remove a connection
whodb 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 Copy Section

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 cloud providers list

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

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

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

diff Copy Section

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 diff --from staging --to prod

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

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

# Emit machine-readable JSON
whodb 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 Copy Section

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

whodb erd --connection my-postgres
whodb 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 Copy Section

Export table data or query results to file.

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

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

# Export query results
whodb 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 Copy Section

Access query history.

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

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

# Clear history
whodb 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 Copy Section

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

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

profiles Copy Section

Manage the same saved connection profiles used by the TUI.

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

Startup modes Copy Chapter

Bare whodb shows saved platform login/workspace metadata and next commands;
whodb status checks the live login. Use whodb --tui for the existing database
terminal UI. Explicit connect, query, and --profile behavior is unchanged.

whodb setup saves the modules and access settings used by whodb mcp serve.
Platform tools are enabled by default. Enable database-only tools or both modules
in setup; every configuration uses the same MCP command. --database remains an
advanced override for a database-only process, and --platform remains a
compatibility override for platform-only tools. Both modules support stdio and
HTTP transports; database-only does not imply that the database is local.

Guided MCP setup Copy Chapter

Run whodb setup once. The wizard lets you choose modules, write access, hosts,
database connections, and optional restrictions. It previews the settings before
saving, offers browser sign-in for platform hosts, and can verify connections.
Existing settings are the defaults when you run the wizard again. You can also
choose an optional default platform workspace using canonical organization and
project IDs. Password entry is hidden and passwords are stored through the existing CLI credential store.

Keep one entry in your MCP client:

{
  "mcpServers": {
    "whodb": {"command": "whodb", "args": ["mcp", "serve"]}
  }
}

Agent-guided setup Copy Section

MCP is self-sufficient; skills are optional supplements. The server supplies
startup instructions, tool descriptions, schemas, workflow guidance, and recovery
steps. If a WhoDB skill is installed, agents may use it as additional guidance;
no essential setup or usage instructions require it.

An agent with MCP access alone can call whodb_mcp_setup:

1. action: "inspect" returns saved settings, allowed target metadata, choices,
   schema, active process settings, and usage guidance.
2. action: "preview", patch: {...} validates changes without saving and returns
   the proposed settings and a confirmation token.
3. After showing the exact preview and obtaining user approval,
   action: "apply", confirmation_token: "...", approved: true saves that preview.
   Do not include a patch in apply. Tokens expire after five minutes, are consumed
   by apply, and are replaced by a newer preview. Changed saved settings invalidate
   the preview.
4. Restart the MCP connection after changes, then action: "verify" checks active
   host logins, workspaces, and database connections. Until restart, verification
   uses the original process settings.

The setup tool manages local MCP configuration, including access restrictions;
it always requires preview approval to save, even in allow-write mode. It follows
normal tool filters: include whodb_mcp_setup when using an explicit enabled-tool
list, or disable it to keep configuration management outside the agent. Changes
never relax the current process's controls. Startup flags still override saved
settings after restart. Browser sign-in and credential entry remain user actions;
agents can relay the required commands without needing shell access.

Agents with shell access can also use the non-interactive JSON commands:

whodb setup inspect
whodb setup validate --file setup.json
# After the user approves the proposed settings:
whodb setup apply --file setup.json --yes
whodb setup verify

inspect returns current settings, available target metadata, tool choices and a
settings schema. validate previews the merged settings without saving. apply
requires --yes and reports whether a restart is needed. verify checks the
configured host logins and database connections, reporting each failure and next
command. Authentication is separate: use whodb login --host for browser
sign-in. Agents must not request passwords or tokens in chat or setup JSON.

Example setup.json enabling both modules with production read-only:

{
  "modules": ["platform", "database"],
  "write_mode": "confirm",
  "platform_policy": {
    "allowed_hosts": ["https://uat.whodb.com", "https://app.whodb.com"],
    "read_only_hosts": ["https://app.whodb.com"]
  },
  "allowed_connections": ["development"]
}

Settings patches preserve omitted fields; arrays replace existing arrays. Use
[] to clear a tool/connection allowlist and "platform_policy": null to clear
platform restrictions. The empty allowlists mean unrestricted access. Unknown
fields are rejected. Settings are saved in the mcp section of WhoDB's existing
configuration file; applying a settings patch does not rewrite the credential or
connection section. Use --file - to supply a patch on stdin.

Restart an existing MCP connection after changing modules or access settings.
An optional default_workspace uses {host, org, project} with canonical IDs.
Explicit process flags or session environment variables replace that saved
default target; calls with workspace still override it. Platform policies apply
to platform tools; database tools use allowed_connections and the shared
write_mode.

Host/project targeting remains per-call: platform tools accept workspace,
database-only tools accept connection. You do not need another MCP entry or a
restart to target a different saved host/project. Read whodb://mcp/configuration
for the running server's active modules and restrictions. Explicit startup flags
override saved settings for that process without saving those overrides.

To keep one chat on one host (for example UAT in one Claude Code or Codex window
and production in another) without separate MCP entries, the agent calls
whodb_platform_session_use with workspace {host, org, project} once. That
default applies to later calls in that MCP session only, is never written to
disk, and is removed with whodb_platform_session_clear.
whodb_platform_status shows it as session_scope. Resolution order for a call
without workspace: session default, then process flags/environment, then the
saved CLI default. whodb use changes the saved default for every session, so
it is the wrong tool for switching a single chat.

MCP Server Copy Chapter

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

Access modes Copy Section

The default supports reads and writes, with confirmation required before writes
execute. Platform tools always enforce the signed-in user's platform permissions.
For direct database tools, access is limited by the configured database account's
privileges; platform permissions do not apply to those connections.

• Default (whodb mcp serve): reads and confirmed writes.
• --read-only: restrict operations to reads.
• --safe-mode: read-only with strict security checks.
• --allow-write: execute writes without the MCP confirmation step, for trusted
  automation. Database and platform permissions still apply.

Saved setup settings can select a different default. Inspect them with
whodb setup inspect; restart the MCP connection after changing access modes.

Start the MCP Server Copy Section

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

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

The platform module exposes whodb_platform_* tools. Enable the database module
in whodb setup to expose the following tools in the same server:

Without saved settings, only the platform module is enabled. Setup can enable
either module or both together.
--tools and --disable-tools work in both modes. Platform mode uses full
whodb_platform_* names; database-only mode uses short names such as query.

Platform access policy and tool selection Copy Section

Save platform_policy through setup to restrict access independently of saved
logins. The advanced --platform-policy policy.json flag overrides that policy
for one process. For example, allow two hosts but keep production read-only:

{
  "allowed_hosts": ["https://uat.whodb.com", "https://app.whodb.com"],
  "read_only_hosts": ["https://app.whodb.com"]
}

whodb mcp serve --platform-policy policy.json
whodb mcp serve --tools whodb_platform_hosts,whodb_platform_workspace_resolve,whodb_platform_sources
whodb mcp serve --disable-tools whodb_platform_source_delete,whodb_platform_delete

For project restrictions, add allowed_workspaces or read_only_workspaces:

{
  "allowed_workspaces": [
    {"host": "https://uat.whodb.com", "org": "<org-id>", "project": "<project-id>"},
    {"host": "https://app.whodb.com", "org": "<org-id>", "project": "<project-id>"}
  ],
  "read_only_workspaces": [
    {"host": "https://app.whodb.com", "org": "<org-id>", "project": "<project-id>"}
  ]
}

Policy workspace entries require canonical organization and project IDs, not
names or slugs. Tool calls can still resolve names through workspace.
When a policy is configured, include matching workspace.org and
workspace.project when using tools with top-level org or project arguments. Host and workspace allowlists intersect; omitted or
empty allowlists impose no restriction. Read-only rules override --allow-write
and also apply when confirming an earlier preview. Global --read-only remains
stricter than any per-target setting. Discovery lists omit disallowed targets.
The policy is loaded at startup; restart MCP after changing it.

Tool disabling takes precedence over enabling. Unknown platform tool names are
rejected at startup. Include whodb_platform_confirm and whodb_platform_pending
when selecting tools that need write confirmation. Tool filtering controls tool
availability; generic write tools can support overlapping operations. Use
read-only policies to block all writes to a target. Platform authorization still
applies to every request.

whodb://platform/schema reports the active access policy and enabled tools.
Failed operations set MCP isError while preserving structured error details,
request IDs, scope, and recovery guidance when supplied by the handler.

Per-call workspace targeting Copy Section

whodb mcp serve exposes hosted platform tools. Sign in to each required host with
whodb login --host . Start with whodb_platform_hosts to discover saved
hosts and accounts, then whodb_platform_orgs with workspace: {host} and
whodb_platform_projects with workspace: {host, org}.

Resolve the intended target with whodb_platform_workspace_resolve. Pass an
explicit workspace: {host, org, project} on subsequent tools when working across
UAT, production, or projects. Targets apply to one call, including parallel calls,
and never change saved defaults. Check the returned scope. Do not run whodb use
to switch another session's defaults. Omitted targets use process overrides, then
saved defaults. Read whodb://platform/schema for operations and payloads.

Writes return a preview bound to its host, account, organization, and project.
Confirm only after approval of that exact preview. Changing defaults does not
redirect a pending confirmation. Persisted workflow plans from before account
binding must be recreated before applying them. Ask for whodb login --host when a host
needs authentication; no separate login is needed per project.

Example arguments for whodb_platform_sources:

{"workspace":{"host":"https://uat.whodb.com","org":"acme","project":"analytics"}}

An explicit host uses that host's saved defaults. An explicit organization clears
any inherited project; project-scoped operations then require a project. Invalid
or ambiguous selectors fail instead of using another workspace. Host discovery
reads local metadata; it does not claim the saved login is still valid.

Hosted setup:

# Sign in to app.whodb.com
whodb login

# Optional: save a default for calls without an explicit workspace
whodb use --org <org> --project <project>

# Start stdio MCP for your MCP client
whodb mcp serve

# Read-only hosted platform MCP
whodb mcp serve --read-only

# Hosted writes without confirmation; use only for trusted automation
whodb mcp serve --allow-write

To capture an actual rendered app with its current data, use the app commands
or the whodb_platform_app_views and whodb_platform_app_screenshot MCP tools.
The MCP screenshot tool returns WebP image content directly to the model. Both
paths use the selected hosted workspace and are available in read-only mode.

whodb apps views "Clidey Sales" --org clidey-erp --project erp-demo --env dev
whodb apps screenshot "Clidey Sales" --org clidey-erp --project erp-demo \
  --env dev --tab Catalog --output sales-catalog.webp
whodb apps setup-capture
# Or install the optional browser on demand when taking a screenshot:
whodb apps screenshot "Clidey Sales" --install --org clidey-erp --project erp-demo

For a specific page or interactive state, list pages first, then pass --page.
Use --click for a visible app control, or --actions for an ordered sequence.
Selectors are Playwright selectors inside the app frame. Each action selector
must match one element; scope repeated text to a node or table row. --js evaluates a
JavaScript expression or IIFE in that frame after the actions; --script-file
reads the expression from a file. JSON output includes the screenshot path,
visible text, browser console errors, page errors, failed requests, HTTP error
responses, and the JavaScript result.
For content loaded after mount, include a wait_for action on an expected row
or control so the screenshot captures the loaded state.
An assertion in --js can throw an error. The command still saves the screenshot
and JSON diagnostics, sets checks_passed to false, and exits nonzero.
checks_passed confirms that actions ran and explicit wait_for or JavaScript
assertions passed; a click alone does not prove the app reached an intended view.

whodb apps views "Clidey Sales" --org clidey-erp --project erp-demo --env dev
whodb apps screenshot "Clidey Sales" --org clidey-erp --project erp-demo \
  --env dev --page main --click 'text=Orders' \
  --js '(() => ({ rows: document.querySelectorAll("tr").length }))()' \
  --output sales-orders.webp --format json

# Capture the same app with mobile viewport and touch behavior.
whodb apps screenshot "Clidey Sales" --mobile --org clidey-erp --project erp-demo \
  --output sales-orders-mobile.webp

# Capture a tablet in landscape orientation.
whodb apps screenshot "Clidey Sales" --tablet --orientation landscape \
  --org clidey-erp --project erp-demo --output sales-orders-tablet.webp

The MCP screenshot tool accepts the same page, tab, actions, script, mobile, tablet, and orientation
inputs, so an agent can click, fill, press, wait for a selector, or inspect DOM
state without creating a Playwright script. For example, use an action
{"kind":"click","selector":"text=Orders"} followed by a script
"(() => document.querySelectorAll('tr').length)()".
Set trace: true to request an interaction trace from a compatible hosted runtime.

App capture needs Node.js and npm. setup-capture installs Playwright and
Chromium in the user's cache; --install does the same before capturing.
Without them, the command and MCP tool return setup instructions. Existing
Playwright installations in the WhoDB source checkout work without setup.
apps screenshot and the MCP screenshot tool only allow hosted GraphQL reads
by default. Use --allow-writes for a function call or another mutation.
apps dev and apps verify have their own write setting, described below.
Captures never upload or publish the image.
Inspect sample data and loading states before using a capture as product media.

Build an app from a local folder Copy Section

An app folder contains app.json, pages//tree.json, page scripts and
state, and optional shared/ files. app.json declares name, defaultPage,
and optional ontologies, readOnlyOntologies, and functions arrays. Resource
entries use the ontology API name or function name; the CLI resolves them to IDs
in the selected project. App scripts use the normal ctx.whodb browser API for
ontology and function calls.

whodb apps init ./orders --name Orders
whodb apps check ./orders --format json

# Or start from an existing hosted app's draft files and bindings.
whodb apps init ./existing-orders --from <app-id-or-name> --org <org> --project <project>

# Create the hosted app identity and bind its resources without promoting it.
whodb apps publish ./orders --draft --org <org> --project <project>

# Files are read from disk on each reload; edits are not uploaded.
whodb apps dev ./orders --org <org> --project <project>

# Replay the generated scenario, save a WebP, and return a JSON flow trace.
whodb apps verify ./orders --scenario ./orders/scenarios/smoke.json \
  --output /tmp/orders.webp --format json --org <org> --project <project>

# Replay the same flow at a phone viewport.
whodb apps verify ./orders --mobile --scenario ./orders/scenarios/smoke.json \
  --output /tmp/orders-mobile.webp --format json --org <org> --project <project>

# Replay at the default tablet viewport.
whodb apps verify ./orders --tablet --scenario ./orders/scenarios/smoke.json \
  --output /tmp/orders-tablet.webp --format json --org <org> --project <project>

# Sync changed and deleted files, then promote the resulting app version.
whodb apps publish ./orders --message "Orders v1" --org <org> --project <project>

apps check validates file structure and handler references; it does not render
the app or verify scroll behavior.
apps dev and apps verify use the hosted app runner and its existing resource
permissions while replacing app files with the local folder in the browser.
For a desktop app with a sidebar that should stay visible, make the main pane
the scroll container: set the root Row to viewport height with hidden overflow,
the sidebar to full height with auto overflow, and the main Col to full height
with minH: 0 and auto overflow. Test a page longer than the viewport by
scrolling the main pane; a full-height root with overflowing content makes a
sticky sidebar move with the outer app viewport.
apps init --from creates a new local folder from the selected app's readable
draft files, preserving existing app.json settings and writing resource names
for version control. It refuses to overwrite an existing folder. The hosted app
is unchanged; pass its ID with --app to apps dev, apps verify, or
apps publish if you rename the local app.

apps dev and apps verify require an app in the selected project with the same resource bindings as
app.json. Use --app when the hosted name differs. Both commands
allow app actions to write to the selected project's data by default; pass
--allow-writes=false only when the preview needs GraphQL queries and no
function calls. Every ctx.whodb.call() uses a GraphQL mutation, including
reporting functions, and is blocked by that flag. Local app files are overlaid
in the browser, while ontology and function calls still use the selected hosted
project. Select an isolated development project for workflow tests, and keep
--host, --org, and --project aligned with the MCP workspace you inspected.
MCP read-only mode does not change the CLI preview's write setting. Both CLI
commands require Node.js and the optional capture browser (apps setup-capture
or --install).
--mobile on apps screenshot or apps verify uses a 390x844 viewport with
mobile and touch emulation. Pass --width and --height with it to test another
phone size. --tablet uses an 820x1180 touch viewport. Add --orientation landscape to rotate either device preset; explicit --width and --height
can set another size. Default filenames include -landscape when applicable.
When testing a locally built app runtime, pass the directory containing
sandbox.html, sandbox-kernel.js, and sandbox-kernel.css with --kernel-dir
or WHODB_APP_KERNEL_DIR. Flow tracing requires a compatible runtime;
apps dev can use the hosted runtime for visual preview.

A scenario is JSON with an actions array. It accepts click, fill, press,
wait_for, wait, expect_text, and expect_not_text actions. Selectors run
inside the app frame; stable node IDs can be selected with
[data-node-id='save-button']. For text repeated in multiple tables, scope the
selector to a table, such as [data-node-id='attention-table'] tbody tr:first-child.
An empty value on fill clears an input. apps verify waits for handlers and bridge calls
to settle, then outputs visible text, browser diagnostics, and a trace of
handlers, state writes, navigation, and WhoDB calls. It exits nonzero on a failed
assertion or runtime error. apps publish --dry-run reports file changes without
writing them. File writes update the draft one at a time; an interrupted sync
can be completed by rerunning the command. Published file content changes only
after promotion; changes to the app's resource bindings take effect when the
draft metadata is updated.

MCP clients can read whodb://platform/app-workflow or request the
whodb_platform_build_app_workflow prompt for the app build sequence. The prompt
guides the agent through a brief-specific visual plan, real data and SDK contracts,
working interactions, and screenshot critique across viewports. MCP prompts are
client-requested; the server instructions point app-building agents to this prompt.
The whodb_platform_workflow_recipe tool also returns an app-specific plan. Hosted
MCP tools can inspect and edit hosted draft files and capture hosted views.
whodb_platform_app_screenshot accepts trace: true on runtimes that support
interaction tracing. whodb_platform_app_components,
whodb_platform_app_component, whodb_platform_app_sdks, and
whodb_platform_app_sdk read the same reference material as the in-app builder
when the hosted platform advertises that capability.
whodb_platform_app_logic_graph runs the builder's interaction and function
contract audit on an authorized hosted draft. A
client needs local filesystem and CLI access to use apps init, apps dev,
apps verify, and apps publish against a version-controlled folder.

Local or staging setup:

whodb login --host http://localhost:8080
whodb use --host http://localhost:8080 --org <org> --project <project>
whodb mcp serve

Recommended MCP client behavior:

1. Read whodb://platform/tool-guide to understand the active platform MCP
   mode, available tool categories, field projection guidance, and write
   behavior.
2. Call whodb_platform_status before project-scoped reads or writes.
3. Use fields on hosted read tools whenever supported. Start narrow, for
   example ["id", "name", "type"], and request heavier fields only when
   needed.
4. For writes in default mode, explain confirmation_preview to the user and
   call whodb_platform_confirm only after the user approves that exact
   preview.
5. In --allow-write, hosted writes execute immediately, so ask the user before
   calling the mutating tool itself.

Most hosted read tools accept a fields array. Agents should request only the
fields needed for the current answer, for example ["id", "name"], then call
again with additional fields only when needed. Backend permissions still decide
what the signed-in user can see or change.

Platform mode uses the same permission modes as local MCP. By default, hosted
create, update, delete, and action tools return confirmation tokens and do not
execute until approved with whodb_platform_confirm. --read-only and
--safe-mode hide hosted write tools entirely. --allow-write executes hosted
writes immediately without confirmation.

Hosted create, update, delete, and action tools return confirmation tokens by
default and do not execute until approved with whodb_platform_confirm. Use
whodb_platform_pending to recover active confirmation tokens. Agents should
explain the returned confirmation_preview to the user before confirming,
especially for delete, deploy, move, and source/object changes.

Answering data questions

Agents answer questions about ontology data without paging through rows:

1. whodb_platform_ontology_describe to learn entity and property names.
2. whodb_platform_ontology_stats to profile the properties involved.
3. whodb_platform_ontology_aggregate for exact totals and group-bys, or
   whodb_platform_ontology_query for filtered rows, free-text search, joins
   and in-memory metrics. The query scans at most scan_limit rows (default
   1000, max 5000) before filtering, so prefer the aggregate for large entities.
4. whodb_platform_ontology_rows or whodb_platform_ontology_follow_link to
   drill into the rows behind a number.

Every ontology read tool accepts the same where object: {prop: value},
{prop: {op: value}} and _and / _or lists with operators eq, neq,
gt, gte, lt, lte, contains, icontains, startswith, in, nin,
between and isnull. The aggregate, stats and similarity tools translate it
to the platform WhereCondition for you; a raw WhereCondition object is still
accepted. Organization-scoped actions default orgId to the selected
organization, so it only needs to be passed when targeting another organization.

Bulk inserts, run control, restore and purge

• whodb_platform_add_ontology_records inserts many rows in one confirmation
  and accepts an idempotency_key so a retried call never duplicates rows.
• whodb_platform_action with resource function_run and action cancel,
  resource transform and action cancel_run, or resource app and action
  cancel_generation stops work that is still running.
• whodb_platform_restore now covers project, file and folder; the
  matching purge actions permanently delete soft-deleted resources, and
  purge_data on an ontology or dataset empties it while keeping the
  definition.
• Service accounts are managed through whodb_platform_action on the
  organization resource: create_service_account,
  create_service_account_key (the rawKey is returned once),
  revoke_service_account_key and delete_service_account.
• Ontologies are shared with share / unshare actions and consumed from
  another project through the ontology_reference resource.

The same capabilities are available from the CLI: whodb ontologies query|aggregate|stats|explain|similar, whodb ontologies records add-many,
whodb functions runs cancel, whodb transforms cancel-run, whodb projects restore|purge, whodb service-accounts ..., and generically whodb resources action <resource> <action> or whodb resources query <Operation>.

Security model:

• The hosted platform remains the authorization boundary. The CLI sends the
  signed-in user's token and selected workspace; the backend still decides what
  that user may read or mutate.
• Workspace IDs are selectors, not proof of access. Pending confirmations store
  the host, organization, and project and re-check them before execution.
• Source config reads return redacted values, secret listing tools return
  metadata only, and confirmation previews include changed field names rather
  than credential values.

For source creation, agents should call whodb_platform_source_types and
whodb_platform_source_fields first so they use backend-published source type
ids and field names.

If no workspace is selected yet, agents should discover saved hosts with
whodb_platform_hosts, then call whodb_platform_orgs with workspace: {host}
and whodb_platform_projects with workspace: {host, org}. Resolve the chosen
target with whodb_platform_workspace_resolve and pass its canonical IDs in
workspace on subsequent calls. whodb use is optional for saving a default.
For single-workspace accounts, hosted login or status can select the only
organization/project automatically and report what was selected.

Example hosted platform MCP config:

{
  "mcpServers": {
    "whodb-platform": {
      "command": "whodb",
      "args": ["mcp", "serve"]
    }
  }
}

For read-only access, save {"write_mode":"read-only"} through setup. The MCP
client entry remains the same:

{
  "mcpServers": {
    "whodb-platform-readonly": {
      "command": "whodb",
      "args": ["mcp", "serve"]
    }
  }
}

Example local or staging platform MCP config:

{
  "mcpServers": {
    "whodb-platform-local": {
      "command": "whodb",
      "args": ["mcp", "serve"]
    }
  }
}

One MCP server can use multiple saved host logins. Sign in to each host with
whodb login --host , then pass workspace: {host, org, project} per tool
call to target local, UAT, or production workspaces without restarting the MCP
server or changing saved defaults. Without an explicit target, the server uses
its process overrides and then saved defaults.

Database-only MCP exposes these resources:

Platform MCP exposes these resources instead:

The same metadata is available from whodb agent schema --format json.
Its platform_mcp section describes the default platform mode, default host,
login/workspace requirements, field projection support, platform-only tool
prefix, platform prompts/resources, and write behavior for confirm, read-only,
safe, and allow-write modes.

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

Upload review and confirmation limitations

For file uploads, the write plan, confirmation preview, and pending-action list
show the full absolute source path, destination host and project, and folder ID
(null means the project root). The summary quotes the path and escapes control
characters. Relative paths are resolved against the MCP server's working
directory when the action is prepared; confirmation uses that stored absolute
path. A literal ~ is not expanded to the user's home directory.

The CLI reads file contents only when the upload executes. The preview approves
a path, not an immutable file snapshot: replacing the file or changing a symlink
before execution can change the uploaded contents. This flow does not sandbox
local file access; the CLI can read files permitted by its operating-system
identity.

A confirmation token does not independently prove human approval. The model
receives the token and can call whodb_platform_confirm. The assistant is
instructed to ask the user first, but an independent approval guarantee requires
the MCP host or another trusted interaction outside the model's control to
enforce that approval. Clear previews support informed review; they do not
prevent a malicious or prompt-injected model from calling available tools.
Use --read-only or --safe-mode to hide hosted write tools when writes are not
needed. --allow-write executes uploads without the CLI confirmation step.

Upload source paths are intentionally visible to the MCP client for review.
They are excluded from WhoDB upload telemetry; client-side logging and retention
are controlled by the MCP host. Other sensitive fields remain redacted, and
persisted workflow payloads still reject local file paths.

Transport Modes Copy Section

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

whodb mcp serve

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

whodb 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 Copy Section

MCP Flags Copy Section

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)

Hosted Platform:

• --database: Expose database-only MCP tools instead of platform tools.
• --platform: Compatibility alias for the default; prints a notice to stderr.

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

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

# Combine: restrict to prod/staging, default to staging
whodb mcp serve --database --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 Copy Section

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 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) Copy Section

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

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

Docker MCP Server Copy Section

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 --database

Interactive Mode Views Copy Chapter

1. Connection View Copy Section

Select and manage database connections.

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

2. Browser View Copy Section

Navigate schemas and tables in a visual grid layout.

3. Editor View Copy Section

Write and execute SQL queries with schema-aware autocomplete.

Features:

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

4. Results View Copy Section

View query results in a responsive, paginated table.

Features:

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

5. History View Copy Section

Browse and re-execute past queries.

6. AI Chat View Copy Section

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

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

7. Export View Copy Section

Export data to CSV or Excel format.

Configuration Copy Chapter

Config File Location Copy Section

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.

Config Structure Copy Section

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

Database and SSH passwords are stored in the OS keyring. If it is unavailable,
saving passwords requires explicitly setting
WHODB_CLI_ALLOW_PLAINTEXT_CREDENTIALS=true; they are then written to
config.json (new files are created with 0600 permissions). A failed keyring
write aborts saving. Hosted login refresh tokens always require secure storage.

Environment Variables Copy Section

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

Docker Usage Copy Chapter

Run Interactively Copy Section

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

Connect to Host Database Copy Section

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

Execute Query Copy Section

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

Persist Configuration Copy Section

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

Environment Variables Copy Section

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

Keyboard Reference Card Copy Chapter

Global Copy Section

Navigation (Vim-style) Copy Section

Common Actions Copy Section

Troubleshooting Copy Chapter

Connection Issues Copy Section

"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

Display Issues Copy Section

"Garbled text / incorrect colors"

# Set terminal type
export TERM=xterm-256color

Recommended terminals: iTerm2, Alacritty, Windows Terminal, Kitty

Configuration Issues Copy Section

"Config not found"

mkdir -p ~/.local/share/whodb
whodb 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

Debug Mode Copy Section

whodb --debug

Architecture Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Development Copy Chapter

# Run in development mode
go run .

# Run tests
go test ./...

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

# Lint
golangci-lint run ./...

License Copy Chapter

Apache License 2.0 - See LICENSE file for details.

HTTP MCP authentication and credential storage Copy Section

HTTP MCP listeners bound outside loopback require --auth-token or
WHODB_MCP_AUTH_TOKEN. Clients send that value as a bearer token on /mcp.
Loopback HTTP and stdio retain their local defaults.

Saving database or SSH passwords requires the OS keyring. If it is unavailable,
plaintext storage requires the explicit environment setting
WHODB_CLI_ALLOW_PLAINTEXT_CREDENTIALS=true; the config file has mode 0600.
A failed keyring write aborts saving instead of copying passwords to disk.
Hosted login refresh tokens always require secure storage.

Platform collection tools use server-side metadata pages when the host advertises
PlatformResources: 50 items by default, at most 100, with offset and
truncated indicating continuation. Filters run before pagination and access
checks run before rows are selected. Use the corresponding detail tool for full
source, schema, bindings, or usage. Explicit function, ontology, dataset, and app
fields can fetch details for the selected page. Older hosts retain their existing
list contract.

Platform wait tools return the latest observed running status with a warning when
their wait budget expires; repeat with the same run ID. Write idempotency keys are
limited to 200 bytes and scoped to the account, workspace, and operation. Matching
completed requests replay bounded identifiers/status for 30 days; secret values
and job output are never retained for replay. Conflicting payloads are rejected.

Overview (`desktop-common/README.md`) Copy Section

WhoDB Desktop Application

This is the WhoDB desktop application built with Wails, providing a native window experience while maintaining full compatibility with the web version. Available in both Community Edition (CE) and Enterprise Edition (EE).

Prerequisites Copy Chapter

1. Install Wails CLI (version is pinned in desktop-common/go.mod):

   bash Copy

   make install-wails

2. Check dependencies:

   bash Copy

   wails doctor

3. Platform requirements:

   • Windows: WebView2 (pre-installed on Windows 10/11)
   • macOS: Xcode Command Line Tools (xcode-select --install)
   • Linux: gcc, libgtk-3, libwebkit2gtk-4.1

Quick Start Copy Chapter

Running the Desktop Application Copy Section

Navigate to the edition directory and use make commands:

# Community Edition
cd desktop-ce
make dev       # Development mode with hot reload
make build     # Build for current platform
make help      # See all available commands

# Enterprise Edition
cd ee/desktop
make dev       # Development mode with EE features
make build     # Build for current platform
make help      # See all available commands

Build Commands Copy Chapter

Development & Basic Builds Copy Section

make dev              # Run in development mode with hot reload
make build            # Build for current platform
make build-all        # Build for all platforms
make build-windows    # Windows AMD64 & ARM64
make build-mac        # macOS Universal Binary
make build-mac-arm64  # macOS ARM64 only (Apple Silicon)
make build-mac-amd64  # macOS AMD64 only (Intel)
make build-linux      # Linux AMD64 & ARM64

Production Builds Copy Section

make build-prod-windows     # Windows NSIS installer with UPX
make build-prod-mac         # macOS Universal Binary
make build-prod-mac-arm64   # macOS ARM64 only
make build-prod-mac-amd64   # macOS AMD64 only
make build-prod-linux       # Linux binary with UPX compression

macOS Packaging & Signing Copy Section

# Create unsigned .pkg
make package-mac

# Sign app and .pkg
make package-mac-signed \
  CODESIGN_ID="Developer ID Application: Your Name (TEAMID)" \
  INSTALLER_ID="Developer ID Installer: Your Name (TEAMID)"

# Notarize for distribution
make notarize-mac \
  NOTARY_PROFILE="WhoDBNotary"
# or
make notarize-mac \
  APPLE_ID="[email protected]" \
  TEAM_ID="TEAMID" \
  APPLE_APP_PASSWORD="app-specific-password"

# One-shot GitHub Release (build + sign + notarize)
make release-mac \
  CODESIGN_ID="..." \
  INSTALLER_ID="..." \
  NOTARY_PROFILE="WhoDBNotary"

# Create DMG for drag-and-drop install
make dmg-mac
make release-dmg  # DMG with signing and notarization

Mac App Store Build Copy Section

make macstore-mac \
  MAS_CODESIGN_ID="Apple Distribution: Your Name (TEAMID)" \
  MAS_INSTALLER_ID="3rd Party Mac Developer Installer: Your Name (TEAMID)" \
  MAS_PROFILE=/path/to/embedded.provisionprofile \
  MAS_ENTITLEMENTS=/path/to/entitlements.plist

Output Files Copy Chapter

Binaries are generated in build/ organized by platform:

Community Edition (desktop-ce) Copy Section

• Windows: build/windows/[arch]/whodb-ce.exe
• macOS Universal: build/darwin/universal/WhoDB.app
• macOS ARM64: build/darwin/arm64/WhoDB.app
• macOS AMD64: build/darwin/amd64/WhoDB.app
• Linux: build/linux/[arch]/whodb-ce

Enterprise Edition (ee/desktop) Copy Section

• Windows: build/windows/[arch]/whodb-ee.exe
• macOS Universal: build/darwin/universal/WhoDB - Enterprise.app
• macOS ARM64: build/darwin/arm64/WhoDB - Enterprise.app
• macOS AMD64: build/darwin/amd64/WhoDB - Enterprise.app
• Linux: build/linux/[arch]/whodb-ee

Note: Architecture-specific macOS builds (arm64/amd64) are optimized single-architecture builds that will be smaller than the universal binary (~50% size reduction) since they only contain code for one architecture.

Manual Build (Advanced) Copy Chapter

If you need to build manually without Make:

# Community Edition
cd desktop-ce
GOWORK=$PWD/../go.work.desktop-ce wails build -o whodb-ce

# Enterprise Edition
cd ee/desktop
wails build -o whodb-ee

Architecture Copy Chapter

The desktop application:

1. Uses the same Go backend as the web version
2. Embeds the React frontend build
3. Serves through a native window instead of browser
4. Routes all API calls through the same Chi router/GraphQL endpoint
5. Maintains full compatibility with all database plugins
6. EE includes all enterprise features and additional plugins

Workspace Structure Copy Section

• CE workspace (go.work.desktop-ce):

  • ./core - Core WhoDB functionality
  • ./desktop-ce - CE desktop module
  • ./desktop-common - Shared desktop code

• EE workspace (ee/go.work.desktop):

  • ../core - Core WhoDB functionality
  • . - Enterprise Edition modules (ee)
  • ./desktop - EE desktop module
  • ../desktop-common - Shared desktop code

Development Tips Copy Chapter

• Use make dev for hot reload during development
• The desktop app shares the same codebase as the web version
• BrowserRouter works seamlessly with Wails
• GraphQL API calls work identically to the web version
• All database plugins work without modification

Troubleshooting Copy Chapter

Module Not Found Errors Copy Section

# For CE
cd desktop-ce
GOWORK=$PWD/../go.work.desktop-ce go mod tidy

# For EE
cd ee/desktop && go mod tidy

Platform-Specific Issues Copy Section

Run wails doctor to check dependencies and ensure platform tools are installed.

Useful Commands Copy Chapter

make clean          # Remove all build artifacts
make doctor         # Check Wails dependencies
make install-wails  # Install/update Wails CLI
make help           # Show all available commands

Versioning Copy Chapter

Set version for builds and packages:

make build-mac VERSION=1.2.3
make package-mac VERSION=1.2.3

If VERSION is not specified, a timestamp is used.

Code Signing Options Copy Chapter

Using Sigstore (Recommended for Open Source) Copy Section

# Install cosign
go install github.com/sigstore/cosign/v2/cmd/cosign@latest

# Sign binary
cosign sign-blob build/bin/whodb-ce-windows-amd64.exe \
  --output-signature whodb-ce-windows-amd64.exe.sig \
  --output-certificate whodb-ce-windows-amd64.exe.crt

Platform-Specific Signing Copy Section

See the macOS packaging section above for Apple Developer ID signing, or use Windows EV certificates with Wails build flags.

Notes Copy Chapter

• The Makefile system automatically handles frontend building and asset preparation
• Both editions share common code via the desktop-common module
• The -obfuscated flag is currently disabled due to hanging issues
• Linux builds use webkit2_41 tag for better compatibility

Overview (`sdk/README.md`) Copy Section

WhoDB Platform SDKs

Customer-facing SDKs for the WhoDB hosted platform: ontology, datasets,
sources, transforms, functions, versioning and promotion, service accounts,
lineage providers, and ontology sharing as in-code function APIs. All five languages expose the same
domains and methods; the shared fixtures in spec/fixtures/ keep them
behaviorally identical.

Design: SDK_DESIGN.md in the EE repository. Architecture in one line:
a generated wire core (rendered from the committed spec snapshot in
spec/) under a handwritten facade per language, kept behaviorally
identical across languages by shared conformance fixtures.

Layout Copy Chapter

spec/                    # committed sync boundary with the platform backend
  platform-schema.graphql   # merged SDL (generated — ee/dev/export-sdk-spec.sh)
  platform-manifest.json    # curated public operation list (generated)
  surface.yaml              # hand-curated operation → facade mapping
  fixtures/                 # cross-language behavior fixtures
tools/
  generate-core.mjs      # spec → per-language wire cores (--check = drift gate)
  render/                # per-language renderers
  conformance-runner.mjs # runs fixtures against a language (--lang ts|python|go|rust|java)
  sync-versions.mjs      # lockstep version stamping (--set X.Y.Z / --check)
  smoke.mjs              # pre-release staging round-trip (real API key)
packages/                # the SDKs

Workflows Copy Chapter

Backend API changed? (schema or platform manifest)

bash ee/dev/export-sdk-spec.sh        # re-export the spec snapshot
node sdk/tools/generate-core.mjs      # regenerate wire cores
# commit both — EE and CE CI both gate on drift

Verify everything:

cd sdk
pnpm install
pnpm run check                        # generate --check + version lockstep
pnpm -r --if-present run build
pnpm -r test
node tools/conformance-runner.mjs --lang ts       # also: python, go, rust, java

Releases ride release-ce.yml (the deploy-sdk toggle) and share the repo
release version across all five targets: npm (_deploy-sdk-npm.yml) plus the
inlined deploy-sdk-pypi, deploy-sdk-cargo, and deploy-sdk-maven jobs
(inlined because PyPI attestations and crates.io trusted publishing validate
the top-level workflow), and deploy-sdk-go-tag, which tags
sdk/packages/go/v<version> only after all four registry publishes succeed.

Adding a language: docs/porting.md. Adding a domain: extend
spec/surface.yaml, add fixtures, then add the facade to every language and
its conformance runner in the same change.

Overview (`.agents/hooks/README.md`) Copy Section

Agent Hooks

Hooks run after tool actions (edit, write, apply_patch) and help keep code
consistent. They receive a JSON payload on stdin containing the tool input.

Hook Scripts Copy Chapter

Translation is intentionally not an automatic hook. Agents should add or update
en_US strings only; run dev/translate tooling manually when translations are
needed.

Supporting Files Copy Chapter

• changed-files.py — parses the JSON payload to extract file paths from edit/write/apply_patch hooks

Platform Compatibility Copy Chapter

These hooks use the Codex/Claude Code hook format (JSON on stdin). Pi uses an
extension-based hook system instead — wrap these scripts in a Pi extension for
equivalent functionality.

Adding a New Hook Copy Chapter

1. Write the script in this directory (root .agents/hooks/).
2. Add a forwarding shim at ee/.agents/hooks/<script-name> so the hook still
   resolves when the agent's cwd is inside the ee/ submodule (its own git
   repo, so git rev-parse --show-toplevel resolves to ee/ rather than the
   monorepo root). Match the existing shim pattern exactly:
   bash Copy

   #!/usr/bin/env bash
   exec "$(cd "$(dirname "$0")/../../.." && pwd)/.agents/hooks/<script-name>" "$@"

   Then chmod +x it.
3. Register the command in both .claude/settings.json and .codex/hooks.json
   using bash "$(git rev-parse --show-toplevel)/.agents/hooks/<script-name>"
   under the appropriate event (SessionStart, PostToolUse, Stop, etc.).
   Both files must be updated — neither tool reads the other's config.
4. Update the table above with the script's trigger and behavior.

Overview (`cli/external-plugin/whodb/README.md`) Copy Section

WhoDB Plugin for Claude Code

WhoDB platform and database-only MCP tools for Claude Code. Work across platform hosts and projects, or query databases directly.

Installation Methods Copy Chapter

This plugin supports multiple installation methods. Choose the one that works best for you:

Method 1: npm (Recommended - No pre-install needed) Copy Section

Run whodb setup to enable platform tools, database-only tools, or both. Keep one MCP entry at whodb mcp serve; agents can guide setup with whodb setup inspect, validate, apply, and verify. Sign in to platform hosts through whodb login --host and target workspaces per call. Docker examples below use an explicit database-only override; saved setup applies to the configuration directory of the running CLI.

The default configuration uses npx to auto-download and run the MCP server:

{
  "whodb": {
    "command": "npx",
    "args": ["-y", "whodb", "mcp", "serve"]
  }
}

Method 2: Docker (Database-only MCP) Copy Section

For database-only MCP access through Docker, update your Claude settings (.claude/settings.local.json):

{
  "mcpServers": {
    "whodb": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "host", "clidey/whodb-cli", "mcp", "serve", "--database"]
    }
  }
}

Method 3: Local Binary (Best performance) Copy Section

Install the CLI once, then it runs instantly:

1. Download from GitHub Releases
2. Add to your PATH
3. Update Claude settings:

{
  "mcpServers": {
    "whodb": {
      "command": "whodb",
      "args": ["mcp", "serve"]
    }
  }
}

Method 4: Homebrew (macOS/Linux) Copy Section

brew install whodb-cli

The formula is named whodb-cli (the whodb name is used by the desktop app cask), but it installs the whodb command.

Method 5: Go Install (Requires Go) Copy Section

go install github.com/clidey/whodb/cli@latest

Supported Databases Copy Chapter

• PostgreSQL
• MySQL / MariaDB
• SQLite
• MongoDB
• Redis
• ClickHouse
• Elasticsearch
• And more via WhoDB plugins

Manual CLI installation Copy Chapter

For the local binary method, install the CLI using one of these options:

Option 1: Download Binary Copy Section

Download the latest release from GitHub Releases and add it to your PATH.

Option 2: Build from Source Copy Section

git clone https://github.com/clidey/whodb.git
cd whodb/cli
go build -o whodb .
sudo mv whodb /usr/local/bin/

Option 3: Docker Copy Section

If you prefer Docker, update your Claude Code settings to use:

{
  "whodb": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "--network", "host", "clidey/whodb-cli", "mcp", "serve", "--database"]
  }
}

Configuration Copy Chapter

Database-only MCP connections Copy Section

These connection settings apply to whodb mcp serve --database. Platform mode
uses the sources configured in the selected platform workspace.

Configure database connections using environment variables:

# Environment profiles (examples below)
export WHODB_POSTGRES='[{"alias":"prod","host":"localhost","user":"user","password":"pass","database":"mydb","port":"5432"}]'
export WHODB_MYSQL_1='{"alias":"dev","host":"localhost","user":"user","password":"pass","database":"devdb","port":"3306"}'

Or use the CLI to save connections:

whodb connect --type postgres --host localhost --port 5432 --user myuser --database mydb --name prod

MCP Tools Copy Chapter

This plugin provides the following tools:

Security Modes Copy Chapter

By default, write operations require confirmation before executing (confirm-writes mode).

Additional options:

Skills Copy Chapter

whodb Copy Section

Main database skill - activates for any database-related task.

query-builder Copy Section

Natural language to SQL conversion. Activates when you ask questions like:

• "Show me users who signed up last week"
• "Find orders over $100"
• "Get the top 10 customers"

schema-designer Copy Section

Database schema design assistance. Activates when you ask to:

• Create tables
• Design schemas
• Model data relationships

Agents Copy Chapter

database-analyst Copy Section

Deep database analysis expert. Use for:

• Schema analysis and documentation
• Data quality assessment
• Multi-step data exploration

Invoke: "Use the database-analyst agent to analyze my schema"

query-optimizer Copy Section

Query performance specialist. Use for:

• Slow query analysis
• Index recommendations
• Query rewriting

Invoke: "Use the query-optimizer agent to optimize this query"

report-generator Copy Section

Data reporting specialist. Use for:

• Formatted reports from queries
• Data summaries and trends
• Export preparation

Invoke: "Use the report-generator agent to create a sales report"

Examples Copy Chapter

# Explore a database
Show me the tables in my prod database

# Query data
Find all users created in the last 7 days

# Analyze performance
Use the query-optimizer agent to analyze: SELECT * FROM orders WHERE status = 'pending'

# Design schema
Help me design a schema for a blog with posts, comments, and tags

Links Copy Chapter

• WhoDB Repository
• WhoDB Documentation
• CLI Documentation

License Copy Chapter

Apache License 2.0

MCP without skills Copy Section

Skills are optional supplements. MCP initialization instructions, tool schemas,
and whodb://mcp/configuration provide essential guidance directly. Use
whodb_mcp_setup actions inspect, preview (with a settings patch), apply
(with the exact approved preview token and approved: true), and verify.
No shell access is required for these actions. Browser login and credential entry
remain user actions. Restart after changing settings; verification checks the
active process. The setup tool follows tool filters and can be disabled when
configuration should remain outside the agent.

Overview (`sdk/packages/go/README.md`) Copy Section

whodb (Go SDK)

Official Go SDK for the WhoDB hosted platform — your
ontology, datasets, sources, transforms, functions, and org administration as
in-code function APIs.

Install Copy Chapter

go get github.com/clidey/whodb/sdk/packages/go

Requires Go ≥ 1.27.3.

Quickstart Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Authentication Copy Chapter

Credential precedence: Config fields (APIKey / Token / TokenFunc /
Credentials) → WHODB_API_KEY env var → the whodb CLI's stored login.
Workspace (Org / Project) is optional with an API key; set Project
when the key has access to more than one project.

Inside a WhoDB Function, whodb.New(whodb.Config{}) auto-detects the runtime
and needs no configuration at all.

Errors Copy Chapter

Sentinel errors for errors.Is: ErrAuth, ErrNotFound, ErrValidation,
ErrVersion (SDK outdated for the platform API — upgrade the module),
ErrCliCredentials, ErrTransportCapability; plus *PlatformError (via
errors.As) carrying the platform's error code.

License Copy Chapter

Apache-2.0

Overview (`sdk/packages/java/README.md`) Copy Section

whodb-sdk (Java)

Official Java SDK for the WhoDB hosted platform — your
ontology, datasets, sources, transforms, functions, and org administration as
in-code function APIs.

Install Copy Chapter

<dependency>
  <groupId>com.clidey</groupId>
  <artifactId>whodb-sdk</artifactId>
  <version>LATEST</version>
</dependency>

Requires Java ≥ 17. One dependency (jackson-databind); HTTP via the JDK's
built-in java.net.http.HttpClient.

Quickstart Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Rows are Map<String, Object> with native-typed values; timestamps hydrate
to java.time.OffsetDateTime.

Authentication Copy Chapter

Credential precedence: Config fields (apiKey / token / credentials)
→ WHODB_API_KEY env var → the whodb CLI's stored login. Workspace
(org / project) is optional with an API key; set project when the key
has access to more than one project.

Inside a WhoDB Function, new WhoDB() auto-detects the runtime and switches
to the in-container IPC transport (unix socket in Docker, TCP in K8s).

Errors Copy Chapter

All failures throw WhoDBException; kind() identifies the class: AUTH,
NOT_FOUND, VALIDATION, VERSION (SDK outdated for the platform API —
upgrade the artifact), CLI_CREDENTIALS, TRANSPORT_CAPABILITY, PLATFORM
(with code()), TRANSPORT.

License Copy Chapter

Apache-2.0

Overview (`sdk/packages/python/README.md`) Copy Section

whodb-sdk

Official Python SDK for the WhoDB hosted platform — your
ontology, datasets, sources, transforms, functions, and org administration as
in-code function APIs.

Install Copy Chapter

pip install whodb-sdk

Requires Python ≥ 3.10.

Quickstart Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Authentication Copy Chapter

Credential precedence: constructor args (api_key= / token= /
credentials=) → WHODB_API_KEY env var → the whodb CLI's stored login.
Workspace (org= / project=) is optional with an API key; pass project=
when the key has access to more than one project.

Inside a WhoDB Function, WhoDB() auto-detects the runtime and needs no
configuration at all.

Typed clients Copy Chapter

whodb sdk generate --language python --out whodb_gen/

License Copy Chapter

Apache-2.0

Overview (`sdk/packages/rust/README.md`) Copy Section

whodb-sdk (Rust)

Official Rust SDK for the WhoDB hosted platform — your
ontology, datasets, sources, transforms, functions, and org administration as
in-code function APIs.

Install Copy Chapter

cargo add whodb-sdk

Requires Rust ≥ 1.75. Synchronous API; two dependencies (serde_json, ureq).

Quickstart Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Rows are serde_json::Map<String, Value> with native-typed values. Hydrated
timestamps carry an @date:<RFC3339> string marker (Rust has no std datetime
type) — parse with your preferred time crate.

Authentication Copy Chapter

Credential precedence: Config fields (api_key / token / credentials)
→ WHODB_API_KEY env var → the whodb CLI's stored login. Workspace
(org / project) is optional with an API key; set project when the key
has access to more than one project.

Inside a WhoDB Function (K8s/TCP runtime), Client::new(Config::default())
auto-detects the runtime. The Docker runtime's unix-socket IPC is not yet
supported by this crate.

Errors Copy Chapter

whodb_sdk::Error variants: Auth, NotFound, Validation, Version
(SDK outdated for the platform API — upgrade the crate), CliCredentials,
TransportCapability, Platform { message, code }, Transport.

License Copy Chapter

Apache-2.0

Overview (`sdk/packages/typescript/README.md`) Copy Section

@clidey/whodb-sdk

Official TypeScript/JavaScript SDK for the WhoDB hosted
platform — your ontology, datasets, sources, transforms, functions, and
org administration as in-code function APIs.

Install Copy Chapter

npm install @clidey/whodb-sdk

Requires Node.js ≥ 20.

Quickstart Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Authentication Copy Chapter

Credential precedence:

1. new WhoDB({ apiKey }) / { token } / { credentials } constructor options
2. WHODB_API_KEY environment variable
3. The whodb CLI's stored login (whodb login), gcloud-ADC-style — ideal
   for local development

Workspace (org / project) is optional with an API key; pass { project }
or set WHODB_PROJECT when the key has access to more than one project.

Typed clients Copy Chapter

Generate typed entity classes from your project's ontology:

whodb sdk generate --language ts --out src/whodb-gen/

import { createClient } from './whodb-gen/whodb.generated.js';

const { ontology } = createClient({ apiKey: process.env.WHODB_API_KEY });
const user = await ontology.User.get('u_123'); // fully typed

Versioning Copy Chapter

Each SDK release is generated against one WhoDB platform release. Deprecated
operations warn once per process with their removal date; operations removed
from the platform raise WhoDBVersionError — upgrade the package to resolve.

License Copy Chapter

Apache-2.0

Overview (`cli/npm-package/packages/whodb-cli/README.md`) Copy Section

@clidey/whodb-cli

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

Installing this package provides the whodb command. If you'd rather use a
namespaced package name, install @clidey/whodb
instead — both provide the same command.

Installation Copy Chapter

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

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

Both install methods provide the whodb command.

Features Copy Chapter

• 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 Copy Chapter

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

Usage Copy Chapter

Interactive Mode (TUI) Copy Section

npx @clidey/whodb --tui

Programmatic Commands Copy Section

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

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

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

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

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

MCP Server Mode Copy Section

Platform MCP is the default. Sign in to each host, then start the server:

npx @clidey/whodb login --host <url>
npx @clidey/whodb mcp serve

Use workspace: {host, org, project} on platform tool calls to target a specific
workspace without changing saved defaults.

For database-only tools, enable the database module using npx @clidey/whodb setup. The server command stays the same:

npx @clidey/whodb 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 mcp serve --database --allowed-connections prod,staging

Database-only MCP Client Configuration Copy Chapter

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

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

Assistant Integration Installer Copy Chapter

Install native assistant configuration with the bundled CLI:

npx @clidey/whodb skills install --target cursor
npx @clidey/whodb skills install --target vscode
npx @clidey/whodb skills install --target gemini-cli
npx @clidey/whodb skills install --target claude-code --include-agents
npx @clidey/whodb 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 Copy Chapter

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.

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 Copy Chapter

Platform Support Copy Chapter

This package automatically installs the correct binary for your platform:

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

Links Copy Chapter

• GitHub Repository
• Documentation

License Copy Chapter

Apache-2.0

Overview (`cli/npm-package/packages/whodb/README.md`) Copy Section

whodb

The WhoDB CLI — an interactive, production-ready command-line
interface for navigating SQL and NoSQL databases, with a TUI, programmatic
commands, and an MCP server for AI assistants.

Use `@clidey/whodb` instead Copy Chapter

This unscoped package is a thin wrapper kept published so the name isn't
squatted by someone else. The primary, namespaced package is
@clidey/whodb:

npm install @clidey/whodb
whodb --help

Installing this package also works and provides the same whodb command —
it depends on and forwards to
@clidey/whodb-cli, same
as @clidey/whodb does. Prefer the scoped name in new setups.

Documentation Copy Chapter

Full CLI documentation, command reference, and MCP setup:
https://github.com/clidey/whodb/tree/main/cli#readme

Overview (`cli/npm-package/packages/@clidey/whodb/README.md`) Copy Section

@clidey/whodb

The WhoDB CLI — an interactive, production-ready command-line
interface for navigating SQL and NoSQL databases, with a TUI, programmatic
commands, and an MCP server for AI assistants.

This is the primary namespaced package for installing WhoDB's CLI:

npm install @clidey/whodb
whodb --help

What this package is Copy Chapter

This is a thin wrapper: all the real work — the launcher, the platform-specific
binaries, and the BAML runtime — lives in
@clidey/whodb-cli, which
this package depends on and forwards to. Installing this package gives you
the whodb command.

Renamed from whodb-cli: the command used to be whodb-cli. If you're
upgrading, @clidey/whodb-cli still ships a deprecated whodb-cli binary
that prints a warning and forwards to whodb — update scripts and configs
to use whodb going forward.

Features Copy Chapter

• Interactive TUI — terminal UI with split-pane layouts, themes, and an
  SQL editor with schema-aware autocomplete
• Multi-database support — PostgreSQL, MySQL/MariaDB, SQLite, MongoDB,
  Redis, ClickHouse, Elasticsearch
• Programmatic mode — JSON/NDJSON/CSV/plain output for scripting and CI
• Import/export — CSV and Excel, plus FK-aware mock data generation
• Schema tools — ERD graph output, EXPLAIN plans, schema diff between
  connections
• MCP server — expose database access to AI assistants (Claude, Cursor,
  and others) with read-only and confirm-writes safety modes
• Assistant integration installer — bundled skills, agents, and MCP
  configs for popular coding assistants

Usage Copy Chapter

# Interactive TUI
whodb --tui

# Run a query
whodb query "SELECT * FROM users LIMIT 10" --connection mydb

# Configure platform, database-only, or both modules once
npx @clidey/whodb setup

# Start the single MCP server
whodb mcp serve

Or without installing:

npx @clidey/whodb

Documentation Copy Chapter

Full CLI documentation, command reference, and MCP setup:
https://github.com/clidey/whodb/tree/main/cli#readme

Query Scratchpad Intro (`docs/query/scratchpad-intro.mdx`) Copy Section

title: "Scratchpad Introduction" Copy Chapter

Scratchpad Introduction

Scratchpad is WhoDB's query workspace for connections that support raw queries — SQL databases, plus shell-style commands for MongoDB and commands for Redis. It gives you page-based query organization, one or more query cells per page, query execution, result grids, action-query confirmations, and per-cell query history.

Open Scratchpad Copy Chapter

Open Scratchpad from the left sidebar. The route is /scratchpad.

The current layout is vertical:

• The SQL editor is at the top of each cell.
• Query results or action status render below the editor.
• Multiple cells stack vertically within the active page.
• Scratchpad pages appear as tabs above the cells.

Run Queries Copy Chapter

Type SQL into the editor and run it with any of:

• The run button at the bottom-right of the cell. It appears on hover (or when the page has a single cell) and is hidden while the editor is empty.
• The per-statement play buttons in the editor's left gutter, which run one statement at a time.
• Cmd/Ctrl + Enter.

SELECT queries show a results grid below the editor. Action queries such as INSERT, UPDATE, and DELETE show an action result after confirmation.

Errors Copy Chapter

Database errors are shown below the editor for the cell that failed.

Start with a small query such as SELECT 1;, then add complexity back until the error is isolated.

Pages And Cells Copy Chapter

Scratchpad has two levels of organization:

• Pages are tabs across the top. Use the plus tab to add a page. Double-click a page name to rename it. Use the close button on a page tab to delete it.
• Cells are query editors inside a page. Hover over a cell to reveal the add, clear, delete, and run controls.

The cell options menu currently contains Clear, Copy Code, and Query History.

Use the visible page tabs and cell controls to organize Scratchpad work.

Query History Copy Chapter

Open query history from the cell options menu or the history button on the cell.

History is stored per cell. Entries show the query text, success/error status, and timestamp. From a history entry you can copy the SQL, load it back into the current editor, or run it again.

Editor Shortcuts Copy Chapter

Related Pages Copy Chapter

Resources Comparisons Overview (`docs/resources/comparisons/overview.mdx`) Copy Section

title: "Database Tool Comparison Overview" Copy Chapter

Database Tool Comparison Overview

Choosing the right database management tool can significantly impact your productivity, workflow efficiency, and team collaboration. This comprehensive comparison guide helps you understand how WhoDB stacks up against popular alternatives and make an informed decision.

Quick Comparison Table Copy Chapter

Detailed Feature Comparison Copy Chapter

Performance and Resource Usage Copy Section

**phpMyAdmin**
- Completely free
- Open source
- Self-hosted
- Community support

**pgAdmin**
- Completely free
- Open source
- Community support

**TablePlus**
- Commercial desktop app
- Free trial available
- Native desktop experience

services:
  whodb:
    image: clidey/whodb:latest
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - WHODB_LOG_LEVEL=info
      # Keeps encrypted login sessions valid across container recreation.
      # Generate once with: openssl rand -hex 32
      - WHODB_ENCRYPTION_KEY=replace_with_openssl_rand_hex_32
    restart: unless-stopped
    volumes:
      - whodb-data:/data

volumes:
  whodb-data:

chmod +x whodb
./whodb

cd core
go run ./cmd/whodb

cd frontend
pnpm start

export WHODB_POSTGRES_1='{"alias":"prod","host":"db.example.com","user":"postgres","password":"secret","database":"app","port":"5432"}'
export WHODB_POSTGRES_2='{"alias":"staging","host":"staging.example.com","user":"postgres","password":"secret","database":"app","port":"5432"}'

export WHODB_POSTGRES_1='{
  "alias": "prod",
  "host": "db.example.com",
  "user": "postgres",
  "password": "secret",
  "database": "app",
  "port": "5432",
  "advanced": {
    "SSL Mode": "verify-ca",
    "SSL CA Path": "/etc/certs/ca.pem",
    "SSL Client Cert Path": "/etc/certs/client.pem",
    "SSL Client Key Path": "/etc/certs/client-key.pem"
  }
}'

PORT=3000 ./whodb

docker run -d \
  -p 3000:8080 \
  clidey/whodb:latest

docker run -d \
  -e PORT=3000 \
  -p 3000:3000 \
  clidey/whodb:latest

docker run -d --name whodb-readguard-pg -p 127.0.0.1:55439:5432 -e POSTGRES_USER=guard -e POSTGRES_PASSWORD=guard-local -e POSTGRES_DB=guard postgres:18
docker run -d --name whodb-readguard-mysql -p 127.0.0.1:53319:3306 -e MYSQL_ROOT_PASSWORD=guard-local -e MYSQL_DATABASE=guard mysql:8.4 --secure-file-priv=/tmp
docker run -d --name whodb-readguard-maria -p 127.0.0.1:53329:3306 -e MARIADB_ROOT_PASSWORD=guard-local -e MARIADB_DATABASE=guard mariadb:latest --secure-file-priv=/tmp
docker run -d --name whodb-readguard-clickhouse -p 127.0.0.1:59009:9000 -e CLICKHOUSE_USER=guard -e CLICKHOUSE_PASSWORD=guard-local -e CLICKHOUSE_DB=guard -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 clickhouse/clickhouse-server:25.5

# From core/
go test ./src/sqlguard ./src/plugins/... ./src/source/adapters ./src/bamlconfig ./graph
WHODB_READGUARD_LOCAL=1 go test -tags integration ./src/plugins/clickhouse -run '^TestClickHouseProtectedExecution$' -count=1
go test ./src/sqlguard -run '^$' -fuzz '^FuzzProtectedRead$' -fuzztime=15s -parallel=2

# From cli/
go test ./pkg/mcp ./internal/database
go build -o /tmp/whodb-readguard-cli .
WHODB_READGUARD_LOCAL=1 WHODB_READGUARD_BINARY=/tmp/whodb-readguard-cli go test -tags integration ./pkg/mcp -run '^TestReadGuardTransport$' -count=1

docker stop whodb-readguard-pg whodb-readguard-mysql whodb-readguard-maria whodb-readguard-clickhouse
docker rm -v whodb-readguard-pg whodb-readguard-mysql whodb-readguard-maria whodb-readguard-clickhouse
rm /tmp/whodb-readguard-cli

# From core/
go test ./src/plugins/duckdb ./src/sourcecatalog ./src/source/adapters

# From cli/
go test -tags integration ./pkg/mcp -run '^TestDuckDBReadGuardTransport$' -count=1
go build -o /tmp/whodb-duckdb-cli .
WHODB_READGUARD_BINARY=/tmp/whodb-duckdb-cli go test -tags integration ./pkg/mcp -run '^TestDuckDBReadGuardTransport$' -count=1
rm /tmp/whodb-duckdb-cli

# From the repository root; the runner creates local test fixtures and services.
VITE_E2E_TEST=true bash dev/run-e2e.sh true duckdb protected-chat.ce

# Full DuckDB browser regression suite:
VITE_E2E_TEST=true bash dev/run-e2e.sh true duckdb

┌─────────────────────────────────────────────────────────────────┐
│                        Connection Sources                        │
├─────────────────────────────────────────────────────────────────┤
│  Manual Entry (current)     │     AWS Provider (new)            │
│  - User enters hostname     │     - Auto-discovers resources    │
│  - User enters credentials  │     - Builds credentials for:     │
│                             │       • RDS → MySQL/Postgres/MariaDB│
│                             │       • ElastiCache → Redis        │
│                             │       • DocumentDB → MongoDB       │
│                             │       • Extensions → source types  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Existing Database Plugins                    │
│  MySQL │ PostgreSQL │ MariaDB │ Redis │ MongoDB │ ...           │
│  (unchanged - they receive standard engine.Credentials)         │
└─────────────────────────────────────────────────────────────────┘

core/src/
├── aws/                      # AWS infrastructure layer
│   ├── config.go            # AWS SDK configuration
│   ├── credentials.go       # Credential parsing and provider building
│   ├── errors.go            # AWS error handling
│   ├── profiles.go          # Local AWS profile discovery
│   ├── regions.go           # AWS region definitions
│   └── *_test.go            # Tests
│
└── providers/               # Connection provider abstraction
    ├── provider.go         # ConnectionProvider interface
    ├── registry.go         # Provider registry
    └── aws/               # AWS provider implementation
        ├── provider.go    # Main AWS provider
        ├── rds.go        # RDS instance discovery
        ├── elasticache.go # ElastiCache cluster discovery
        ├── documentdb.go  # DocumentDB cluster discovery
        └── *_test.go      # Tests

type ConnectionProvider interface {
    Type() ProviderType
    ID() string
    Name() string
    DiscoverConnections(ctx context.Context) ([]DiscoveredConnection, error)
    TestConnection(ctx context.Context) error
    RefreshConnection(ctx context.Context, connectionID string) (bool, error)
    Close(ctx context.Context) error
}

type DiscoveredConnection struct {
    ID           string                // "providerID/resourceID"
    ProviderType ProviderType          // "aws", "manual"
    ProviderID   string                // Provider instance ID
    Name         string                // Display name
    DatabaseType engine.DatabaseType   // MySQL, Postgres, Redis, etc.
    Region       string                // Geographic location
    Status       ConnectionStatus      // available, starting, stopped, etc.
    Metadata     map[string]string     // Provider-specific details
}

config := &aws.Config{
    ID:                  "aws-us-west-2",
    Name:                "Production AWS",
    Region:              "us-west-2",
    AuthMethod:          awsinfra.AuthMethodDefault, // or profile
    DiscoverRDS:         true,
    DiscoverElastiCache: true,
    DiscoverDocumentDB:  true,
    DiscoverS3:          true, // used when an S3 discovery extension is registered
}

provider, err := aws.New(config)

// Create provider
provider, _ := aws.New(&aws.Config{
    ID:     "aws-prod",
    Name:   "Production",
    Region: "us-west-2",
})

// Register with the global registry
registry := providers.GetDefaultRegistry()
registry.Register(provider)

// Discover all connections
ctx := context.Background()
connections, _ := registry.DiscoverAll(ctx)

// Connection metadata (endpoint, port, TLS) is exposed to frontend.
// Users select a connection in the UI, which prefills the login form.
// Users can then modify values (e.g., hostname to localhost for tunneling)
// before submitting via the standard LoginSource mutation.

// The source login resolver maps source types to connectors/plugins:
//   - ElastiCache → Redis plugin
//   - DocumentDB → MongoDB plugin
//   - S3 extension → S3 source connector

var (
    ErrAccessDenied       // IAM permission issues
    ErrInvalidCredentials // Bad access key/secret
    ErrExpiredCredentials // Session token expired
    ErrResourceNotFound   // Resource doesn't exist
    ErrThrottling         // Rate limited
    ErrServiceUnavailable // AWS service issues
    ErrConnectionFailed   // Network issues
)

// Usage
if aws.IsRetryable(err) {
    // Safe to retry
}

# Run AWS infrastructure tests
go test ./src/aws/...

# Run provider tests
go test ./src/providers/...

# Single provider with default auth
WHODB_AWS_PROVIDER='[{
  "name": "Production",
  "region": "us-west-2"
}]'

# Multiple regions with a named profile
WHODB_AWS_PROVIDER='[
  {"name": "US", "region": "us-west-2"},
  {"name": "EU", "region": "eu-west-1", "profileName": "eu-account"}
]'

cd core && go run ./cmd/whodb