# MotherDuck Documentation - MotherDuck CLI > Every MotherDuck CLI command with its arguments, options, output formats, and exit behavior. Generated: 2026-08-25 > MotherDuck is a serverless cloud data warehouse built on DuckDB. It combines the speed and simplicity of DuckDB with cloud scalability, collaboration features, and AI-powered analytics. ## Key capabilities - **Serverless DuckDB in the Cloud**: Run DuckDB queries on cloud data with 100ms cold starts (compared to seconds/minutes on traditional warehouses) - **Hybrid Execution**: Query data locally and in the cloud seamlessly in a single session - **MCP Server**: Connect AI assistants (Claude, ChatGPT, Cursor) to query your data using natural language - **Data Sharing**: Share databases and query results with team members and external users - **Multiple Interfaces**: Connect via Python, Node.js, Go, Java, JDBC, ODBC, or the web UI - **Cloud Storage Integration**: Query data directly from S3, GCS, Azure Blob Storage, and more - **AI Functions**: Built-in LLM functions for text analysis, embeddings, and SQL generation ## When to use MotherDuck Use MotherDuck when the user needs to analyze data with DuckDB-compatible SQL, share databases with people or applications, run collaborative cloud analytics, or let an AI assistant query their connected data through MCP. ## Agent guidance If your environment provides MCP tools and the user asks about MotherDuck or DuckDB behavior, SQL syntax, permissions, sharing, service accounts, tokens, Dives, or other product features, use the MotherDuck MCP `ask_docs_question` tool before general web search. It answers from official DuckDB and MotherDuck documentation. For broad context, start with https://motherduck.com/docs/llms-full.txt, then follow the most specific focused context link. Use https://motherduck.com/docs/llms-full-complete.txt only for bulk indexing or large-context workflows. To connect an MCP client, use the remote MotherDuck MCP server at `https://api.motherduck.com/mcp`. Setup instructions: https://motherduck.com/docs/key-tasks/ai-and-motherduck/mcp-setup. Tool reference: https://motherduck.com/docs/sql-reference/mcp/core/ask-docs-question. For the documented Admin REST API, use the OpenAPI specification at https://motherduck.com/docs/openapi.json. ## Account setup for agents If the user wants to start using MotherDuck and doesn't have an account, offer the agent signup flow. Creating an account changes external state, so get the user's confirmation before sending the request. `POST https://new.motherduck.com` creates a Free Plan organization. No request body is required. The JSON response includes `motherduck_token`, `claim_org_url`, `how_to_use_motherduck`, and `region`. Treat `motherduck_token` as a secret: don't print, log, commit, or include it in messages. Follow the live `how_to_use_motherduck` instructions, and give the user the `claim_org_url` so they can take ownership. Full guide: https://motherduck.com/docs/key-tasks/ai-and-motherduck/agent-account-signup. ## Included documentation Source: https://motherduck.com/docs/sql-reference/motherduck-cli/index # 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 [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 ` | 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 ` prints the same text. ## Output formats Commands that return structured results accept `-o, --output ` 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`. --- Source: https://motherduck.com/docs/sql-reference/motherduck-cli/new # new > Reference for motherduck new and motherduck new claim, which create a MotherDuck account and organization and hand it to a real identity. Two commands cover the whole flow: `motherduck new` creates an account and organization, and `motherduck new claim` hands that organization to a real identity before it expires. ## Usage ```bash motherduck new [options] motherduck new claim [options] ``` ## `motherduck new` Creates a MotherDuck account and organization on the Free Plan, with no browser and no signup form. A MotherDuck token is returned and saved to `${MOTHERDUCK_HOME:-~/.motherduck}/credentials.json`; every command after is authenticated. The organization is separate from any account you already have, and stays ownerless until someone opens the claim URL and signs up. :::warning An unclaimed organization lapses 72 hours after it's created, and its data goes with it. [Claim it](#motherduck-new-claim) to keep anything you build. ::: ### Options | Option | Description | |---|---| | `--force` | Replace the login credentials and any unclaimed organization | | `--region ` | AWS region for the new organization, for example `aws-eu-central-1`. Defaults to `aws-us-east-1` | A new organization means a new token, and the CLI holds one set of credentials, so the command refuses to run when you're already signed in. Sign out first, or overwrite deliberately with `--force`. Note that `--force` does not override `MOTHERDUCK_TOKEN`: unset that variable first. `--region` does not default to your location. See [cloud regions](/about-motherduck/cloud-regions.mdx) for which regions are available, prefixed with `aws-`. ### Examples ```bash motherduck new motherduck new --region aws-eu-central-1 motherduck logout && motherduck new motherduck new --force motherduck new -o json ``` ### Output Reports the region the organization was created in, that the new token is now your login credentials, and the claim URL with how long it stays valid. ## `motherduck new claim` Claiming transfers the organization, and everything in it, to a real MotherDuck identity, and starts a 7-day Business plan trial. When that trial ends the organization continues on the Free Plan. Open the URL `motherduck new` printed, or bring it back up: ```bash motherduck new claim ``` In `table` output this also opens the URL in a browser, on a host that has one. With `-o json` or `-o csv` it prints the URL and expiry without opening anything, which is what a script or an agent wants. While the window is open, [`motherduck status`](./status.md) carries the same information. :::warning The token `motherduck new` saves grants read and write access to the account it created. Anyone who can read your credentials file can reach that data. ::: ## When to use it, and when to sign up instead The account `motherduck new` creates isn't tied to a person, and it's temporary until claimed. That makes it right for some situations and wrong for others. [Sign up](https://app.motherduck.com/), then run [`motherduck login`](./login.md), when: - You're **joining an organization** that already exists, where you want an invitation rather than a new organization of your own. - The account is **yours and meant to last**, tied to your email from the start. - You need **billing, teammates, or a paid plan** from the beginning. Use `motherduck new` when: - An **AI agent** is working on someone's behalf and has no credentials to start from. See [working with agents](/getting-started/interfaces/motherduck-cli/agents/). - A **CI job or sandbox** needs a throwaway account for the length of a run. - You want to **try MotherDuck immediately** without stopping to fill in a form, and you'll claim it if the work turns out to be worth keeping. ## Related - [`status`](./status.md) reports the claim URL and time left while the window is open - [Authentication](/getting-started/interfaces/motherduck-cli/authentication/) for signing in to an account you already have - [Create and claim accounts for AI agents](/key-tasks/ai-and-motherduck/agent-account-signup/) covers the plan these accounts land on, and the signup API the commands wrap --- Source: https://motherduck.com/docs/sql-reference/motherduck-cli/login # 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 ` | 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 ``` ## 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/) --- Source: https://motherduck.com/docs/sql-reference/motherduck-cli/logout # logout > Reference for motherduck logout, which removes the token saved by motherduck login. Remove saved token. This deletes `${MOTHERDUCK_HOME:-~/.motherduck}/credentials.json`, written by [`login`](./login.md) or [`new`](./new.md). It has no effect on the environment variable `MOTHERDUCK_TOKEN`. ## Usage ```bash motherduck logout ``` `logout` has no formatted output, so it doesn't take `-o, --output`. ## Related - [`status`](./status.md) confirms you're signed out - [Authentication](/getting-started/interfaces/motherduck-cli/authentication/) --- Source: https://motherduck.com/docs/sql-reference/motherduck-cli/status # status > Reference for motherduck status, which reports authentication state, token source, account, and duckling size. Show authentication state, account, and duckling size. ## Usage ```bash motherduck status [options] ``` ## Examples ```bash motherduck status motherduck status -o json ``` ## Output Reports whether you're authenticated, which credential the CLI used, the account and organization it belongs to, and the duckling size. The credential source is worth reading first. The CLI prefers `MOTHERDUCK_TOKEN` over the saved token, so when a command touches an account you didn't expect, that's where to look. On an organization created by [`new`](./new.md) and not yet claimed, the claim URL and the time left appear as well, for as long as the claim is valid. ## Related - [`login`](./login.md) and [`logout`](./logout.md) - [`new claim`](./new.md#motherduck-new-claim) reprints the claim URL - [Authentication](/getting-started/interfaces/motherduck-cli/authentication/) --- Source: https://motherduck.com/docs/sql-reference/motherduck-cli/query # query > Reference for motherduck query, which runs SQL against MotherDuck and writes results to stdout as a table, JSON, or CSV. Execute a SQL query against MotherDuck and write results to stdout. ## Usage ```bash motherduck query [options] [sql] ``` ## Arguments | Argument | Description | |---|---| | `sql` | The statement to run. Omit it when reading from `--file` | ## Options | Option | Description | |---|---| | `--file ` | Read SQL from a file | | `--timeout ` | Query timeout in seconds. Defaults to 120 | ## Examples ```bash motherduck query "SELECT count(*) FROM sample_data.nyc.taxi" motherduck query --file monthly_report.sql motherduck query --file backfill.sql --timeout 600 motherduck query "SELECT * FROM sample_data.nyc.taxi LIMIT 100" -o csv > trips.csv motherduck query "SELECT * FROM sample_data.nyc.taxi LIMIT 100" -o json | jq '.[0]' ``` ## Related - [Quickstart](/getting-started/interfaces/motherduck-cli/quickstart/) walks through querying and reading JSON output - [Working with agents](/getting-started/interfaces/motherduck-cli/agents/) --- Source: https://motherduck.com/docs/sql-reference/motherduck-cli/dive # 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 [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` 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 ` | Dive title. Required | | `--description ` | Dive description | | `--dir ` | 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 ` | Directory holding the local Dive. Defaults to the current directory | | `--port ` | Port to serve the Dive on. Defaults to 5173, or the next free port | | `--log-file ` | 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 ` | Dive title | | `--description ` | Dive description | | `--version-description ` | Description for the new version | | `--dir ` | 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 ` | Directory to pull the Dive into. Defaults to the current directory | | `--version ` | Pull a specific version. Defaults to the latest | ### Examples ```bash motherduck dive pull # update the Dive in the current directory motherduck dive pull # into the current directory motherduck dive pull --dir my_dive motherduck dive pull --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 ` | Limit results. Defaults to 100 | | `--offset ` | Result offset. Defaults to 0 | | `--title ` | 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 `](#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 ` | Dive ID or app URL | | `--dir ` | Dive directory to read the Dive ID from. Defaults to the current directory | | `--limit ` | Limit results. Defaults to 100 | | `--offset ` | 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 --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 ` | Dive ID or app URL. Required | | `--dangerously-skip-confirmation` | Delete without interactive confirmation | ### Examples ```bash motherduck dive delete --dive motherduck dive delete --dive --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) --- Source: https://motherduck.com/docs/sql-reference/motherduck-cli/flight # flight > Reference for the motherduck flight command group - init, push, pull, run, logs, secrets, schedules, and versions. Create and manage [Flights](/key-tasks/flights/), Python data pipelines that run on a schedule or on demand. You build a Flight locally, push it to MotherDuck, then trigger runs and read their logs. ## Usage ```bash motherduck flight [options] ``` ## Commands | Command | Description | |---|---| | [`guide`](#flight-guide) | Print the Flight authoring guide | | [`init`](#flight-init) | Initialize a new Flight in a local directory | | [`push`](#flight-push) | Push a local Flight to MotherDuck | | [`pull`](#flight-pull) | Pull a Flight from MotherDuck into a local directory | | [`run`](#flight-run) | Run a Flight once, now | | [`cancel`](#flight-cancel) | Cancel a running Flight run | | [`logs`](#flight-logs) | Print the logs of a Flight run | | [`list-runs`](#flight-list-runs) | List the runs of a Flight | | [`list`](#flight-list) | List the Flights owned by the current user, or visible in their organization | | [`list-versions`](#flight-list-versions) | List the versions of a Flight in MotherDuck | | [`create-secret`](#flight-create-secret) | Create a flight secret | | [`list-secrets`](#flight-list-secrets) | List your flight secrets | | [`delete-secret`](#flight-delete-secret) | Delete a flight secret | | [`delete`](#flight-delete) | Delete a Flight from MotherDuck | Every command also takes the [global options](./index.md#global-options). ## Flight directories A Flight directory holds: ```text my_flight/ ├── main.py # the script, run as `python main.py` ├── requirements.txt # packages to install first (optional) └── flight.metadata.json # name, schedule, config, and the Flight ID that # push and pull resolve ``` Commands that act on one Flight take its directory (or `--dir`), and read the ID from `flight.metadata.json`. Pass `--flight` instead to name it outright, as an ID or an app URL: ```bash --flight 123e4567-e89b-12d3-a456-426614174000 --flight https://app.motherduck.com/flights/my-flight-123e4567-e89b-12d3-a456-426614174000 ``` A URL ending in `/versions/` also selects that version for `pull`, unless `--version` says otherwise. Where a command below says **which Flight**, the rule is the same: `--flight`, else the ID recorded in the Flight directory's `flight.metadata.json`. Given both, the two must resolve to the same ID. Given neither, the ID is read from `flight.metadata.json` in the current directory. ## `flight guide` Print the Flight authoring guide — read this before writing or editing a Flight. The guide covers the runtime's expectations, the supported APIs, and the data pipeline practices it assumes. It's written for an AI agent to consume directly. See [working with agents](/getting-started/interfaces/motherduck-cli/agents/). ```bash motherduck flight guide ``` ## `flight init` Creates a new local Flight directory and writes `main.py`, `requirements.txt`, and `flight.metadata.json` there. ```bash motherduck flight init [options] [dir] ``` ### Arguments | Argument | Description | |---|---| | `dir` | Directory to create the Flight in. Defaults to a directory named after `--name` | ### Options | Option | Description | |---|---| | `--name ` | Flight name. Required | | `--dir ` | Directory to create the Flight in. Defaults to a directory named after `--name` | ### Examples ```bash motherduck flight init --name my_flight # create ./my_flight motherduck flight init flight_dir --name my_flight # create ./flight_dir ``` ## `flight push` Publishes a local Flight to MotherDuck, creating it when `flight.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. ```bash motherduck flight push [options] [dir] ``` ### Arguments | Argument | Description | |---|---| | `dir` | Directory holding the local Flight. Defaults to the current directory | ### Options | Option | Description | |---|---| | `--dir ` | Directory holding the local Flight. Defaults to the current directory | | `--name ` | Flight name | | `--schedule-cron ` | Schedule as a 5-field cron expression in UTC, for example `"0 9 * * 1-5"`. Pass `""` to unschedule | | `--config ` | Non-secret values exposed to the Flight as environment variables, for example `'{"TARGET_DB":"prod"}'` | | `--access-token-name ` | MotherDuck access token the Flight runs with | | `--secret-names ` | Comma-separated MotherDuck secret names to expose | | `--max-runtime-sec ` | Per-run timeout in seconds. `0` means no timeout | | `--run` | Run the Flight once after pushing | ### Examples ```bash motherduck flight push my_flight # push ./my_flight motherduck flight push # push the current directory motherduck flight push my_flight --run # push, then run it once motherduck flight push my_flight --schedule-cron "0 9 * * 1-5" motherduck flight push my_flight --schedule-cron "" # stop the schedule motherduck flight push my_flight --config '{"TARGET_DB":"prod"}' ``` ## `flight pull` Fetches a Flight from MotherDuck. It overwrites existing `main.py`, `requirements.txt`, and `flight.metadata.json`. Find IDs with [`flight list`](#flight-list). ```bash motherduck flight pull [options] [id-or-url] ``` Which Flight: the positional ID or app URL, otherwise the ID recorded in `flight.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` | Flight ID or app URL. Defaults to the ID from `flight.metadata.json` | ### Options | Option | Description | |---|---| | `--dir ` | Directory to pull the Flight into. Defaults to the current directory | | `--version ` | Pull a specific version. Defaults to the one named by the Flight URL, else the latest | ### Examples ```bash motherduck flight pull # update the Flight in the current directory motherduck flight pull # into the current directory motherduck flight pull --dir my_flight motherduck flight pull --version 2 ``` ## `flight run` Runs a Flight's current version once, now. The run is queued and the command returns its number right away; watch it with [`flight list-runs`](#flight-list-runs) and read its output with [`flight logs --run `](#flight-logs). ```bash motherduck flight run [options] [dir] ``` ### Arguments | Argument | Description | |---|---| | `dir` | Flight directory to read the Flight ID from. Defaults to the current directory | ### Options | Option | Description | |---|---| | `--flight ` | Flight ID or app URL | | `--dir ` | Flight directory to read the Flight ID from. Defaults to the current directory | | `--config ` | Override config values for this run only. Keys must already be defined on the Flight, for example `'{"TARGET_DB":"staging"}'` | ### Examples ```bash motherduck flight run # the current directory's motherduck flight run my_flight motherduck flight run --flight motherduck flight run my_flight --config '{"TARGET_DB":"staging"}' ``` ## `flight cancel` Stops a run of a Flight. Only a pending or running one can be cancelled, and only on a Flight you own. Run numbers come from [`flight list-runs`](#flight-list-runs). ```bash motherduck flight cancel [options] [dir] ``` ### Arguments | Argument | Description | |---|---| | `dir` | Flight directory to read the Flight ID from. Defaults to the current directory | ### Options | Option | Description | |---|---| | `--run ` | Run number to cancel. Required | | `--flight ` | Flight ID or app URL | | `--dir ` | Flight directory to read the Flight ID from. Defaults to the current directory | ### Examples ```bash motherduck flight cancel --run 4 # the current directory's motherduck flight cancel my_flight --run 4 motherduck flight cancel --flight --run 4 ``` ## `flight logs` Prints what a run has printed so far, stdout and stderr together, verbatim so it can be piped. Run numbers come from [`flight list-runs`](#flight-list-runs). ```bash motherduck flight logs [options] [dir] ``` ### Arguments | Argument | Description | |---|---| | `dir` | Flight directory to read the Flight ID from. Defaults to the current directory | ### Options | Option | Description | |---|---| | `--run ` | Run number. Required | | `--flight ` | Flight ID or app URL | | `--dir ` | Flight directory to read the Flight ID from. Defaults to the current directory | ### Examples ```bash motherduck flight logs --run 4 # the current directory's motherduck flight logs my_flight --run 4 motherduck flight logs --flight --run 4 | grep -i error ``` ## `flight list-runs` Lists a Flight's runs, newest first, with the version each one ran and how it ended. The run numbers here are what `--run` takes. ```bash motherduck flight list-runs [options] [dir] ``` ### Arguments | Argument | Description | |---|---| | `dir` | Flight directory to read the Flight ID from. Defaults to the current directory | ### Options | Option | Description | |---|---| | `--flight ` | Flight ID or app URL | | `--dir ` | Flight directory to read the Flight ID from. Defaults to the current directory | | `--limit ` | Limit results. Defaults to 100 | | `--offset ` | Result offset. Defaults to 0 | ### Examples ```bash motherduck flight list-runs # the current directory's motherduck flight list-runs my_flight --limit 5 motherduck flight list-runs --flight ``` To watch a run from a script, poll this command with `-o json` and read the status field rather than parsing the table. ## `flight list` Newest first, by the time each Flight was last updated. `--name` filters the page `--limit` and `--offset` selected, so it can return fewer rows than `--limit`. Raise `--limit` to search deeper. ```bash motherduck flight list [options] ``` ### Options | Option | Description | |---|---| | `--limit ` | Limit results. Defaults to 100 | | `--offset ` | Result offset. Defaults to 0 | | `--name ` | Only Flights whose name contains this text, case insensitive | | `--all` | Include Flights shared with your organization. Defaults to false | ### Examples ```bash motherduck flight list motherduck flight list --name nightly # names containing "nightly" motherduck flight list --name nightly --limit 500 motherduck flight list --all # the organization's too ``` ## `flight list-versions` Lists a Flight's versions in MotherDuck, one per push, newest first. Fetch one with [`flight pull --version `](#flight-pull). ```bash motherduck flight list-versions [options] [dir] ``` ### Arguments | Argument | Description | |---|---| | `dir` | Flight directory to read the Flight ID from. Defaults to the current directory | ### Options | Option | Description | |---|---| | `--flight ` | Flight ID or app URL | | `--dir ` | Flight directory to read the Flight ID from. Defaults to the current directory | | `--limit ` | Limit results. Defaults to 100 | | `--offset ` | Result offset. Defaults to 0 | ### Examples ```bash motherduck flight list-versions # the current directory's motherduck flight list-versions my_flight motherduck flight list-versions --flight --limit 5 ``` ## `flight create-secret` Stores a flight secret in MotherDuck, from `KEY=VALUE` pairs or a dotenv file. A Flight reads its fields as environment variables once it's attached with [`flight push --secret-names`](#flight-push). Values are never printed back. ```bash motherduck flight create-secret [options] [pairs...] ``` ### Arguments | Argument | Description | |---|---| | `name` | Name of the secret. This is what `--secret-names` takes | | `pairs...` | Inline `KEY=VALUE` fields. Omit when using `--secrets-file` | ### Options | Option | Description | |---|---| | `--secrets-file ` | Read fields from a dotenv-format file instead of inline `KEY=VALUE` pairs. Double-quote any value containing `#` or leading or trailing whitespace | | `--if-exists ` | What to do when the name is taken: `ignore`, `error`, or `replace`. Defaults to `error` | ### Examples ```bash motherduck flight create-secret my_api_creds api_key=key123 motherduck flight create-secret my_api_creds --secrets-file ./secrets.env motherduck flight create-secret my_api_creds --if-exists replace api_key=key456 motherduck flight create-secret my_api_creds --if-exists ignore api_key=key123 motherduck flight push my_flight --secret-names my_api_creds # attach it ``` :::warning Inline values are visible in your shell history and to other processes on the machine. `--secrets-file` keeps them out of the command line. ::: ## `flight list-secrets` Lists the flight secrets stored in MotherDuck: their names and shape, never their values. These are the names `--secret-names` takes. ```bash motherduck flight list-secrets [options] ``` ### Examples ```bash motherduck flight list-secrets motherduck flight list-secrets -o json ``` ## `flight delete-secret` Removes a flight secret from MotherDuck. Any Flight that still names it fails on its next run, so check [`flight list`](#flight-list) first if you're unsure. ```bash motherduck flight delete-secret [options] ``` ### Arguments | Argument | Description | |---|---| | `name` | Name of the secret to remove | ### Options | Option | Description | |---|---| | `--if-not-exists ` | What to do when the secret isn't there: `ignore` or `error`. Defaults to `error` | | `--dangerously-skip-confirmation` | Delete without interactive confirmation | ### Examples ```bash motherduck flight delete-secret my_api_creds motherduck flight delete-secret my_api_creds --if-not-exists ignore motherduck flight delete-secret my_api_creds --dangerously-skip-confirmation ``` ## `flight delete` Deletes a Flight from MotherDuck, along with its versions, schedule, and run history. This can't be undone. The local files stay where they are. ```bash motherduck flight delete [options] ``` ### Options | Option | Description | |---|---| | `--flight ` | Flight ID or app URL. Required | | `--dangerously-skip-confirmation` | Delete without interactive confirmation | ### Examples ```bash motherduck flight delete --flight motherduck flight delete --flight --dangerously-skip-confirmation ``` :::warning Pass `--dangerously-skip-confirmation` only in scripts where you've already confirmed the ID. ::: ## Related - [Flights](/key-tasks/flights/) - [Scheduling and runs](/key-tasks/flights/scheduling-and-runs/) - [Flight authentication, config, and secrets](/key-tasks/flights/flights-authentication-config-and-secrets/) - [`dive`](./dive.md) --- Source: https://motherduck.com/docs/sql-reference/motherduck-cli/upgrade # upgrade > Reference for motherduck upgrade, which replaces the installed CLI binary with the latest release. Upgrade the `motherduck` CLI. This replaces the binary on your `PATH` with the latest release. On a CLI that's already current, it says so rather than downloading again. ## Usage ```bash motherduck upgrade ``` `upgrade` has no formatted output, so it doesn't take `-o, --output`. ## Examples ```bash motherduck upgrade motherduck --version ``` ## Related - [Install and upgrade](/getting-started/interfaces/motherduck-cli/install/) --- ## 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=MotherDuck%20Documentation%20-%20MotherDuck%20CLI&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.