Use the MotherDuck CLI

Source Of Truth

• Prefer the current MotherDuck CLI documentation and command reference. Read command help before relying on remembered flags because the command surface can evolve.
• Before authoring or editing a Dive or Flight, run motherduck dive guide or motherduck flight guide. Those built-in guides are the current runtime contract.
• Use motherduck <command> --help after a parsing or option error instead of guessing at syntax.

Default Posture

• Reuse an authenticated CLI when available; check with motherduck status before starting a login flow.
• For automation, pass MOTHERDUCKTOKEN through the environment and set an absolute, task-specific MOTHERDUCKHOME so parallel agents do not share credentials or assets.
• Request --output json for machine-readable resource operations and check both the exit code and returned success field. motherduck query --output json returns a bare JSON array instead.
• Redirect large query results to a file rather than pulling every row into model context.
• Never run motherduck new merely because authentication is missing. Account creation requires an explicit signup request.
• Treat dive push, flight push, scheduling, secret changes, and account creation as external mutations. Perform them only when the user's build/change request includes that outcome.

Workflow

1. Inspect the host project and existing CLI/authentication state.
2. Install or upgrade only when needed, following the current platform-specific docs.
3. Choose CLI or MCP based on the task shape:

- files, local edits, CI, large results, or repeated iterations: CLI - chat-only exploration, inline answers, or no filesystem: MCP - mixed workflow: explore through MCP, then build from local files through the CLI

1. For queries, use motherduck query with the smallest suitable output format.
2. For a Dive or Flight, read its built-in guide, pull or initialize the local project, edit files, validate or preview, then push only when publication is requested.
3. Capture the resource ID, URL, or run number from JSON output and verify the remote state after mutation.

For answer, review, or planning requests, recommend commands without logging in, creating an account, or changing remote resources. For explicit build/change requests, complete the in-scope CLI workflow and validate its result; ask before destructive deletes or materially broader external changes.

References

Read only the reference sections needed for the current task.

• Read references/CLI_PLAYBOOK.md for installation, authentication, JSON contracts, query patterns, agent isolation, and complete Dive/Flight file workflows.

Related Skills

Load related skills only for missing capabilities; reuse established context.

• motherduck-connect for choosing the underlying application connection path
• motherduck-explore and motherduck-query for catalog discovery and SQL behavior
• motherduck-create-dive and motherduck-create-flight for the product-specific authoring workflow