flight
Create and manage 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
motherduck flight <command> [options]
Commands
| Command | Description |
|---|---|
guide | Print the Flight authoring guide |
init | Initialize a new Flight in a local directory |
push | Push a local Flight to MotherDuck |
pull | Pull a Flight from MotherDuck into a local directory |
run | Run a Flight once, now |
cancel | Cancel a running Flight run |
logs | Print the logs of a Flight run |
list-runs | List the runs of a Flight |
list | List the Flights owned by the current user, or visible in their organization |
list-versions | List the versions of a Flight in MotherDuck |
create-secret | Create a flight secret |
list-secrets | List your flight secrets |
delete-secret | Delete a flight secret |
delete | Delete a Flight from MotherDuck |
Every command also takes the global options.
Flight directories
A Flight directory holds:
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:
--flight 123e4567-e89b-12d3-a456-426614174000
--flight https://app.motherduck.com/flights/my-flight-123e4567-e89b-12d3-a456-426614174000
A URL ending in /versions/<n> 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.
motherduck flight guide
flight init
Creates a new local Flight directory and writes main.py,
requirements.txt, and flight.metadata.json there.
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 <string> | Flight name. Required |
--dir <path> | Directory to create the Flight in. Defaults to a directory named after --name |
Examples
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.
motherduck flight push [options] [dir]
Arguments
| Argument | Description |
|---|---|
dir | Directory holding the local Flight. Defaults to the current directory |
Options
| Option | Description |
|---|---|
--dir <path> | Directory holding the local Flight. Defaults to the current directory |
--name <string> | Flight name |
--schedule-cron <cron> | Schedule as a 5-field cron expression in UTC, for example "0 9 * * 1-5". Pass "" to unschedule |
--config <json> | Non-secret values exposed to the Flight as environment variables, for example '{"TARGET_DB":"prod"}' |
--access-token-name <string> | MotherDuck access token the Flight runs with |
--secret-names <names> | Comma-separated MotherDuck secret names to expose |
--max-runtime-sec <n> | Per-run timeout in seconds. 0 means no timeout |
--run | Run the Flight once after pushing |
Examples
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.
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 <path> | Directory to pull the Flight into. Defaults to the current directory |
--version <n> | Pull a specific version. Defaults to the one named by the Flight URL, else the latest |
Examples
motherduck flight pull # update the Flight in the current directory
motherduck flight pull <id-or-url> # into the current directory
motherduck flight pull <id-or-url> --dir my_flight
motherduck flight pull <id-or-url> --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 and read its output with
flight logs --run <n>.
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 <id-or-url> | Flight ID or app URL |
--dir <path> | Flight directory to read the Flight ID from. Defaults to the current directory |
--config <json> | Override config values for this run only. Keys must already be defined on the Flight, for example '{"TARGET_DB":"staging"}' |
Examples
motherduck flight run # the current directory's
motherduck flight run my_flight
motherduck flight run --flight <id-or-url>
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.
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 <number> | Run number to cancel. Required |
--flight <id-or-url> | Flight ID or app URL |
--dir <path> | Flight directory to read the Flight ID from. Defaults to the current directory |
Examples
motherduck flight cancel --run 4 # the current directory's
motherduck flight cancel my_flight --run 4
motherduck flight cancel --flight <id-or-url> --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.
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 <number> | Run number. Required |
--flight <id-or-url> | Flight ID or app URL |
--dir <path> | Flight directory to read the Flight ID from. Defaults to the current directory |
Examples
motherduck flight logs --run 4 # the current directory's
motherduck flight logs my_flight --run 4
motherduck flight logs --flight <id-or-url> --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.
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 <id-or-url> | Flight ID or app URL |
--dir <path> | Flight directory to read the Flight ID from. Defaults to the current directory |
--limit <number> | Limit results. Defaults to 100 |
--offset <number> | Result offset. Defaults to 0 |
Examples
motherduck flight list-runs # the current directory's
motherduck flight list-runs my_flight --limit 5
motherduck flight list-runs --flight <id-or-url>
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.
motherduck flight list [options]
Options
| Option | Description |
|---|---|
--limit <number> | Limit results. Defaults to 100 |
--offset <number> | Result offset. Defaults to 0 |
--name <text> | Only Flights whose name contains this text, case insensitive |
--all | Include Flights shared with your organization. Defaults to false |
Examples
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 <n>.
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 <id-or-url> | Flight ID or app URL |
--dir <path> | Flight directory to read the Flight ID from. Defaults to the current directory |
--limit <number> | Limit results. Defaults to 100 |
--offset <number> | Result offset. Defaults to 0 |
Examples
motherduck flight list-versions # the current directory's
motherduck flight list-versions my_flight
motherduck flight list-versions --flight <id-or-url> --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. Values are never printed back.
motherduck flight create-secret [options] <name> [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 <path> | 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 <action> | What to do when the name is taken: ignore, error, or replace. Defaults to error |
Examples
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
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.
motherduck flight list-secrets [options]
Examples
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 first if you're unsure.
motherduck flight delete-secret [options] <name>
Arguments
| Argument | Description |
|---|---|
name | Name of the secret to remove |
Options
| Option | Description |
|---|---|
--if-not-exists <action> | What to do when the secret isn't there: ignore or error. Defaults to error |
--dangerously-skip-confirmation | Delete without interactive confirmation |
Examples
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.
motherduck flight delete [options]
Options
| Option | Description |
|---|---|
--flight <id-or-url> | Flight ID or app URL. Required |
--dangerously-skip-confirmation | Delete without interactive confirmation |
Examples
motherduck flight delete --flight <id-or-url>
motherduck flight delete --flight <id-or-url> --dangerously-skip-confirmation
Pass --dangerously-skip-confirmation only in scripts where you've already
confirmed the ID.