# guide
> Reference for the motherduck guide command group, including local files, versions, references, and access.
Create and manage Guides, Markdown documents that record conventions,
definitions, and context for people and agents working with your data.

## Usage

```bash
motherduck guide <command> [options]
```

## Commands

| Command | Description |
|---|---|
| [`init`](#guide-init) | Initialize one Guide in a local directory |
| [`list`](#guide-list) | List Guides you own or can access |
| [`pull`](#guide-pull) | Pull one Guide into a local directory |
| [`push`](#guide-push) | Create or update one Guide from local files |
| [`list-versions`](#guide-list-versions) | List the versions of a Guide |
| [`delete`](#guide-delete) | Soft-delete a Guide |

Every command also takes the [global options](./index.md#global-options).

## Guide directory

```text
revenue-guide/
├── guide.md             # Markdown body
└── guide.metadata.json  # Title, topic, access, references, version, and ID
```

`guide.metadata.json` has this shape:

```json
{
  "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.

```json
[
  {
    "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:

```bash
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`.

```bash
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

```bash
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.

```bash
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

```bash
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.

```bash
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

```bash
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.

```bash
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

```bash
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>`](#guide-pull).

```bash
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

```bash
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.

```bash
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

```bash
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`](./dive.md)
- [`flight`](./flight.md)
- [Work with AI agents](/getting-started/interfaces/motherduck-cli/agents/)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fmotherduck-cli%2Fguide%2F&page_title=guide&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.