Where MotherDuck read/write and read-scaling tokens live in THYROID_2026, resolution order, and safe usage. Use whenever running --md scripts, MotherDuckClient, or answering "where is the API key".
motherduck_client.py — get_token() (RW), get_read_scaling_token() (read-scaling only). Prefer importing these instead of reading files ad hoc.get_token)Matches docs/motherduck_database_contract_v1.md §8 and the docstring in motherduck_client.py:
MD_SA_TOKENMOTHERDUCK_TOKENmotherduck_token (alias)LOCAL_DB_PATH — only if the value looks like a JWT / md_ PAT (misconfig guard)motherduck.local.toml — keys in order: MD_SA_TOKEN, , MOTHERDUCK_TOKENmotherduck_token.streamlit/secrets.toml — same key order as (5)Bootstrap: Copy motherduck.local.toml.example → motherduck.local.toml at repo root and set keys there (file stays gitignored).
Optional env files: At import, motherduck_client may load repo-root .env and .env.motherduck via python-dotenv (override=False). See .env.motherduck.example if present.
get_read_scaling_token)Use only for read-only / dashboard attach patterns — never as RW for promotion or connect_rw().
Order: MD_READ_SCALING_TOKEN → MOTHERDUCK_READ_SCALING_TOKEN → motherduck.local.toml → .streamlit/secrets.toml.
AGENTS.md).--md; some support --md-sa to prefer MD_SA_TOKEN where documented.MOTHERDUCK_SESSION_HINT (see smoke test and runbooks under docs/motherduck_*.md).| Purpose | Primary keys | Typical file / source |
|---|---|---|
| RW (dev/CI) | MD_SA_TOKEN, MOTHERDUCK_TOKEN | Env → motherduck.local.toml → .streamlit/secrets.toml |
| Read-scaling | MD_READ_SCALING_TOKEN, MOTHERDUCK_READ_SCALING_TOKEN | Same TOML files after env |
When the user says "use the token in the TOML file," they mean repo-root motherduck.local.toml (from the example), not a committed path with real secrets.