Brainforge Knowledge

motherduck-cli-setup

2 min read

MotherDuck CLI — install, auth, and connect

Last updated: 2026-04-09
Audience: Anyone using DuckDB CLI against Brainforge’s MotherDuck org (data engineering, analytics, agents).

Purpose

Single place for installing the DuckDB CLI, persisting authentication so you are not prompted in every new shell, and verifying a connection. Client-specific load steps (e.g. Default CSV exports) live in separate playbooks.

DocUse when
MotherDuck — Default export loadLanding Default product CSV exports into my_db / raw_export
MotherDuck: Brainforge warehouse overviewWhat databases/schemas exist (raw_export, raw_data, etc.)
MotherDuck: Default export pipeline (engineering)Pipeline layout, script names, runtime expectations

Official MotherDuck: DuckDB CLI + MotherDuck, Authenticating to MotherDuck.

1. Install (one-time per machine)

macOS (MotherDuck installer):

curl -s https://install.motherduck.com | sh

Add the CLI to your PATH (installer usually suggests):

export PATH="$HOME/.duckdb/cli/latest:$PATH"

Homebrew users may use brew install duckdb if versions remain compatible with MotherDuck; see MotherDuck’s version notes in their CLI doc.

Verify:

duckdb --version

2. Persist auth (stops repeated browser prompts)

Each run of duckdb "md:" in a new shell without a token can open MotherDuck SSO. Set MOTHERDUCK_TOKEN once per machine so routine CLI use and Cursor agents do not keep asking you to authenticate.

  1. Interactive session: duckdb, then ATTACH 'md:'; — complete browser login if prompted.
  2. In the same session: PRAGMA PRINT_MD_TOKEN; — copy the value (secret; never commit it).
  3. Persist it, for example:
    • export MOTHERDUCK_TOKEN='…' in ~/.zshrc / ~/.bashrc, or
    • Store in 1Password and export MOTHERDUCK_TOKEN="$(op read 'op://Vault/Item/field')", or
    • Cursor: env that applies to integrated terminal / agent runs (gitignored .env.local only if your workflow loads it).
  4. New terminal — verify (should not open a browser):
duckdb "md:" -c "SHOW DATABASES;"

Agents: Do not run duckdb "md:" in automation unless MOTHERDUCK_TOKEN is set for that process.

3. Quick queries after connect

SHOW ALL TABLES;
-- or scope to one database:
SHOW TABLES FROM raw_export;

Discover tables by name:

SELECT database_name, schema_name, table_name
FROM duckdb_tables()
WHERE lower(table_name) LIKE '%your_pattern%'
ORDER BY 1, 2, 3;

4. Troubleshooting

SymptomWhat to do
Browser SSO every timeSet and export MOTHERDUCK_TOKEN (§2); confirm new shells echo ${MOTHERDUCK_TOKEN:+set} shows set.
Non-interactive / CI failuresSame — token in env; no TTY for browser.
Version mismatchAlign DuckDB CLI with MotherDuck-supported versions per their docs.

Graph View

Backlinks