Deploy Tutorial

Deploy a static site to WREN, preview changes before going live, and promote when ready. Takes about 10 minutes.

Prerequisites

  1. 1 A running WREN instance (local Docker or wren.aemwip.com)
  2. 2 The WREN CLI installed: bun install -g @usewren/cli (or run from the repo with bun run cli/index.ts)
  3. 3 An account — sign up via the Admin UI
Configure the CLI. Point it at your server and sign in:
bash
wren config --url https://wren.aemwip.com
wren auth login -e [email protected] -p yourpassword
wren me   # confirm: shows your principal, org, and role

1 Create a simple site

Let’s make a minimal static site to deploy. Create a folder with a few files:

bash
mkdir my-site && cd my-site

cat > index.html <<'EOF'
<!DOCTYPE html>
<html>
<head>
  <title>My WREN Site</title>
  <link rel="stylesheet" href="/assets/style.css">
</head>
<body>
  <h1>Hello from WREN!</h1>
  <p>Deployed with <code>wren deploy</code>.</p>
  <a href="/about.html">About</a>
</body>
</html>
EOF

cat > about.html <<'EOF'
<!DOCTYPE html>
<html>
<head>
  <title>About — My WREN Site</title>
  <link rel="stylesheet" href="/assets/style.css">
</head>
<body>
  <h1>About</h1>
  <p>This site is versioned and served by WREN.</p>
  <a href="/">Home</a>
</body>
</html>
EOF

mkdir -p assets
cat > assets/style.css <<'EOF'
body { font-family: system-ui, sans-serif; max-width: 640px; margin: 2rem auto; padding: 0 1rem; line-height: 1.6; }
h1 { color: #4338ca; }
a { color: #6366f1; }
EOF

You now have index.html, about.html, and assets/style.css.

2 First deploy

Deploy the folder to a WREN tree. The --public flag creates a permission rule so anyone can view the site.

bash
wren deploy . --tree my-site --public

Output:

output
Found 3 files in .
Creating binary collection: my-site-assets
  Uploaded 3 files...
Created public read permission for tree:my-site

Deployed to tree "my-site":  3 uploaded, 0 unchanged, 3 new paths

Preview:  https://wren.aemwip.com/orgs/your-slug/tree/my-site/index.html
What just happened:
  1. A binary collection my-site-assets was created to store your files
  2. Each file was uploaded as a versioned binary document
  3. Each file was assigned to a tree path matching its local path
  4. A principal=* read permission was added so the site is public

3 See it live

Open the URL from the output in your browser. Your site is live — HTML, CSS, and all. Links between pages work because tree paths match your directory structure.

You can also check it from the CLI:

bash
wren tree view my-site
output
  /about.html       [my-site-assets v1]  size: 234
  /assets/style.css [my-site-assets v1]  size: 168
  /index.html       [my-site-assets v1]  size: 265

Every file is at version 1. The tree serves them at their local paths.

4 Make a change

Edit index.html — change the heading:

html
<h1>Hello from WREN! — Updated</h1>
<p>This is version 2 of the site.</p>

Re-deploy. Only the changed file uploads:

bash
wren deploy . --tree my-site
output
Found 3 files in .

Deployed to tree "my-site":  1 uploaded, 2 unchanged, 0 new paths

WREN detected that about.html and style.css haven’t changed (same file size) and skipped them. Only index.html was uploaded as version 2.

5 Deploy as preview

What if you want to test changes before the public sees them? Deploy with a label:

bash
# Make another change
sed -i '' 's/Updated/v3 Preview/' index.html

# Deploy with --label preview
wren deploy . --tree my-site --label preview

The public site is unchanged — visitors still see the current version. You can see the preview by adding ?label=preview to any URL:

bash
# Public site (unchanged):
open https://wren.aemwip.com/orgs/your-slug/tree/my-site/index.html

# Your preview (new version):
open https://wren.aemwip.com/orgs/your-slug/tree/my-site/index.html?label=preview
How labels control visibility: If you created a permission with labelFilter: "published", anonymous visitors would only see the published label. The --public flag on the first deploy didn’t set a labelFilter, so visitors currently see the latest version. To enable preview → publish flow, set a labelFilter on the permission rule via the Admin UI or the API.

6 Promote to published

Happy with the preview? Promote it:

bash
wren promote my-site --from preview
output
Promoting 3 documents in tree "my-site" → label "published" (from "preview")...
Done: 3 documents labeled "published".

Public: https://wren.aemwip.com/orgs/your-slug/tree/my-site/index.html?label=published

The published label now points to the same versions as preview. If your permission has labelFilter: "published", the public site is updated.

You can also promote without a source label — this labels the current (latest) version of every document in the tree:

bash
wren promote my-site   # defaults to --label published

7 Add JSON data alongside your site

WREN isn’t just file hosting. Your site can read structured data from a collection via the API:

bash
# Create a JSON collection for your site's content
wren create pages '{"slug":"home","title":"Welcome","body":"This content is stored in WREN."}'
wren create pages '{"slug":"about","title":"About Us","body":"We are a team building with WREN."}'

# Your site's JavaScript can fetch from the public API:
# GET /api/v1/orgs/your-slug/pages

Now your static site and its content data live in the same system. When you promote, both the HTML files and the JSON content can move to published together.

8 Rollback

Every file upload creates a new version. You can roll back any individual file:

bash
# See version history for a document
wren versions my-site-assets <document-id>

# Roll back to version 1
wren rollback my-site-assets <document-id> 1

# Re-promote to make the rollback live
wren promote my-site

Or roll back the entire site by promoting an older label. If you labeled yesterday’s deploy as v1, just re-promote it:

bash
wren promote my-site --from v1 --label published

9 Cleanup: remove deleted files

If you delete a file locally and redeploy, the old tree path stays by default. Use --clean to remove paths that no longer exist in your local directory:

bash
rm about.html
wren deploy . --tree my-site --clean
output
Found 2 files in .

Deployed to tree "my-site":  0 uploaded, 2 unchanged, 0 new paths, 1 removed

/about.html is removed from the tree. The document still exists in the collection (soft-deleted or just unassigned) — nothing is permanently lost.

What’s next

  • Full WREN tutorial — covers the Admin UI, collections, schemas, labels, permissions, and more
  • API Docs — interactive reference for every endpoint
  • Projects — see live sites deployed on this WREN instance
  • Admin UI — browse your deployed files, manage permissions, and edit content
Quick reference: 
wren deploy ./dist --tree mysite --public       # first deploy
wren deploy ./dist --tree mysite --label preview # preview deploy
wren promote mysite --from preview               # go live
wren promote mysite                              # label current as published
wren deploy ./dist --tree mysite --clean          # remove deleted files
wren tree view mysite                            # inspect the tree