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

references/CLI_PLAYBOOK.md

View on GitHub
# MotherDuck CLI Playbook

Reference for terminal-based MotherDuck work. Command flags can evolve; use current docs and `--help` as the runtime source of truth.

## Contents

| Section | Covers |
| --- | --- |
| CLI or MCP | Interface choice by task shape |
| Install and Upgrade | Platform-aware setup and current-version checks |
| Authentication and Isolation | Browser login, token automation, `MOTHERDUCK_HOME` |
| Output Contracts | JSON, CSV, exit codes, and filtering |
| Query Workflow | Read-only and write-query posture |
| Dive Workflow | Guide, init/pull, watch, push |
| Flight Workflow | Guide, init/pull, test, push, run, logs |
| Automation Safety | Mutations, secrets, signup, and cleanup |
| Troubleshooting | Common symptoms and next checks |

## CLI or MCP

Choose the interface independently from the SQL or product workflow.

| Task shape | Default |
| --- | --- |
| Coding agent with shell and filesystem | CLI |
| Dive or Flight source edited across iterations | CLI |
| CI job or shell automation | CLI |
| Large query result written to a file | CLI |
| Chat client without shell access | MCP |
| Inline catalog exploration or rendered Dive | MCP |
| Explore interactively, then implement in a repo | MCP for discovery, CLI for files and publication |

The CLI keeps source and large results out of model context. MCP exposes structured tools and inline resources. Do not force one interface across every phase.

## Install and Upgrade

Follow the current CLI install page. On macOS or Linux, the documented installer can install only the MotherDuck CLI:

```bash
curl -s https://install.motherduck.com | SKIP_DUCKDB_CLI=1 sh
```

Use the documented PowerShell installer on Windows. Do not translate the POSIX command mechanically.

```powershell
powershell -c "$env:SKIP_DUCKDB_CLI=1; irm https://install.motherduck.com | iex"
```

After installation:

```bash
motherduck status
motherduck upgrade
```

Run `upgrade` only when the user asks to upgrade or a current command reports an incompatible version. Never pipe an installer into a privileged shell without inspecting the environment and current docs.

## Authentication and Isolation

Interactive login opens a browser:

```bash
motherduck login
motherduck status
```

For CI or an agent runtime, inject a scoped token and isolate state:

```bash
: "${MOTHERDUCK_TOKEN:?inject a scoped MotherDuck token before running automation}"
export MOTHERDUCK_HOME="/absolute/task-specific/path/.motherduck"
motherduck status --output json
```

`MOTHERDUCK_HOME` must be absolute. Use one directory per concurrent job. Never echo the token, write it into CLI project files, or commit the state directory.

`motherduck new` creates an account and organization. Run it only for an explicit signup request; missing credentials alone do not authorize account creation.

## Output Contracts

Resource commands support structured output:

```bash
motherduck dive list --output json
motherduck flight list --output json
```

Successful resource operations return an object containing `success: true` plus a resource-shaped field. Failures return `success: false`, an error, and a non-zero process exit.

`motherduck query --output json` is different: it returns a bare JSON array. Use CSV for large tabular output:

```bash
motherduck query "SELECT * FROM sample_data.nyc.taxi LIMIT 1000" --output csv > result.csv
```

Filter JSON before reading it into context:

```bash
motherduck dive list --output json | jq -r '.dives[] | [.id, .title, .status] | @tsv'
```

## Query Workflow

Use DuckDB SQL even though the command is a thin terminal interface.

```bash
motherduck query "DESCRIBE sample_data.nyc.taxi" --output json
motherduck query "SELECT count(*) AS rows FROM sample_data.nyc.taxi" --output json
```

Prefer read-only inspection for exploratory work. A user request to query or inspect does not authorize DDL/DML. When a write is requested, make the target explicit and verify it afterward with a separate read.

## Dive Workflow

Read the current guide before writing code:

```bash
motherduck dive guide
```

Create or pull a local Dive:

```bash
motherduck dive init taxi_trips --title "Taxi trips"
DIVE_ID_OR_NAME="taxi_trips"
motherduck dive pull "$DIVE_ID_OR_NAME"
```

