shhac MongoDB exploration with agent-mongo
agent-mongo is a read-only CLI binary on $PATH. Default output is NDJSON — one JSON record per line on stdout. List commands emit one record per item, then @-prefixed metadata lines ({"@meta": ...} for context, {"@pagination": ...} for paging). Errors go to stderr as one JSON line {"error": "...", "fixable_by": "agent"|"human"|"retry", "hint": "..."} with a non-zero exit.
fixable_by tells you who resolves the error: agent — fix your input and retry; human — needs the user (auth, a GUI dialog); retry — transient, run it again.
Quick start (connections)
Set up a connection:
agent-mongo connection add local "mongodb://localhost:27017/myapp" --default
agent-mongo connection test
For authenticated connections, store credentials separately — prefer --form
(native OS dialog; the secret never enters agent context) over
--username/--password flags:
agent-mongo credential add acme --form
agent-mongo connection add prod "mongodb+srv://cluster.example.net/myapp" --credential acme --default
A user:pass embedded in the URI is automatically extracted into a stored
credential named after the connection alias (don't combine with
--credential — that's an error). If a credential with that alias already
exists holding different values, the add is refused; follow the error's hint
(rotate via credential add --form, or reference the existing credential
with --credential). connection list always redacts passwords in
connection strings.
Some deployments authenticate against an identity provider instead (MONGODB-OIDC) — see references/auth.md to set one up.
If any command fails with fixable_by: human naming credential login,
stop and ask the person to run it. No retry fixes it and no agent can
complete it: the login is deliberately human-only. This is the one auth
failure that is not a bug to work around.
Exploring a database
agent-mongo database list # all databases with sizes
agent-mongo collection list myapp # all collections in myapp
agent-mongo collection schema myapp users # infer schema from samples
agent-mongo collection schema myapp users --depth 2 # limit nesting depth
agent-mongo collection schema myapp events --limit 50 # paginate large schemas
agent-mongo collection schema myapp events --limit 50 --skip 50 # next page
agent-mongo collection indexes myapp users # index key patterns (verbatim specs)
agent-mongo collection stats myapp orders # document count, sizes
agent-mongo database stats myapp # database-level statistics
Querying documents
agent-mongo query find myapp users --filter '{"age":{"$gte":21}}' --limit 10
agent-mongo query find myapp orders --sort '{"createdAt":-1}' --projection '{"status":1,"total":1}'
agent-mongo query get myapp users 665a1b2c3d4e5f6a7b8c9d0e # by _id (auto-detects ObjectId)
agent-mongo query get myapp users 665a1b2c3d4e5f6a7b8c9d0e --projection '{"name":1,"email":1}'
agent-mongo query count myapp orders --filter '{"status":"pending"}'
agent-mongo query sample myapp users --size 10 # random documents
agent-mongo query sample myapp users --size 10 --filter '{"status":"active"}' # filtered sample
agent-mongo query distinct myapp orders status # unique values
query find emits one record per document, then a {"@pagination": {"has_more": ..., "total_items": ...}} line — has_more means more documents match beyond the limit, total_items is the full matching count.
All JSON arguments (--filter, --sort, --projection, --pipeline) accept MongoDB Extended JSON for BSON types:
agent-mongo query find myapp events --filter '{"createdAt":{"$gt":{"$date":"2026-01-01T00:00:00Z"}}}'
agent-mongo query find myapp users --filter '{"_id":{"$oid":"665a1b2c3d4e5f6a7b8c9d0e"}}'
Aggregation
agent-mongo query aggregate myapp orders '[{"$group":{"_id":"$status","count":{"$sum":1}}}]'
agent-mongo query aggregate myapp orders --pipeline '[{"$group":{"_id":"$status","count":{"$sum":1}}}]'
agent-mongo query aggregate myapp events '[{"$match":{"type":"purchase"}},{"$group":{"_id":"$userId","total":{"$sum":"$amount"}}}]'
Pipeline can be passed as a positional argument, via --pipeline flag, or piped via stdin.
Write stages ($out, $merge) are rejected — the CLI is strictly read-only.
Output format
Default is NDJSON (-f jsonl). Switch with -f/--format:
agent-mongo database list -f json # pretty {"data": [...], ...meta} envelope for lists
agent-mongo query count myapp users -f yaml
-f json gives a single pretty envelope ({"data": [...]} for lists, a bare pretty object for single results) — easier to eyeball than NDJSON when you're reading output yourself.
Connection management
agent-mongo connection list # saved connections + defaults
agent-mongo connection add staging "mongodb://..." --credential acme
agent-mongo connection update prod --credential new-cred
agent-mongo connection set-default staging
agent-mongo connection remove old-conn
agent-mongo connection test prod # verify connectivity (positional alias)
agent-mongo connection test -c prod # also works with -c flag
Connection resolution: -c flag > AGENT_MONGO_CONNECTION env > config default > error listing available connections.
Credential management
agent-mongo credential add acme --form # preferred interactive; see secure entry below
printf '%s' "$PW" | agent-mongo credential add acme --username deploy # non-interactive machine path
agent-mongo credential list # passwords always redacted
agent-mongo credential remove acme --force # even if connections reference it
Credentials are stored separately from connections, in the OS secret store when available (macOS Keychain, Linux Secret Service, Windows Credential Manager) with plaintext-config fallback. credential list shows the storage source per credential. Plaintext entries are auto-upgraded to the keychain on first use (reported via a stderr {"notice": ...} line — not an error). When you rotate a password, just re-add the credential — all connections referencing it pick up the new auth automatically.
Secure credential entry — never paste a secret into --password
If a user pastes a MongoDB password (or any secret) into chat, do not put it into --password. A literal secret on the command line would land in your context window, transcripts, shell history, ps//proc, and any downstream telemetry. Two safe paths supply the secret without ever putting it on argv:
1. --form — preferred interactive path. A native OS dialog (macOS osascript, Linux zenity/kdialog, Windows Win32) pops up and the user types the secret straight into the OS. The agent only sees a redacted JSON receipt. When the agent is driving the CLI on the user's machine, instruct the user to run the --form command themselves so the secret stays out of the LLM:
agent-mongo credential add acme --form # both fields prompted
agent-mongo credential add acme --username deploy --form # only password prompted
2. Piped stdin — non-interactive machine path. For scripts, CI, or a headless host where no GUI is available, pipe the password on stdin. It is read off the stream, never placed on the command line. --username is not a secret and stays a flag:
printf '%s' "$PW" | agent-mongo credential add acme --username deploy
Password resolution precedence: --password flag > piped stdin > --form dialog. Prefer --form or stdin; reserve --password for values that are already non-secret (test fixtures, throwaway local dbs) — never for a secret pasted into chat.
--form failure modes return a structured error with fixable_by:
human— no GUI session available (SSH, headless host). Ask the user to run on their local machine, or use the piped-stdin path above.retry— user cancelled the dialog. Re-running the same command is the right next step.
Truncation
Any string field exceeding truncation.maxLength (default 200) gets truncated with … and a companion {field}Length key showing original length.
agent-mongo --full query find myapp posts # expand all fields
agent-mongo --expand description query find myapp posts # expand specific field
These are global flags — place them before or after the command.
Timeout
Default timeout is 30s (configurable via query.timeout). Applies to both connection and query phases. Override per-command with -t/--timeout <ms>:
agent-mongo --timeout 60000 query find myapp large_collection --filter '{"status":"active"}'
agent-mongo --timeout 120000 collection schema myapp events
On timeout (MongoDB code 50), the error hint suggests increasing the timeout or checking indexes.
Configuration
agent-mongo config list-keys # all keys with defaults/ranges
agent-mongo config set defaults.limit 50
agent-mongo config get query.timeout
agent-mongo config reset # restore defaults
Key settings: defaults.limit (20), defaults.sampleSize (5), defaults.schemaSampleSize (100), query.timeout (30000ms), query.maxDocuments (100), truncation.maxLength (200).
MCP server
agent-mongo mcp runs the read-only data commands (database, collection, query, connection) as MCP tools over stdio (or Streamable HTTP with --http <addr>). Credential and config commands are not exposed. See agent-mongo mcp usage for registration, OAuth, and Tailscale details.
Safety
- Read-only: No write operations exist
- Aggregation:
$outand$mergestages rejected - Result cap:
query.maxDocuments(default 100) - Timeout: applies to both connections and queries (default 30s), override per-command with
-t/--timeout <ms>
Per-command usage docs
Every command group has a usage subcommand with detailed, LLM-optimized docs:
agent-mongo usage # top-level overview
agent-mongo connection usage # connection commands
agent-mongo credential usage # credential management
agent-mongo database usage # database commands
agent-mongo collection usage # collection commands
agent-mongo query usage # all query commands
agent-mongo config usage # settings keys, defaults, validation
agent-mongo mcp usage # MCP server transports and registration
Use agent-mongo <command> usage when you need deep detail on a specific domain before acting.
References
- references/auth.md: identity-provider (OIDC) credentials
- references/commands.md: full command map + all flags
- references/output.md: NDJSON output shapes + field details