Command reference

Preview

This feature is in preview and is subject to change.

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.

Syntax

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

Commands

Command	Description
new	Create a MotherDuck account and organization, and save its token
login	Authenticate through an OAuth device flow
logout	Remove the saved token
status	Show authentication state, account, and duckling size
query	Run SQL against MotherDuck and write results to stdout
dive	Create and manage Dives, React apps hosted by MotherDuck
flight	Create and manage Flights, Python data pipelines that run on a schedule or on demand
guide	Create and manage Guides, Markdown documents that capture context about your data
upgrade	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
-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:

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.

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, .guide, or .org holds the result.

query 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 for how the CLI chooses between them, and install and upgrade for what lives under MOTHERDUCK_HOME.