guide
Create and manage Guides, Markdown documents that record conventions, definitions, and context for people and agents working with your data.
Usage
motherduck guide <command> [options]
Commands
| Command | Description |
|---|---|
init | Initialize one Guide in a local directory |
list | List Guides you own or can access |
pull | Pull one Guide into a local directory |
push | Create or update one Guide from local files |
list-versions | List the versions of a Guide |
delete | Soft-delete a Guide |
Every command also takes the global options.
Guide directory
revenue-guide/
├── guide.md # Markdown body
└── guide.metadata.json # Title, topic, access, references, version, and ID
guide.metadata.json has this shape:
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"title": "Revenue definitions",
"topic": "core/metrics",
"description": "Definitions for recurring revenue metrics",
"version": 3,
"access": "user",
"references": []
}
The id and version fields are absent before the first push.
Topics, access, and references
A topic is a lowercase, slash-separated grouping label. A Guide without a topic
is a root Guide. The reserved dives and flights topics, including their
nested topics, add relevant Guides to motherduck dive guide and
motherduck flight guide.
Access is one of:
| Value | Visibility |
|---|---|
user | Visible only to the Guide owner. This is the default |
organization | Visible to the current organization. Requires permission |
References connect a Guide to the assets it documents. --references takes a
JSON array for init and push, while guide list --reference takes one reference
object.
[
{
"type": "catalog",
"url": "md:analytics",
"schema": "main",
"table": "orders"
},
{
"type": "guide",
"uuid": "123e4567-e89b-12d3-a456-426614174000"
}
]
Supported reference shapes are:
| Asset | Example |
|---|---|
| Database | {"type":"catalog","url":"md:analytics"} |
| Table | {"type":"catalog","url":"md:analytics","schema":"main","table":"orders"} |
| Column | {"type":"catalog","url":"md:analytics","schema":"main","table":"orders","column":"customer_id"} |
| View | {"type":"catalog","url":"md:analytics","schema":"main","view":"active_orders"} |
| Macro | {"type":"catalog","url":"md:analytics","schema":"main","macro":"net_revenue"} |
| Guide | {"type":"guide","uuid":"<guide_uuid>"} |
| Dive | {"type":"dive","uuid":"<dive_uuid>"} |
| Flight | {"type":"flight","uuid":"<flight_uuid>"} |
Use a Share's fully qualified md:_share/... URL rather than its local alias.
Find database and Share URLs with:
motherduck query "SELECT alias, fully_qualified_name FROM MD_ALL_DATABASES()"
Every reference can also include a description.
guide init
Creates a local directory containing guide.md and guide.metadata.json.
It doesn't create the remote Guide until you run guide push.
motherduck guide init [options] [dir]
Arguments
| Argument | Description |
|---|---|
dir | Directory to create the Guide in. Defaults to the Guide title |
Options
| Option | Description |
|---|---|
--title <string> | Guide title. Required |
--topic <topic> | Slash-separated grouping label. Omit for a root Guide |
--description <string> | Short summary shown in Guide listings |
--access <access> | user or organization. Defaults to user |
--references <json> | JSON array of referenced assets |
--dir <path> | Directory to create the Guide in |
Examples
motherduck guide init revenue-guide --title "Revenue definitions"
motherduck guide init --title "Dive style" --topic dives/style
motherduck guide init revenue-guide \
--title "Revenue definitions" \
--access organization \
--references '[{"type":"catalog","url":"md:analytics","schema":"main","table":"orders"}]'
guide list
Lists Guides you own by default. --all includes every Guide visible to you,
with owned Guides first. Topic filtering includes the named topic and its nested
topics.
motherduck guide list [options]
Options
| Option | Description |
|---|---|
--topic <topic> | Limit results to a topic subtree |
--reference <json> | Only Guides that reference this JSON object |
--all | Include every Guide visible to you |
--limit <number> | Limit results. Defaults to 100 |
--offset <number> | Result offset. Defaults to 0 |
Table output prints the next offset when another page is available.
Examples
motherduck guide list
motherduck guide list --all
motherduck guide list --topic core/metrics
motherduck guide list \
--reference '{"type":"catalog","url":"md:analytics","schema":"main","table":"orders"}'
guide pull
Pulls one Guide when you pass its UUID or app URL, or when the destination has a
guide.metadata.json file with an ID. It overwrites guide.md and
guide.metadata.json with the remote version and returns the Guide's app URL.
motherduck guide pull [options] [id-or-url]
Arguments
| Argument | Description |
|---|---|
id-or-url | Guide UUID or app URL. Defaults to the ID from guide.metadata.json |
Options
| Option | Description |
|---|---|
--dir <path> | Directory to pull into. Defaults to the current directory |
--version <n> | Pull a specific version of one Guide. Defaults to the latest |
Examples
motherduck guide pull <guide_uuid> --dir revenue-guide
motherduck guide pull <guide_uuid> --version 2
Pull always replaces local Guide content. Push or copy local edits before pulling if you need to preserve them.
guide push
Creates a Guide when its metadata has no ID and updates it otherwise. If the
content hasn't changed, push reconciles metadata and access without creating a
version. Pass --force to append a version anyway. Successful output includes
the Guide's app URL.
motherduck guide push [options] [dir]
Arguments
| Argument | Description |
|---|---|
dir | Directory holding the Guide. Defaults to the current directory |
Options
| Option | Description |
|---|---|
--dir <path> | Directory holding the Guide |
--title <string> | Override the Guide title |
--topic <topic> | Override the topic. Pass an empty value to move to the root |
--description <string> | Override the listing summary. Pass an empty value to clear |
--access <access> | Override access with user or organization |
--references <json> | Replace references with a JSON array. Pass [] to clear |
--version-description <string> | Human-readable summary of the version change |
--external-id <string> | Caller-provided version identifier, such as a Git SHA |
--force | Append a version when content hasn't changed |
Examples
motherduck guide push revenue-guide
motherduck guide push revenue-guide --version-description "Clarify ARR"
guide list-versions
Lists a Guide's versions, newest first. Fetch one with
guide pull --version <n>.
motherduck guide list-versions [options] <guide>
Arguments
| Argument | Description |
|---|---|
guide | Guide UUID or app URL |
Options
| Option | Description |
|---|---|
--limit <number> | Limit results. Defaults to 100 |
--offset <number> | Result offset. Defaults to 0 |
Examples
motherduck guide list-versions <guide_uuid>
motherduck guide list-versions <guide_url> --limit 5
guide delete
Soft-deletes a Guide while preserving its version history. The command doesn't remove local files.
motherduck guide delete [options] <guide>
Arguments
| Argument | Description |
|---|---|
guide | Guide UUID or app URL |
Options
| Option | Description |
|---|---|
--dangerously-skip-confirmation | Delete without interactive confirmation |
Examples
motherduck guide delete <guide_uuid>
motherduck guide delete <guide_url> --dangerously-skip-confirmation
Pass --dangerously-skip-confirmation only in scripts where you've already
confirmed the Guide.