dive
Create and manage 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
motherduck dive <command> [options]
Commands
| Command | Description |
|---|---|
guide | Print the Dive authoring guide |
init | Initialize a new Dive in a local directory |
watch | Serve a local Dive and re-render it on every change |
push | Push a local Dive to MotherDuck |
pull | Pull a Dive from MotherDuck into a local directory |
list | List the Dives owned by the current user, or visible in their organization |
list-versions | List the versions of a Dive in MotherDuck |
delete | Delete a Dive from MotherDuck |
Every command also takes the global options.
Dive directories
A Dive directory holds two files:
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:
--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.
motherduck dive guide
dive init
Creates a new local Dive directory and writes index.tsx and
dive.metadata.json there.
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
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.
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
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.
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
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.
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
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.
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
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>.
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
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.
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
motherduck dive delete --dive <id-or-url>
motherduck dive delete --dive <id-or-url> --dangerously-skip-confirmation
Pass --dangerously-skip-confirmation only in scripts where you've already
confirmed the ID.
Related
- Quickstart builds and publishes a Dive end to end
- Dives
flight