Agent CLI contract
Every command prints one JSON envelope on stdout. Stderr is diagnostics only.
-o pretty indents the same envelope for humans; agents keep the default
compact json.
Envelope
Section titled “Envelope”{ "ok": true, "api_version": "miudb.cli/v1", "kind": "query.result", "command": "query run", "request_id": "req_...", "summary": { "connection": "app", "db_type": "sqlite" }, "data": { "connection": "app", "result": { "columns": [{ "name": "id", "type": "INTEGER", "nullable": true }], "rows": [[1], [2]], "truncated": true } }, "page": { "limit": 2, "next_cursor": "..." }, "artifacts": [], "warnings": []}summary,data,page, andstatsare omitted when empty.artifactsandwarningsare always arrays.- Rows are positional arrays matching
columns.truncated: truewithpage.next_cursormeansquery fetch-page --cursorhas more. erdcommands list written files inartifacts.
On failure ok is false, kind is error, and there is no data:
{ "ok": false, "kind": "error", "command": "query run", "error": { "code": "connection.not_found", "message": "connection not found", "retryable": false } }error may also carry hint, safe_to_retry, and details.
One exception: when a statement in query script fails, the envelope keeps
kind: query.script_result with ok: false, no error object, and
data.results plus data.errors for the statements that ran. The exit code is 2.
Exit codes
Section titled “Exit codes”| Exit | Meaning |
|---|---|
0 | Success. Also connections smoke with failed connections: read data.results[].ok and summary.failed. |
2 | Bad input or a known failure: connection.not_found, invalid flags or options, unsupported script or session key, ERD errors |
1 | Everything else, including driver errors (internal.error), unknown flags, and failed upgrades |
Always branch on ok, not only the exit code.
Common error codes
Section titled “Common error codes”| Code | Meaning |
|---|---|
connection.not_found | No connection with that ref. List them with connections list --basic. |
connection.missing_input, connection.invalid_option | connections add input is incomplete or malformed |
connection.import_unreadable, connection.import_empty | The import file cannot be read or has no connections |
query.missing_input, query.missing_cursor | --sql or --cursor missing |
query.multi_statement_not_allowed | Several statements sent to query run; use query script |
query.script_unsupported | Script on SQLite, Postgres, or BigQuery |
query.unsupported_session_key | --session key the provider does not accept |
erd.unsupported_db, erd.missing_connection, erd.meta_invalid | ERD input errors |
activity.invalid_since, activity.invalid_older_than | Bad duration |
upgrade.managed_install | Installed by Homebrew; use brew upgrade miudb |
internal.error | Driver or unexpected error; the message says what failed |
Redaction
Section titled “Redaction”Credential-named fields (password, secret, token, private_key,
api_key, and similar), password-bearing URLs, and key=secret assignments are
replaced before anything reaches stdout. connections list shows
has_password: true, never the value. Query values are not masked; they are the
user’s data.
Discovery
Section titled “Discovery”miudb commands # catalog: name, summary, stability, mutates, side effectsmiudb describe query run # one commandmiudb connections list --basic # refs to pass to --connectionOther transports
Section titled “Other transports”| Command | For |
|---|---|
miudb mcp serve --transport stdio | MCP hosts. See MCP server. |
miudb serve --protocol jsonrpc | JSON-RPC 2.0 over stdio with call-event notifications (Neovim, custom clients) |
miudb serve --protocol ndjson | One line-delimited envelope per request, response, and event |
Neither serve mode writes human progress to stdout.