# Authentication
> Sign the MotherDuck CLI in through your browser, on a headless machine, or with a token in CI.
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.

| Approach | Use it when |
|---|---|
| [Sign in](#signing-in) with `motherduck login` | You have an account, or you're about to [sign up](https://app.motherduck.com/) for one |
| [Set a token](#using-access-tokens-in-unattended-environments) | An unattended run needs credentials: CI, a container, a scheduled job |
| [`motherduck new`](/sql-reference/motherduck-cli/new/) | There's no account to sign in to yet, and you want one from the terminal |

## Signing in

```bash
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`](#signing-out) 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.

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
motherduck logout
```

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

## Related

- [`login`](/sql-reference/motherduck-cli/login/), [`logout`](/sql-reference/motherduck-cli/logout/), and [`status`](/sql-reference/motherduck-cli/status/) in the command reference
- [`new`](/sql-reference/motherduck-cli/new/) creates an account and organization when there isn't one to sign in to
- [Securing read-only access](../../../key-tasks/ai-and-motherduck/securing-read-only-access.mdx)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fgetting-started%2Finterfaces%2Fmotherduck-cli%2Fauthentication%2F&page_title=Authentication&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.