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

warning

Pass --dangerously-skip-confirmation only in scripts where you've already confirmed the Guide.

Related

• dive
• flight
• Work with AI agents