Skip to main content

Authentication

Preview
This feature is in preview and is subject to change.

The CLI needs a credential before it can do anything but print help. There are two ways to give it one, and which fits depends on who's at the keyboard.

ApproachUse it when
Sign in with motherduck loginYou have an account, or you're about to sign up for one
Set a tokenAn unattended run needs credentials: CI, a container, a scheduled job
motherduck newThere's no account to sign in to yet, and you want one from the terminal

Signing in​

motherduck login

This opens your browser, completes an OAuth device flow, and saves the token to ~/.motherduck/credentials.json, in plain text. Later commands read it from there, so you sign in once per machine, and motherduck logout deletes the file.

tip

Set MOTHERDUCK_HOME to override where the credential files and the asset cache are stored. This gives parallel runs in CI and sandboxes an isolated environment each.

export MOTHERDUCK_HOME=/workspace/.motherduck

On a machine with no browser, start the headless login flow. Open the printed sign in URL on any other device, then resume:

motherduck login --headless
motherduck login --device-code <code>

The first command prints a device code and returns rather than polling. Pass that code to the second command to complete the sign in.

Check the result at any time:

motherduck status

Using access tokens in unattended environments​

For CI and other unattended runs, set a token rather than signing in. The CLI reads MOTHERDUCK_TOKEN before it looks at the saved credentials, so it wins wherever both exist:

export MOTHERDUCK_TOKEN=<your_token>

motherduck status reports which credential is active, under Token source. When a command touches an account you didn't expect, read that row first.

Signing out​

motherduck logout

This removes the saved token. It has no effect on MOTHERDUCK_TOKEN, so unset that variable too if you set it.