Butterbase Templates
A "template" is a Butterbase app marked visibility: 'public' and listed: true, with a repo snapshot uploaded via butterbase repo push. The clone pipeline replays the source app's schema, RLS, functions, config, and frontend artifact into a new app in the cloner's region; the pushed repo gives the cloner the actual source tree to keep developing.
How the repo snapshot flows (repo push / repo pull / repo status)
The repo snapshot is the source-code half of a template; the clone job replays schema/RLS/functions/config separately. Both halves are pinned via apps.repo_latest_snapshot.
butterbase repo init <app_id> — Bind the current directory to an app. Writes .butterbase/config.json and seeds .butterbaseignore. Run once per project. butterbase clone does this for you on the cloner side.butterbase repo push -m "<msg>" — Publisher uploads. Walks the project tree (respecting .butterbaseignore + .gitignore), hashes files (SHA256), uploads any new blobs via presigned URLs, commits a new immutable snapshot, updates the local pin. Content-addressed — re-pushing an unchanged tree is a no-op upload. This is the only way the source tree gets onto the snapshot. Clone replay does not synthesise it.butterbase repo pull [--force] — Cloner / collaborator downloads. Fetches the remote latest manifest, diffs against the locally pinned snapshot, downloads changed/new files, deletes files that are gone upstream, and bumps the local pin. Refuses if a file was deleted upstream but modified locally — --force overrides. butterbase clone invokes this automatically after the clone job completes, so cloners get a working tree without thinking about it.butterbase repo status — Inspector. Shows files modified vs pinned, untracked locally, and deleted locally. Use before push to confirm what's about to be uploaded; use after pull to confirm a clean tree.butterbase repo log — List all snapshots for the bound app.butterbase repo wipe — Destructive; clear all snapshots. Requires app-id confirmation.
Reading a template's source code: clone it into a scratch directory — butterbase clone <source_app_id> /tmp/peek — and read the resulting tree. There is no separate "browse template source" CLI; snapshots are only materialised by repo pull, which requires the caller to be bound to the app.
Updating a clone with newer template versions: clones don't auto-follow the source — each clone owns its own app and its own snapshot history. butterbase repo pull in the clone fetches the cloner's own latest, not the upstream publisher's. To track upstream changes, the cloner has to clone again into a sibling directory and merge with git, or the publisher has to push to a snapshot the clone can read (uncommon).
What clone replay DOES and DOES NOT copy
| Copied on clone |
Not copied — cloner must do |
| Schema (DDL) |
App user data (unless explicitly seeded) |
| RLS policies |
Auth provider OAuth secrets |
| Functions (handlers + non-secret env) |
Function secrets / API keys (cloner provides via preflight) |
| App config |
Agents (record in agents table) — bundle as agents/*.json in the repo and re-import after clone |
| Frontend artifact (with app-id rewritten) |
Storage objects (only the bucket config replays) |
| Repo snapshot (files) |
OAuth integration installs |
This makes the README in the pushed repo the most important publishing artifact — it has to explain everything that doesn't replay.
When to use
- Publishing an app you built as a public template.
- Listing or searching templates.
- Cloning a template (or guiding a user through clone with env-var preflight).
- Toggling visibility / listed status on an existing app.
Publishing checklist
Before flipping visibility: public, verify all of the following. Each one prevents a class of broken-on-clone bugs.
Repo snapshot exists and is fresh. Run butterbase repo push -m "publish v1" from the project root. Confirm apps.repo_latest_snapshot is non-null via manage_app action: get. The clone preflight endpoint returns has_repo: false if missing, and discovery hides templates without a repo for several sort modes.
README.md at repo root with clone instructions. No formal "template instructions" field exists — the README in the pushed snapshot is the instructions. It MUST cover:
- One-line pitch (what does this app do?)
- Required env vars per function — the preflight surfaces keys but not what they're for. List each (e.g.,
STRIPE_SECRET_KEY — server-side Stripe secret).
- Auth setup — OAuth provider IDs/secrets the cloner must register (OAuth secrets do not replay).
- Agent re-import — if the app uses agents, the spec files (
agents/*.json) ride along in the repo, but the agents DB rows don't. Document: butterbase agents create -f agents/<name>.json.
- MCP server registration — if agents reference MCP servers, document each server's URL/transport/auth-header so the cloner can register them post-clone.
- Seed data steps — if the app needs minimum rows (e.g., a default category), provide a seed script or document
manage_schema / select_rows calls.
- First-run smoke — concrete command(s) to verify the clone works.
Env-var conventions for auto-mint. If a function reads butterbase_api_key, the clone preflight auto-mints a scoped key for the cloner. Use this convention name exactly so the clone modal can fill it without asking.
No secrets in committed files. .butterbaseignore covers the obvious cases (.env, secrets/). Verify with butterbase repo push --dry-run and scan the file list.
Visibility flip. Only after 1–4: butterbase visibility public --listed (or manage_app action: update_visibility with {visibility: 'public', listed: true}).
Procedure: publishing
Confirm intent. "Publish '<app_name>' (id=<app_id>) as a public, listed template? This makes the app discoverable, exposes the repo snapshot, and lets anyone fork it. (yes / unlisted-public / no)".
Author README. If README.md does not exist or is shorter than ~30 lines, write one using the checklist above. Show it to the user for approval before pushing.
Bundle agent specs if applicable. Confirm agents/*.json files exist and are tracked. If the app has agents but no spec files, export each via butterbase agents get <name> (the wrapped agents skill helps) and write them to agents/.
Dry-run the push. butterbase repo push --dry-run. Review the file list with the user — especially flag any path that looks like a secret.
Push. butterbase repo push -m "publish v1". Confirm the snapshot ID printed.
Flip visibility. butterbase visibility public --listed (or unlisted if step 1 chose "unlisted-public"; unlisted public apps are still cloneable by anyone with the app_id but don't show in discovery).
Verify discovery. Hit GET /v1/templates?q=<app_name> (or butterbase templates --q <name>) and confirm the app shows with the right schema_summary (table_count, function_count) and has_repo: true.
Clone-test it yourself. butterbase clone <app_id> /tmp/clone-test-$(date +%s) and walk the README. Anything ambiguous or missing in the README → fix in the source repo, butterbase repo push again (snapshots are content-addressed, so unchanged files don't re-upload).
Procedure: cloning
Preflight. GET /v1/templates/<source_app_id>/clone-preflight (or the clone_app MCP tool with dry_run: true if available). Returns per-function env var keys grouped by convention (auto_mint_eligible for butterbase_api_key).
Collect env vars. For each non-auto-mintable key, ask the user for the value. For auto-mintable keys, default to "yes, mint a fresh bb_sk_*".
Start clone. clone_app (MCP) or butterbase clone <source_app_id> (CLI). Pass env_var_values and auto_mint_api_key.
Poll the job. Stage progression: pending → processing → replaying_schema → replaying_rls → seeding_data → replaying_functions → replaying_config → copying_repo → completed. If it transitions to failed, surface the error_message; the user can retry_clone(job_id).
Post-clone. Read the cloned app's README.md (it came down with the repo snapshot). Walk the post-clone steps: OAuth registration, agent re-import (butterbase agents create -f agents/*.json), MCP server registration, seed data.
First-run smoke. Run the README's "first-run smoke" commands.
CLI reference
| Command |
Purpose |
butterbase repo init <app_id> |
Bind the current directory to an app. Seeds .butterbase/config.json + .butterbaseignore. |
butterbase repo push [-m msg] [--dry-run] |
Walk files, hash, upload missing blobs, commit snapshot, update apps.repo_latest_snapshot. |
butterbase repo pull [--force] |
Download the bound app's latest snapshot, diff vs local pin, apply downloads + deletes, bump pin. Refuses on local-edit vs upstream-delete conflict without --force. Auto-invoked by butterbase clone. |
butterbase repo status |
Show files modified vs pinned, untracked, and locally deleted. Use before push and after pull. |
butterbase repo log |
List snapshots for the bound app. |
butterbase repo wipe |
Destructive — clear all snapshots. Requires app-id confirmation. |
| `butterbase visibility public [--listed |
--unlisted]` |
butterbase visibility private |
Unpublish. Auto-unlists. |
butterbase templates [--q <text>] [--sort recent|popular] |
Browse the gallery. |
butterbase clone <source_app_id> [target_dir] |
Clone a template into the user's account, replaying source and pulling the repo to target_dir. |
Anti-patterns
- ❌ Flipping
visibility: public before butterbase repo push. Cloners get an empty file tree.
- ❌ Skipping the README. The clone preflight tells the cloner which env vars to set, not what they're for; without a README, they're guessing.
- ❌ Assuming agents come with the clone. They don't — bundle
agents/*.json and document re-import.
- ❌ Storing OAuth secrets or function API keys in repo files. They'll be uploaded into every clone's filesystem. Use
.butterbaseignore and document the env-var keys instead.
- ❌ Publishing without a self-clone test. Always
butterbase clone your own template into a scratch dir and walk the README before announcing.
- ❌ Confusing
--unlisted public with private. Unlisted-public apps are still forkable by anyone who knows the app_id (useful for "share a link with a friend" but not for personal apps).
1---2name: templates3description: Use when publishing a Butterbase app as a public template (visibility + listed + repo snapshot), browsing the template gallery, or cloning a template with environment-variable preflight. Templates are public apps with a pushed repo snapshot that other users can fork into their own region.4---5
6# Butterbase Templates
7
8A "template" is a Butterbase app marked `visibility: 'public'` and `listed: true`, **with a repo snapshot uploaded via `butterbase repo push`**. The clone pipeline replays the source app's schema, RLS, functions, config, and frontend artifact into a new app in the cloner's region; the pushed repo gives the cloner the actual source tree to keep developing.
9
10## How the repo snapshot flows (`repo push` / `repo pull` / `repo status`)
11
12The repo snapshot is the **source-code half** of a template; the clone job replays schema/RLS/functions/config separately. Both halves are pinned via `apps.repo_latest_snapshot`.
13
14- **`butterbase repo init <app_id>`** — Bind the current directory to an app. Writes `.butterbase/config.json` and seeds `.butterbaseignore`. Run once per project. `butterbase clone` does this for you on the cloner side.
15- **`butterbase repo push -m "<msg>"`** — Publisher uploads. Walks the project tree (respecting `.butterbaseignore` + `.gitignore`), hashes files (SHA256), uploads any new blobs via presigned URLs, commits a new immutable snapshot, updates the local pin. Content-addressed — re-pushing an unchanged tree is a no-op upload. **This is the only way the source tree gets onto the snapshot.** Clone replay does not synthesise it.
16- **`butterbase repo pull [--force]`** — Cloner / collaborator downloads. Fetches the remote latest manifest, diffs against the locally pinned snapshot, downloads changed/new files, deletes files that are gone upstream, and bumps the local pin. Refuses if a file was deleted upstream but modified locally — `--force` overrides. `butterbase clone` invokes this **automatically** after the clone job completes, so cloners get a working tree without thinking about it.
17- **`butterbase repo status`** — Inspector. Shows files modified vs pinned, untracked locally, and deleted locally. Use before `push` to confirm what's about to be uploaded; use after `pull` to confirm a clean tree.
18- **`butterbase repo log`** — List all snapshots for the bound app.
19- **`butterbase repo wipe`** — Destructive; clear all snapshots. Requires app-id confirmation.
20
21**Reading a template's source code:** clone it into a scratch directory — `butterbase clone <source_app_id> /tmp/peek` — and read the resulting tree. There is no separate "browse template source" CLI; snapshots are only materialised by `repo pull`, which requires the caller to be bound to the app.
22
23**Updating a clone with newer template versions:** clones don't auto-follow the source — each clone owns its own app and its own snapshot history. `butterbase repo pull` in the clone fetches the cloner's *own* latest, not the upstream publisher's. To track upstream changes, the cloner has to clone again into a sibling directory and merge with git, or the publisher has to push to a snapshot the clone can read (uncommon).
24
25## What clone replay DOES and DOES NOT copy
26
27| Copied on clone | Not copied — cloner must do |
28|---|---|
29| Schema (DDL) | App user data (unless explicitly seeded) |
30| RLS policies | Auth provider OAuth secrets |
31| Functions (handlers + non-secret env) | Function secrets / API keys (cloner provides via preflight) |
32| App config | **Agents** (record in `agents` table) — bundle as `agents/*.json` in the repo and re-import after clone |
33| Frontend artifact (with app-id rewritten) | **Storage objects** (only the bucket config replays) |
34| Repo snapshot (files) | OAuth integration installs |
35
36This makes the **README in the pushed repo** the most important publishing artifact — it has to explain everything that doesn't replay.
37
38## When to use
39
40- Publishing an app you built as a public template.
41- Listing or searching templates.
42- Cloning a template (or guiding a user through clone with env-var preflight).
43- Toggling visibility / listed status on an existing app.
44
45## Publishing checklist
46
47Before flipping `visibility: public`, verify all of the following. Each one prevents a class of broken-on-clone bugs.
48
491. **Repo snapshot exists and is fresh.** Run `butterbase repo push -m "publish v1"` from the project root. Confirm `apps.repo_latest_snapshot` is non-null via `manage_app action: get`. The clone preflight endpoint returns `has_repo: false` if missing, and discovery hides templates without a repo for several sort modes.
50
512. **README.md at repo root with clone instructions.** No formal "template instructions" field exists — the README in the pushed snapshot **is** the instructions. It MUST cover:
52 - **One-line pitch** (what does this app do?)
53 - **Required env vars per function** — the preflight surfaces keys but not what they're for. List each (e.g., `STRIPE_SECRET_KEY — server-side Stripe secret`).
54 - **Auth setup** — OAuth provider IDs/secrets the cloner must register (OAuth secrets do not replay).
55 - **Agent re-import** — if the app uses agents, the spec files (`agents/*.json`) ride along in the repo, but the `agents` DB rows don't. Document: `butterbase agents create -f agents/<name>.json`.
56 - **MCP server registration** — if agents reference MCP servers, document each server's URL/transport/auth-header so the cloner can register them post-clone.
57 - **Seed data steps** — if the app needs minimum rows (e.g., a default category), provide a seed script or document `manage_schema` / `select_rows` calls.
58 - **First-run smoke** — concrete command(s) to verify the clone works.
59
603. **Env-var conventions for auto-mint.** If a function reads `butterbase_api_key`, the clone preflight auto-mints a scoped key for the cloner. Use this convention name exactly so the clone modal can fill it without asking.
61
624. **No secrets in committed files.** `.butterbaseignore` covers the obvious cases (`.env`, `secrets/`). Verify with `butterbase repo push --dry-run` and scan the file list.
63
645. **Visibility flip.** Only after 1–4: `butterbase visibility public --listed` (or `manage_app action: update_visibility` with `{visibility: 'public', listed: true}`).
65
66## Procedure: publishing
67
681. **Confirm intent.** `"Publish '<app_name>' (id=<app_id>) as a public, listed template? This makes the app discoverable, exposes the repo snapshot, and lets anyone fork it. (yes / unlisted-public / no)"`.
69
702. **Author README.** If `README.md` does not exist or is shorter than ~30 lines, write one using the checklist above. Show it to the user for approval before pushing.
71
723. **Bundle agent specs** if applicable. Confirm `agents/*.json` files exist and are tracked. If the app has agents but no spec files, export each via `butterbase agents get <name>` (the wrapped agents skill helps) and write them to `agents/`.
73
744. **Dry-run the push.** `butterbase repo push --dry-run`. Review the file list with the user — especially flag any path that looks like a secret.
75
765. **Push.** `butterbase repo push -m "publish v1"`. Confirm the snapshot ID printed.
77
786. **Flip visibility.** `butterbase visibility public --listed` (or `unlisted` if step 1 chose "unlisted-public"; unlisted public apps are still cloneable by anyone with the app_id but don't show in discovery).
79
807. **Verify discovery.** Hit `GET /v1/templates?q=<app_name>` (or `butterbase templates --q <name>`) and confirm the app shows with the right `schema_summary` (table_count, function_count) and `has_repo: true`.
81
828. **Clone-test it yourself.** `butterbase clone <app_id> /tmp/clone-test-$(date +%s)` and walk the README. Anything ambiguous or missing in the README → fix in the source repo, `butterbase repo push` again (snapshots are content-addressed, so unchanged files don't re-upload).
83
84## Procedure: cloning
85
861. **Preflight.** `GET /v1/templates/<source_app_id>/clone-preflight` (or the `clone_app` MCP tool with `dry_run: true` if available). Returns per-function env var keys grouped by convention (`auto_mint_eligible` for `butterbase_api_key`).
87
882. **Collect env vars.** For each non-auto-mintable key, ask the user for the value. For auto-mintable keys, default to "yes, mint a fresh `bb_sk_*`".
89
903. **Start clone.** `clone_app` (MCP) or `butterbase clone <source_app_id>` (CLI). Pass `env_var_values` and `auto_mint_api_key`.
91
924. **Poll the job.** Stage progression: `pending → processing → replaying_schema → replaying_rls → seeding_data → replaying_functions → replaying_config → copying_repo → completed`. If it transitions to `failed`, surface the `error_message`; the user can `retry_clone(job_id)`.
93
945. **Post-clone.** Read the cloned app's README.md (it came down with the repo snapshot). Walk the post-clone steps: OAuth registration, agent re-import (`butterbase agents create -f agents/*.json`), MCP server registration, seed data.
95
966. **First-run smoke.** Run the README's "first-run smoke" commands.
97
98## CLI reference
99
100| Command | Purpose |
101|---|---|
102| `butterbase repo init <app_id>` | Bind the current directory to an app. Seeds `.butterbase/config.json` + `.butterbaseignore`. |
103| `butterbase repo push [-m msg] [--dry-run]` | Walk files, hash, upload missing blobs, commit snapshot, update `apps.repo_latest_snapshot`. |
104| `butterbase repo pull [--force]` | Download the bound app's latest snapshot, diff vs local pin, apply downloads + deletes, bump pin. Refuses on local-edit vs upstream-delete conflict without `--force`. Auto-invoked by `butterbase clone`. |
105| `butterbase repo status` | Show files modified vs pinned, untracked, and locally deleted. Use before `push` and after `pull`. |
106| `butterbase repo log` | List snapshots for the bound app. |
107| `butterbase repo wipe` | Destructive — clear all snapshots. Requires app-id confirmation. |
108| `butterbase visibility public [--listed | --unlisted]` | Mark public + optionally list in gallery. |
109| `butterbase visibility private` | Unpublish. Auto-unlists. |
110| `butterbase templates [--q <text>] [--sort recent\|popular]` | Browse the gallery. |
111| `butterbase clone <source_app_id> [target_dir]` | Clone a template into the user's account, replaying source and pulling the repo to `target_dir`. |
112
113## Anti-patterns
114
115- ❌ Flipping `visibility: public` before `butterbase repo push`. Cloners get an empty file tree.
116- ❌ Skipping the README. The clone preflight tells the cloner *which* env vars to set, not *what they're for*; without a README, they're guessing.
117- ❌ Assuming agents come with the clone. They don't — bundle `agents/*.json` and document re-import.
118- ❌ Storing OAuth secrets or function API keys in repo files. They'll be uploaded into every clone's filesystem. Use `.butterbaseignore` and document the env-var keys instead.
119- ❌ Publishing without a self-clone test. Always `butterbase clone` your own template into a scratch dir and walk the README before announcing.
120- ❌ Confusing `--unlisted` public with `private`. Unlisted-public apps are still forkable by anyone who knows the `app_id` (useful for "share a link with a friend" but not for personal apps).
butterbase-ai