Edit the generated source with the normal repository workflow, then preview without stealing focus and capture machine-readable events:

```bash
motherduck dive watch taxi_trips --no-open --log-file preview.ndjson
```

Inspect compile and query events in the log. Publish only when requested:

```bash
motherduck dive push taxi_trips --output json
```

Read back the returned ID, URL, version, and status. A new Dive is Draft; promote it to Ready only after content, query, and viewport validation. Do not self-endorse it.

## Flight Workflow

Read the current guide first:

```bash
motherduck flight guide
```

Initialize or pull source, then keep Python and requirements in local files:

```bash
motherduck flight init --name nightly_load nightly_load
FLIGHT_ID_OR_NAME="nightly_load"
motherduck flight pull "$FLIGHT_ID_OR_NAME" --dir nightly_load
```

Use `motherduck flight --help` for the current local validation command and push flags. Create the remote Flight without a schedule, trigger one run, and capture its number:

```bash
motherduck flight push nightly_load --output json
motherduck flight run nightly_load --output json
```

Cancel a pending or running run with `motherduck flight cancel` (owner or organization Admin); see `motherduck flight cancel --help` for its arguments.

Poll only the relevant run through the current exact-run command when available; otherwise list one newest run. On failure, read the bounded log tail:

```bash
motherduck flight list-runs nightly_load --limit 1 --output json
RUN_NUMBER="1"
motherduck flight logs nightly_load --run "$RUN_NUMBER" | tail -100
```

Attach a schedule only after a successful on-demand run and only when scheduling was requested. Use the CLI secret commands for secret metadata, but never place secret values in shell history or logs.

## Guide Workflow

Guides live as a folder with `guide.md` and `guide.metadata.json` (title, topic, description, access, references, and, after the first push, id and version):

```bash
motherduck guide list --topic core/metrics --output json
motherduck guide init revenue-guide --title "Revenue definitions" --topic core/metrics
motherduck guide push revenue-guide --version-description "Clarify ARR" --external-id "$(git rev-parse HEAD)"
motherduck guide pull <guide-id-or-url> --dir revenue-guide
motherduck guide list-versions <guide-id-or-url> --limit 5
```

- Nothing exists remotely until `push`. `push` without an id in metadata creates the Guide; with one it updates it. Metadata- or access-only changes do not add a version; `--force` adds one anyway.
- Access defaults to `user`. `organization` needs permission and an explicit request.
- Topics are lowercase and slash-separated. The reserved `dives` and `flights` topics feed `motherduck dive guide` and `motherduck flight guide`.
- References are a JSON array linking the Guide to databases, tables, columns, views, macros, Guides, Dives, or Flights; use the full `md:_share/...` URL for shares.
- `delete` is a soft delete that keeps version history; confirm before running it.

## Automation Safety

- Check the process exit code before parsing output.
- Use `set -euo pipefail` in repeatable shell automation.
- Bound polling and log output; stop on a terminal run state.
- Keep signup, publication, schedules, secrets, and deletes inside the explicit task scope.
- Use task-specific state and output paths; do not repurpose `HOME`.
- Read back remote resources after every mutation.
- Confirm destructive Dive/Flight deletion and explain whether recovery is possible.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Command or flag rejected | Run the command's `--help`; do not rely on remembered syntax |
| `motherduck --version` reports an unexpected command surface | Check `command -v motherduck` and `motherduck --help` for a PATH collision; do not overwrite another installation implicitly |
| Browser login unavailable | Use an approved scoped `MOTHERDUCK_TOKEN`, not a pasted credential |
| Parallel agents affect each other | Give each an absolute, unique `MOTHERDUCK_HOME` |
| JSON parsing fails | Check exit code and whether `query` returned its documented bare array |
| Dive code fails at runtime | Re-read `motherduck dive guide`, then inspect the preview NDJSON |
| Flight run fails | Read the exact run and bounded logs; verify requirements, config, secrets, and runtime limit |
| CLI source differs from remote | Pull or list the remote version before pushing over it |
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