Connections and Passwords

dbcode connections lists every saved connection with a cli column that says ok or why the CLI cannot open it. Most drivers work. The few that do not need a native library or Java, or come from a cloud provider; the column says which.

SQLite needs the database engine that DBCode downloads the first time you open a SQLite connection in the editor. If the CLI reports it missing, open any SQLite connection once.

Columns

The listing has name, id, driver, host, database, scope (whether the connection is saved for your user or the workspace) and cli.

When the table is wider than your terminal, the CLI drops the less useful columns in turn (first id, then host, then scope) so the names stay readable instead of every column being cut short. Widen the terminal, or pipe the output, to see them all.

Use --columns to choose the columns yourself, in any order:

dbcode connections --columns name,driver,database

--columns also works with the other formats. --format json (the default when the output is piped), --format csv and the rest always include every column otherwise, since they do not depend on the terminal width.

Passwords

The CLI honours the “Save password” choice on each connection.

• Secret storage (the default): the CLI reads the password your editor saved. On macOS this shows a Keychain prompt the first time, from the security tool, for the item named Code Safe Storage (or Cursor Safe Storage and so on). Click Always Allow to stop it asking. On Windows it is silent. On Linux it works with the basic password store and with an unlocked desktop keyring.
• Encrypted: you are asked for the encryption passphrase.
• Session and Prompt each time: you are asked for the password.
• Command: the command runs after you approve it, or with --yes.

Prompts go to your terminal, never to stdin, so they work while SQL is piped in. Without a terminal, a connection that needs a prompt fails with exit code 3 and a message saying why.

Authentication profiles

Connections that sign in through an authentication profile work from the CLI. The profile and its secrets come from the editor, so create the profile there first.

• .pgpass, Azure Storage, Entra ID with the Azure CLI or a service principal, AWS access keys or a signed-in AWS profile, and OAuth2 client credentials work everywhere, including the headless MCP server.
• OAuth2 and Entra ID single sign-on open your browser the first time. Run that first dbcode query on a terminal; after that the sign-in is remembered and works headless too.
• Command profiles ask for confirmation before the command runs, every run. Pass --yes to skip the question. The MCP server cannot ask, so it refuses these profiles, except when a profile caches its credentials for a set time and that cache is still valid; then no command runs.
• An expired AWS SSO session asks whether to run aws sso login; the device code is printed on the terminal.

The CLI keeps the tokens it obtains in globalStorage/dbcode.dbcode/cli-auth-state.json under your editor profile folder, encrypted with the same key the editor uses for its own secrets. Delete that file to discard the CLI’s own tokens; the CLI then falls back to the editor’s stored sign-in, so sign out in the editor to revoke access completely. The CLI never changes the editor’s stored sign-in.

Extra secrets a connection stores in the editor’s secret storage (for example an API token beside the password) are read the same way as the password.

SSH tunnels

Connections that go through an SSH tunnel work from the CLI, whether the tunnel was saved in the editor or comes from a host in your ~/.ssh/config. The CLI opens the tunnel, runs the query, and closes it.

• Tunnels saved in the editor connect with the same password, key or agent the editor uses. A password or key passphrase kept in secret storage is read the way connection passwords are. One saved as “session” or “prompt each time” is asked for on the terminal, and an “encrypted” one asks there for its encryption password.
• Hosts from ~/.ssh/config run your system’s ssh, so jump hosts, agents and known hosts behave exactly as on the command line. On a terminal, ssh asks its own questions, such as confirming a new host key.
• Command tunnels run the configured command and wait for its port, as the editor does. A command tunnel that comes from a workspace’s settings is confirmed on the terminal first (pass —yes to skip the question); the MCP server cannot ask, so it refuses those. Command tunnels in your user settings run without a question.

The headless MCP server cannot ask anything, so it needs a tunnel that opens on its own: a password or passphrase in secret storage, a password saved in the tunnel itself, an unencrypted key, or an agent; and for ~/.ssh/config hosts, a host key ssh already trusts. Anything else fails with a message saying what to do, usually to run the command once on a terminal or to open the editor.

If a tunnel drops while the MCP server is running, the connection is closed and the next request opens it again.