# login
> Reference for motherduck login, which authenticates the CLI through an OAuth device flow, including headless machines.
Authenticate through an OAuth device flow. Use `--headless` on a machine with
no browser, or set `MOTHERDUCK_TOKEN`.

The token is saved to `${MOTHERDUCK_HOME:-~/.motherduck}/credentials.json`, so
you sign in once per machine.

## Usage

```bash
motherduck login [options]
```

## Options

| Option | Description |
|---|---|
| `--headless` | Start the OAuth device flow, print the device code, and return without polling |
| `--device-code <code>` | Resume a pending headless OAuth device flow from the displayed code |

`--headless` and `--device-code` are mutually exclusive: the first starts a
flow, the second finishes by sending the code.

`login` has no formatted output, so it doesn't take `-o, --output`.

## Examples

Sign in through the browser:

```bash
motherduck login
```

Sign in on a machine with no browser. The first command prints a code, which
you open on any other device; the second completes the flow:

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

## Related

- [`logout`](./logout.md) removes the saved token
- [`status`](./status.md) confirms which credential is in use
- [`new`](./new.md) creates an account instead of signing in to one
- [Authentication](/getting-started/interfaces/motherduck-cli/authentication/)


---

## 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=%2Fsql-reference%2Fmotherduck-cli%2Flogin%2F&page_title=login&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.