# 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) --- ## 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%2Fflight%2F&page_title=flight&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.