# Command reference
> Every MotherDuck CLI command with its arguments, options, output formats, and exit behavior.
This section documents every `motherduck` command: its arguments, its options,
and what it writes. To learn the CLI by using it, start with the
[quickstart](/getting-started/interfaces/motherduck-cli/quickstart/).

## Syntax

```bash
motherduck <command> [subcommand] [arguments] [options]
```

## Commands

| Command | Description |
|---|---|
| [`new`](./new.md) | Create a MotherDuck account and organization, and save its token |
| [`login`](./login.md) | Authenticate through an OAuth device flow |
| [`logout`](./logout.md) | Remove the saved token |
| [`status`](./status.md) | Show authentication state, account, and duckling size |
| [`query`](./query.md) | Run SQL against MotherDuck and write results to stdout |
| [`dive`](./dive.md) | Create and manage Dives, React apps hosted by MotherDuck |
| [`flight`](./flight.md) | Create and manage Flights, Python data pipelines that run on a schedule or on demand |
| [`upgrade`](./upgrade.md) | Upgrade the `motherduck` CLI |

## Global options

These are available on every command, and the pages in this section don't
repeat them.

| Option | Description |
|---|---|
| `-o, --output <format>` | Print output as `table`, `json`, or `csv`. Defaults to `table`. See [output formats](#output-formats) |
| `-h, --help` | Print help for the CLI or for any command |
| `-V, --version` | Print the CLI version. Top level only |

Help is available at every level, and the deepest level carries the examples:

```bash
motherduck --help
motherduck dive --help
motherduck dive push --help
```

`motherduck help <command>` prints the same text.

## Output formats

Commands that return structured results accept `-o, --output <format>` with
`table`, `json`, or `csv`. `table` is the default and is meant for reading; the
other two are meant for piping.

```bash
motherduck status -o json
motherduck dive list -o csv > dives.csv
```

`login`, `logout`, and `upgrade` have no formatted output, so they don't accept
the option. `csv` covers commands with a naturally tabular result; a command
without one rejects the format before doing any work rather than inventing a
shape.

### Result shape

Commands that act on a resource wrap it under a `success` discriminant and name
the resource, so `.dive`, `.flight`, or `.org` holds the result.

[`query`](./query.md) is the exception. It returns its rows as a bare JSON
array, because there's no resource to name.

Failures are uniform across every command. Each writes an error object carrying
`success` and `error`, and exits non-zero, so a script branches on one field
instead of parsing prose.

## Environment variables

| Variable | Effect |
|---|---|
| `MOTHERDUCK_TOKEN` | Token to authenticate with. Takes precedence over the saved credentials for every command |
| `MOTHERDUCK_HOME` | Relocates the credentials, state, and asset tree from `~/.motherduck`. Must be an absolute path |

See [authentication](/getting-started/interfaces/motherduck-cli/authentication/) for how the CLI chooses between
them, and [install and upgrade](/getting-started/interfaces/motherduck-cli/install/) for what lives under
`MOTHERDUCK_HOME`.


---

## 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%2F&page_title=Command%20reference&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.