> ## Documentation Index
> Fetch the complete documentation index at: https://ralphy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples

> ralphy example list and pull — import full example projects from ralphy-assets.

`ralphy example` pulls complete reference projects from the [`ralphy-assets`](https://github.com/alecs5am/ralphy-assets) companion repo and lands them under `.ralphy/workspaces/<ws>/projects/<as>/`. Templates give you the shape; examples give you a working project, end-to-end, with assets and logs already populated. Use them for visual regression baselines, agent fine-tuning fodder, or as the starting point for a tweak-it-from-here variant.

## ralphy example list

```bash theme={"dark"}
ralphy example list
ralphy example list --template italian-brainrot
ralphy example list --refresh
```

Returns `{ manifestUpdated, examples: [{ id, template, sizeMB, via, description }] }`. The size column matters — examples can be 80–400 MB depending on render length and whether refs are included.

## ralphy example pull \<example-id>

Downloads the tarball, SHA-256 verifies, extracts into `.ralphy/workspaces/<ws>/projects/<as>/`, and registers the new project in `registry.json`.

```bash theme={"dark"}
ralphy example pull italian-brainrot-001 --as my-test-001
```

The `--as <project-id>` flag is required — you pick the local id. The verb refuses if the destination already exists; pick a different `--as` to retry.

## What lands on disk

An extracted example is a regular project, identical in shape to one you'd create from scratch:

```text theme={"dark"}
.ralphy/workspaces/<ws>/projects/my-test-001/
├── BRIEF.md
├── scenario.json
├── prompts.json
├── asset-manifest.json
├── composition-props.json
├── artifacts/
│   ├── images/
│   ├── videos/
│   ├── voiceover/
│   ├── music/
│   ├── captions/
│   └── refs/
├── render/
│   └── final.mp4
├── logs/
│   ├── generations.jsonl
│   ├── user-prompts.jsonl
│   └── user-assets.jsonl
└── TEMPLATE_ORIGIN.md
```

The `from_example` field on the registry entry records the source, so future `project show` tells you where the project came from.

## Examples vs. templates

|              | Template                                                    | Example                                     |
| ------------ | ----------------------------------------------------------- | ------------------------------------------- |
| What you get | shape only (composition + prompt scaffolding)               | a populated project                         |
| Size         | KB                                                          | MB to hundreds of MB                        |
| Use when     | building a new project in a known format                    | want a known-good render to compare against |
| Mutability   | typed via `template use`                                    | edit freely after `example pull`            |
| Storage      | `templates/` (repo) or `.ralphy/workspaces/<ws>/templates/` | `.ralphy/workspaces/<ws>/projects/<id>/`    |

If you want to start from a known-good render and iterate, pull the example. If you want to start from scratch in a known format, use the template.

## Caching

Tarballs cache under `.ralphy/cache/assets/examples/`. A second pull of the same id (with a different `--as`) reuses the cached download. Wipe with `ralphy assets clean`.

## Related

* [Templates](/cli/templates) — the shape-only counterpart
* [Assets](/cli/assets) — the broader companion-repo flow
* [Project verbs](/cli/project-verbs) — what you do with the extracted project
* [cli/commands/example.ts](https://github.com/alecs5am/ralphy/blob/main/cli/commands/example.ts)