feat: agent CLI — database access for AI agents, with approval-gated writes

[matej21]

Lets an AI coding agent work with your databases through the running Dotaz app — without ever holding your credentials. Reads run against a session the database itself enforces as read-only. Writes are supported too, but they route through you: the agent submits SQL, it opens in the app with Run/Reject, and only your click executes it.

Full design: docs/agent-cli.md.

How it works

The Electrobun backend serves a local control endpoint (unix socket, loopback TCP on Windows), discovered through a 0600 endpoint file and authenticated with a token. dotaz is a one-shot client against it, so it reuses the connections the user already configured in the app.

dotaz ls prod/app/public              # tables
dotaz describe prod/app/public/orders # columns, PK, indexes, FKs both ways
dotaz rows prod/app/public/orders --where "status='new'" --limit 20
dotaz ui open prod/app/public/orders  # open it in the user's window

dotaz propose prod "UPDATE orders SET status='paid' WHERE id=42" --reason "..."
# → opens in the app for Run/Reject; `dotaz approvals wait <id>` blocks on the decision

Three things this design turns on

Read-only comes from the engine, not from parsing SQL. PostgreSQL and MySQL get read-only session characteristics on the session's dedicated connection; SQLite gets a per-session handle with PRAGMA query_only. SQLite needed the most care — it shares one connection across sessions, so a naive pragma would have leaked into the UI's own queries. A statement classifier sits in front purely to fail fast with a useful message, and treats anything it cannot classify as a write.

Writes are proposed, not executed. dotaz propose opens the SQL in the user's app with Run/Reject. Approved SQL runs in the frontend's session, so the CLI session is never switched to read-write. Closing the tab reports back rather than leaving the CLI hanging.

The endpoint serves an allowlist, not the app's handler map. That map is built for the trusted webview: it includes connection deletion, imports, settings writes, and methods that return decrypted credentials. The CLI reaches ~20 named methods, and connections.list responses are stripped of passwords on the way out.

Off by default — Settings → Allow CLI access, or DOTAZ_CLI=1. No setting, no socket, no endpoint file. Toggling it starts and stops the endpoint without a restart.

Scope

Attach-to-running-app only. No headless mode and no remote mode in this PR — both were considered and deferred (headless means two writers on the app database; remote means web mode, where connections live in the browser's IndexedDB and the CLI cannot see them).

Verified against a running app

Not just unit tests — the desktop app was launched with the endpoint enabled and driven from a real CLI against a local SQLite database:

• Run → executed, 1 row affected, CLI exits 0, and the row really changed (checked from outside the app).
• Reject → rejected, CLI exits 8, and the DELETE never ran.
• No interaction → still pending after 30 s, CLI exits 7. There is no auto-run path.
• A write from the CLI exits 4 pointing at dotaz propose; ui.state reports the prefilled tab back to the CLI.

That run found two bugs, both fixed here. A proposal resolved behind the app's back (agent cancels it, or the TTL expires) left the banner fully live — and since Run executes before reporting, clicking it would have run a write for a proposal that no longer exists. And the spec claimed the endpoint file is removed on SIGTERM; Electrobun owns the signal handlers and exits through a native quit, so it never was. The docs now describe what actually happens, and nothing depends on that cleanup.

Testing

1832 tests pass. New coverage: statement classification, engine-level read-only enforcement per driver (PostgreSQL and MySQL blocks skip cleanly without Docker), proposal lifecycle, the method allowlist and password redaction, CLI path resolution and output capping, plus integration tests that drive the real binary against a real control server over a real unix socket.

Known limitation: SQLite agent sessions have no statement timeout. bun:sqlite exposes neither an interrupt nor a progress handler, and busy_timeout bounds lock waits rather than query runtime, so a read-only SQLite session can still run an unbounded scan. PostgreSQL and MySQL/MariaDB sessions are capped.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GaiURkVJQu7uSu1A7YUxP8