agent-database-cli

Local multi-database CLI for agents. One command opens a connection, runs, disconnects. Supports MySQL · PostgreSQL · Redis · Oracle · MongoDB, with read-only mode and a command blocklist. Built in Rust, shipped via npm.

Install

npm install -g @mejazbese21/agent-database-cli
agent-database-cli --help     # also available as: db-cli

Requires Node >= 20. On install, the matching native binary (macOS x64/arm64, Linux x64/arm64, Windows x64) is downloaded from GitHub Releases into the package.

Prefer no npm? Download the binary for your OS straight from the Releases page, put it on your PATH, and run it — it's self-contained.

Update / uninstall:

npm install -g @mejazbese21/agent-database-cli@latest
npm uninstall -g @mejazbese21/agent-database-cli && rm -rf ~/.agent-database-cli

Usage

agent-database-cli list                                  # types + configured connections
agent-database-cli test --db local-mysql                 # test a connection
agent-database-cli exec --db local-mysql --command "select 1"          # runs + opens an HTML review page
agent-database-cli meta --db local-mysql --type tables   # tables/columns/collections/keys
agent-database-cli --format table exec --db local-mysql --command "select 1"
agent-database-cli exec --db local-mysql --command "select * from accounts limit 200" --no-review  # skip the HTML page

exec and meta render the result to an interactive HTML page by default — click-to-sort, show/hide/freeze/reorder columns, expandable cells, per-table view preferences — and open it in your default browser; stdout is unchanged. Pass --no-review to skip it (scripts, pipelines, CI, agents). Pages land in ~/.agent-database-cli/exports/query-results/ (dated, never overwritten) and reference shared assets in exports/assets/, written from the binary so everything works offline. Because every run persists result data as plaintext HTML on disk, treat exports/ like query logs: pass --no-review for sensitive data and clean it out periodically.

For many queries in a row, reuse one connection:

printf 'select 1\nselect count(*) from accounts\n' | agent-database-cli repl --db local-mysql

MCP server (agent-database-cli-mcp) — for agents. Stateless tools (query / describe / list_databases / help); each call names its database and the first query per database opens a connection that stays warm for the rest of the session:

claude mcp add agent-db -- agent-database-cli-mcp

CLI reference

Global options

Passed before the subcommand (e.g. agent-database-cli --format table list).

| Option | Possible values | Default | Description | | --- | --- | --- | --- | | --format <fmt> | compact · json · pretty · table | compact for exec/meta · pretty for list · json for test/install-skill | Output format. compact: single-line JSON, columns listed once in fields + positional rows (most token-efficient). json: minified keyed JSON. pretty: indented keyed JSON, for humans. table: padded text table. | | -h, --help | — | — | Print help (global, or for a subcommand). | | -V, --version | — | — | Print the version and exit. |

Commands & options

| Command | Option | Possible values | Default | Required | Description | | --- | --- | --- | --- | --- | --- | | list | — | — | — | — | Print supported DB types + configured connections. | | test | --db <name> | a configured connection | — | yes | Connection to test. | | exec | --db <name> | a configured connection | — | yes | Target connection. | | | --command <str> | SQL · Redis command · Mongo JSON | — | yes | Statement to run. | | | --review | flag | true (on) | no | Render the result to an HTML page + open the browser. On by default. | | | --no-review | flag | — | no | Skip the HTML review page for this run. | | repl | --db <name> | a configured connection | — | yes | Reuse one connection; reads stdin, one statement per line. | | meta | --db <name> | a configured connection | — | yes | Target connection. | | | --type <t> | tables · columns · collections · keys | — | yes | What to inspect. | | | --table <name> | a table name | — | only if --type columns | Table whose columns to list. | | | --pattern <p> | Redis match pattern | all keys | no | Filter for --type keys (Redis SCAN). | | | --review | flag | true (on) | no | Render the result to an HTML page + open the browser. On by default. | | | --no-review | flag | — | no | Skip the HTML review page for this run. | | install-skill | --dry-run | flag | false | no | Show the install plan; write nothing. | | | --yes | flag | false | no | Skip the confirmation prompt and install directly. |

flag options take no value — present means on, absent means the default.

Environment variables

| Variable | Default | Description | | --- | --- | --- | | AGENT_DATABASE_CLI_CONFIG | ~/.agent-database-cli/config.json | Path to the config file. |

Configuration

File: ~/.agent-database-cli/config.json (override with AGENT_DATABASE_CLI_CONFIG).

{
  "databases": {
    "local-mysql": {
      "type": "mysql",
      "url": "mysql://user:password@localhost:3306/app",
      "readonly": true,
      "blacklist": ["drop", "truncate", "delete"]
    },
    "remote-mysql": {
      "type": "mysql",
      "url": "mysql://user:[email protected]:3306/app",
      "sshTunnel": { "host": "jump.example.com", "username": "deploy", "privateKeyPath": "~/.ssh/id_rsa" },
      "readonly": true
    }
  }
}

Per-connection fields:

• type — mysql | postgres | redis | oracle | mongodb
• url — connection string. Postgres TLS via ?sslmode= (prefer default, require, verify-full, disable). For managed DBs with a private CA (e.g. RDS) use require.
• readonly — default true; only set false when writes are truly needed.
• blacklist — case-insensitive command blocklist, checked before read-only.
• sshTunnel — host, port (22), username, and password or privateKeyPath/privateKey (+ optional passphrase).
• redisCluster.nodes — array of cluster node URLs (cluster mode needs both url and nodes).
• Oracle: oracleDriver (sqlcl default | oracle | oracledb), sqlclPath, javaHome.

Passwords/passphrases are encrypted on first use (stored as *Ref in the config dir); plaintext is cleared automatically.

Permissions

Use readonly and blacklist together. Order: blacklist is checked first (reject on match), then read-only (reject writes). Read-only also blocks write-semantic reads like Postgres SELECT INTO and Mongo $out / $merge.

High-risk commands to blocklist:

• SQL: drop, truncate, delete, update, insert, merge, alter, create, grant, revoke
• Redis: flushall, flushdb, del, set, expire, rename, keys
• Mongo: insertMany, updateMany, deleteMany, drop, dropDatabase, $out, $merge

Oracle (SQLcl)

Oracle uses SQLcl by default (no Instant Client needed, works with old versions like Oracle 11). The connect script is passed via stdin so the password is never in process args; blocklist and read-only still apply.

License

MIT