# dive
> Reference for the motherduck dive command group - init, watch, push, pull, list, list-versions, delete, and guide.
Create and manage [Dives](/key-tasks/dives/), React apps hosted by MotherDuck
that query your data live. You build a Dive locally, push it to MotherDuck,
then open it in the browser.

## Usage

```bash
motherduck dive <command> [options]
```

## Commands

| Command | Description |
|---|---|
| [`guide`](#dive-guide) | Print the Dive authoring guide |
| [`init`](#dive-init) | Initialize a new Dive in a local directory |
| [`watch`](#dive-watch) | Serve a local Dive and re-render it on every change |
| [`push`](#dive-push) | Push a local Dive to MotherDuck |
| [`pull`](#dive-pull) | Pull a Dive from MotherDuck into a local directory |
| [`list`](#dive-list) | List the Dives owned by the current user, or visible in their organization |
| [`list-versions`](#dive-list-versions) | List the versions of a Dive in MotherDuck |
| [`delete`](#dive-delete) | Delete a Dive from MotherDuck |

Every command also takes the [global options](./index.md#global-options).

## Dive directories

A Dive directory holds two files:

```text
my_dive/
├── index.tsx            # the component exported as the default, and the
│                        # REQUIRED_DATABASES it queries
└── dive.metadata.json   # title, description, and the Dive ID that push
                         # and pull resolve
```

Commands that act on one Dive take its directory (or `--dir`), and read the ID
from `dive.metadata.json`. Pass `--dive` instead to name it outright, as an ID
or an app URL:

```bash
--dive 123e4567-e89b-12d3-a456-426614174000
--dive https://app.motherduck.com/dives/my-dive-name-123e4567-e89b-12d3-a456-426614174000
```

A URL ending in `-v<n>` also selects that version for `pull`, unless
`--version` says otherwise.

## `dive guide`

Print the Dive authoring guide — read this before writing or editing a Dive.

The guide covers the component shape the runtime requires, the query APIs, the
libraries that can be imported, and the patterns that don't work. It's written
for an AI agent to consume directly. See
[working with agents](/getting-started/interfaces/motherduck-cli/agents/).

```bash
motherduck dive guide
```

## `dive init`

Creates a new local Dive directory and writes `index.tsx` and
`dive.metadata.json` there.

```bash
motherduck dive init [options] [dir]
```

### Arguments

| Argument | Description |
|---|---|
| `dir` | Directory to create the Dive in. Defaults to a directory named exactly as the title |

### Options

| Option | Description |
|---|---|
| `--title <string>` | Dive title. Required |
| `--description <string>` | Dive description |
| `--dir <path>` | Directory to create the Dive in. Defaults to a directory named exactly as the title |

### Examples

```bash
motherduck dive init dive_dir --title "My Dive"  # create ./dive_dir
motherduck dive init --title "My Dive"           # create "./My Dive"
```

Without a directory the title becomes the directory name.

## `dive watch`

Serve a local Dive and re-render it on every change.

```bash
motherduck dive watch [options] [dir]
```

### Arguments

| Argument | Description |
|---|---|
| `dir` | Directory holding the local Dive. Defaults to the current directory |

### Options

| Option | Description |
|---|---|
| `--dir <path>` | Directory holding the local Dive. Defaults to the current directory |
| `--port <number>` | Port to serve the Dive on. Defaults to 5173, or the next free port |
| `--log-file <path>` | Write NDJSON preview events to this file |
| `--no-open` | Don't open the preview in a browser |

### Examples

```bash
motherduck dive watch taxi_trips
motherduck dive watch taxi_trips --no-open --log-file preview.ndjson
```

## `dive push`

Publishes a local Dive to MotherDuck, creating it when `dive.metadata.json` has
no ID and updating it after that. Every push makes a new version. The options
below override what that file records, and are written back into it.

The databases and shares the Dive needs are read from the `REQUIRED_DATABASES`
export in `index.tsx`, the same declaration the Dive renders against, so
there's nothing to keep in step by hand.

```bash
motherduck dive push [options] [dir]
```

### Arguments

| Argument | Description |
|---|---|
| `dir` | Directory holding the local Dive. Defaults to the current directory |

### Options

| Option | Description |
|---|---|
| `--title <string>` | Dive title |
| `--description <string>` | Dive description |
| `--version-description <string>` | Description for the new version |
| `--dir <path>` | Directory holding the local Dive. Defaults to the current directory |

### Examples

```bash
motherduck dive push my_dive        # push ./my_dive
motherduck dive push                # push the current directory
motherduck dive push my_dive --title "New title"
motherduck dive push my_dive --version-description "fix the axis labels"
```

## `dive pull`

Fetches a Dive from MotherDuck. It overwrites existing `index.tsx` and
`dive.metadata.json`. Find IDs with [`dive list`](#dive-list).

```bash
motherduck dive pull [options] [id-or-url]
```

Which Dive: the positional ID or app URL, otherwise the ID recorded in
`dive.metadata.json` in the destination directory.

Where to pull: `--dir`, otherwise the current directory. Pull writes files, so
it always has a destination.

### Arguments

| Argument | Description |
|---|---|
| `id-or-url` | Dive ID or app URL. Defaults to the ID from `dive.metadata.json` |

### Options

| Option | Description |
|---|---|
| `--dir <path>` | Directory to pull the Dive into. Defaults to the current directory |
| `--version <n>` | Pull a specific version. Defaults to the latest |

### Examples

```bash
motherduck dive pull                          # update the Dive in the current directory
motherduck dive pull <id-or-url>              # into the current directory
motherduck dive pull <id-or-url> --dir my_dive
motherduck dive pull <id-or-url> --version 2
```

## `dive list`

Endorsed first, then ready, draft, and archived; within each, newest by the
time it was last updated.

`--title` filters the page `--limit` and `--offset` selected, so it can return
fewer rows than `--limit`. Raise `--limit` to search deeper.

```bash
motherduck dive list [options]
```

### Options

| Option | Description |
|---|---|
| `--limit <number>` | Limit results. Defaults to 100 |
| `--offset <number>` | Result offset. Defaults to 0 |
| `--title <text>` | Only Dives whose title contains this text, case insensitive |
| `--all` | Include Dives shared with your organization. Defaults to false |

### Examples

```bash
motherduck dive list
motherduck dive list --title taxi            # titles containing "taxi"
motherduck dive list --title taxi --limit 500
motherduck dive list --all                   # the organization's too
```

## `dive list-versions`

Lists a Dive's versions in MotherDuck, one per push, newest first. Fetch one
with [`dive pull --version <n>`](#dive-pull).

```bash
motherduck dive list-versions [options] [dir]
```

### Arguments

| Argument | Description |
|---|---|
| `dir` | Dive directory to read the Dive ID from. Defaults to the current directory |

### Options

| Option | Description |
|---|---|
| `--dive <id-or-url>` | Dive ID or app URL |
| `--dir <path>` | Dive directory to read the Dive ID from. Defaults to the current directory |
| `--limit <number>` | Limit results. Defaults to 100 |
| `--offset <number>` | Result offset. Defaults to 0 |

### Examples

```bash
motherduck dive list-versions                # the current directory's
motherduck dive list-versions my_dive
motherduck dive list-versions --dive <id-or-url> --limit 5
```

## `dive delete`

Deletes a Dive from MotherDuck, along with its versions. This can't be undone.
The local files stay where they are.

```bash
motherduck dive delete [options]
```

### Options

| Option | Description |
|---|---|
| `--dive <id-or-url>` | Dive ID or app URL. Required |
| `--dangerously-skip-confirmation` | Delete without interactive confirmation |

### Examples

```bash
motherduck dive delete --dive <id-or-url>
motherduck dive delete --dive <id-or-url> --dangerously-skip-confirmation
```

:::warning
Pass `--dangerously-skip-confirmation` only in scripts where you've already
confirmed the ID.
:::

## Related

- [Quickstart](/getting-started/interfaces/motherduck-cli/quickstart/) builds and publishes a Dive end to end
- [Dives](/key-tasks/dives/)
- [`flight`](./flight.md)


---

## 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%2Fdive%2F&page_title=dive&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.