Skip to content

motherduckdb/agent-skills / plugins/motherduck-skills-claude/skills/motherduck-cli

motherduck-cli

Flagged

Use the MotherDuck CLI for terminal queries, authentication, and file-based Dive or Flight workflows.

FileKindSize
SKILL.mdskill md3.5 KB
agents/openai.yamlconfig219 B
references/CLI_PLAYBOOK.mdmarkdown8.5 KB
---
name: motherduck-cli
description: Use the MotherDuck CLI for terminal queries, authentication, and file-based Dive or Flight workflows.
argument-hint: [terminal-task]
license: MIT
---

# 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 `MOTHERDUCK_TOKEN` through the environment and set an absolute, task-specific `MOTHERDUCK_HOME` 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.
- Keep Guides as files with `motherduck guide init|pull|push`; `push` creates or updates and only adds a version when content changes. Record a Git SHA with `--external-id` and the reason with `--version-description`. `pull` overwrites local files, so push or save local edits first.
- Treat `dive push`, `flight push`, `guide 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
4. For queries, use `motherduck query` with the smallest suitable output format.
5. 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.
6. 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
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall