A small place to start.

Install FleaCMS

For Apple Silicon Macs and x86-64 Linux. Open Terminal and run:

curl -fsSL https://fleacms.com/install.sh | bash

The installer downloads the matching executable, checks its SHA-256 checksum and installs it to ~/.local/bin/flea. No sudo, Go or Node required. It does not change your shell profile.

Use the installed copy in this terminal and check the version:

export PATH="$HOME/.local/bin:$PATH"
flea version

If needed, add that PATH line to your shell profile for future terminals. Then follow the quickstart below.

You can read the installer before running it, or download the Mac binary, Linux binary and checksums directly.

A site needs no frontend build pipeline or database. Deployment uses Git and SSH. Flea serves your sites on an Ubuntu server you manage.

Your first site

Create a project and start the local server:

flea new my-site
cd my-site
flea dev

Enter a site name when prompted. You can add an owner email now or come back to it later. Open http://127.0.0.1:3000.

Edit site/index.html. The browser reloads when your files change. Add a little editable text:

<h1 snip>Hello, from our little corner.</h1>

While dev runs, Flea moves that text into flea/snips.json and leaves a generated reference in your HTML. Keep both files together in Git.

To start with example pages, use flea new --starter my-site. The default gives you a clean homepage.

Check your work

flea status

This validates your project without rewriting it. New projects have a Git repository on main, but no initial commit.

A folder you can follow

site/

Public HTML, CSS, images and other assets.

site/main.layout.html

The shared page wrapper.

flea/snips.json

Editable content and page metadata.

flea/data/

Optional JSON data you maintain in code.

flea/media/

Managed photos and videos.

mailers/

Private email templates.

.flea.config.json

Site settings and branch deployment destinations.

flea/runtime/

Private, Git-ignored runtime state.

Public URLs leave off site/. For example, site/images/logo.svg is served at /images/logo.svg. Keep secrets out of configuration, templates and Git.

Pages & templates

Add a page

Create site/about.html for /about. You can use site/about/index.html instead, but not both. Link to extensionless URLs without a trailing slash.

Share a layout

The default wrapper is site/main.layout.html. Put {slot} where the page content belongs.

<header>Our studio</header>
<main>{slot}</main>
<footer>Thanks for stopping by.</footer>

For a different wrapper, put this comment at the very start of a page:

<!-- flea
layout: /custom.layout.html
-->

Preserve the generated layout's app.current_admin conditional blocks, CSRF meta tag and admin toolbar include. They connect the page to the owner editor.

Reuse a partial

Create site/_card.html, then include it with {render card}. Relative names resolve beside the calling template. {render /shared/card} selects site/shared/_card.html.

Settings and structured data

Public settings live under app in .flea.config.json. Use {app.site_name} in your templates. A file named flea/data/team.json is available as data.team.

{#if app.phone}
  <p>Call {app.phone}</p>
{/if}

{#each data.team.members as member}
  <p>{member.name}</p>
{:else}
  <p>Meet the team soon.</p>
{/each}

Conditions take dotted paths, not JavaScript expressions. Use {#unless app.phone}...{/unless} for a negative condition. Both support {:else} and {:else if dotted.path}.

Make content editable

A snip is a piece of content the owner can change. Mark an element with a bare snip attribute:

<section snip>
  <h2>Made just around the corner.</h2>
  <p>Visit our studio on Saturday.</p>
</section>

Dev extracts the inner HTML into JSON and replaces it with a generated snip directive. Let Flea generate the ID and keep it unchanged. The JSON entry becomes the source of the editable value.

Classes, layout and other attributes stay in the template. Don't nest snips or put template directives inside a new editable region. Use dedicated image and video snips for media.

Owners can format text and edit page titles and descriptions using Page details. Changes are published with the page's Save changes button.

Photos & videos

Photos

<img snip src="/images/studio.jpg"
  alt="The studio in the afternoon"
  width="1200" height="800" />

Dev imports a local JPEG or PNG into managed media and creates the source and alt-text bindings. Keep dimensions, classes and links in your HTML. Don't combine a media snip with srcset, picture or competing source elements.

Owners click a photo in Edit mode to choose or upload a replacement. Save changes publishes it; Cancel discards the draft.

Videos

<video snip src="/videos/studio.mp4" controls></video>

Use a fast-start MP4 with H.264 video and optional AAC-LC audio, up to 25 MiB. Flea does not transcode videos. Owners can replace the video or its poster from the page editor.

Video storage is limited to 64 MiB, including retained replacements. Managed MP4 files are Git-ignored. Restore missing files on a fresh checkout with flea pull --snips-only before validation.

Repeatable content

A multisnip lets an owner add, remove and reorder items such as team members. Give the group a name and name its editable fields:

<article multisnip="team">
  <h2 snip="name">Sam Rivera</h2>
  <p snip="title">Studio founder</p>
  <img snip="photo" src="/images/sam.jpg" alt="Sam" />
</article>

Dev turns the seed into a loop. Owners use the on-page Add tile, remove button and drag handles. Arrow keys on a handle can reorder items too.

Keep each group on an individual page, with one root element. Don't nest groups or place them in layouts, partials or other loops. Video fields are not supported in multisnips.

Hand over the editing

Add an approved owner from your site folder:

flea admin owner@example.com

This adds the address to admin.emails. Owners visit /admin and sign in with an emailed code. All approved owners have the same editing access.

Editing starts enabled. Click text or media, make changes, then use Save changes or Cancel. Both keep editing on. The Theme panel has its own save and cancel controls.

New local sites preview email in the browser without sending it. Production needs HTTPS and real email delivery. Commit and deploy owner-list changes before sharing the live sign-in link.

Sessions have a default 30-day idle window. Set admin.session_idle_days to a value from 1 to 365. An empty owner list disables live sign-in.

Your CSS, your design

Generated sites include Prewind 1.3.1. Start with global styles, then use utilities for individual adjustments. There is no CSS build step.

Edit site/css/theme.css for colors, fonts and spacing tokens. Put shared rules in site/css/global.css inside @layer styles. Owners can change supported theme variables through the Theme panel.

Icons

{icon arrow-right}
{icon search size="20" aria-label="Search"}

Dev downloads only the referenced Lucide icons into flea/icons/. Commit the cache for offline use. Status checks do not download icons.

Put your site online

Flea hosts multiple sites on one Ubuntu server. You'll need SSH access, a domain pointing to that server, and inbound TCP ports 80 and 443 for HTTPS.

Set up the server

flea setup

Run this from your computer. It installs the bundled server remotely; there is no need to install Go on the host. Use a suitable server with ports available for Flea.

Deploy a branch

flea deploy

The first run asks for the server, domain and HTTPS preferences. It saves that branch's destination in .flea.config.json and offers to commit your reviewed files. Deployment publishes committed source and requires a clean working tree.

Each branch has its own destination. Use flea deploy -configure to change it. Configuring a destination does not create DNS records.

Keep owner changes

Normal deployment preserves live editable content and theme changes. To bring those edits into your local project, stop dev and run:

flea pull

Use --snips-only or --theme-only to narrow a pull. Review and commit the result.

To deliberately publish local content or theme edits, first establish a pull baseline, then use the relevant option:

flea deploy --with-snips
flea deploy --with-theme

You can combine the options. Conflicts require an explicit choice between the live and local changes.

Email & contact forms

New sites set dev.email_preview to true. Local sign-in and contact emails open as private browser previews without Resend credentials. Preview messages expire and disappear when dev stops.

For real delivery, run:

flea email

Local credentials belong in the private, Git-ignored .env file. For real local delivery, set the preview toggle to false and restart dev. Production ignores the preview toggle and needs server-side mail configuration.

A contact form

Set contact.to in site configuration. The starter has a working example. The form posts these fields:

<form method="post" action="/_flea/contact">
  <label>Name <input name="name" required /></label>
  <label>Email <input type="email" name="email" required /></label>
  <label>Message <textarea name="message" required></textarea></label>
  <input type="hidden" name="website" value="" />
  <button type="submit">Send message</button>
</form>

Messages are emailed, not stored. Add a success page if you configure contact.success_path. General-purpose form handling is not included.

Email templates

Customize mailers/*.email.html and *.email.txt. HTML emails share mailers/main.layout.html. Keep its slot and use escaped app.* and email.* values.

flea email preview sign-in

This renders a sample without sending an email.

Backups & recovery

Make a backup

flea backup ../before-redesign.flea-backup

This downloads the active site's code and editable content, including managed media and theme. Choose a new file path outside your site and keep a separate copy. Credentials, certificates, deployment mappings and sessions are excluded.

Roll back code

flea rollback --list
flea rollback

Rollback republishes earlier code while retaining current owner content and theme. It asks for confirmation before acting.

Restore a backup

flea restore ../before-redesign.flea-backup

Restore replaces live code, site configuration and editable content. It requires typed confirmation. Take a fresh backup first if newer content matters.

Reset a local project

flea reset returns the local site to a clean starting point after confirmation. It replaces local files and settings, keeping Git history and a private sibling backup. It does not reset a live site.

Keep Flea up to date

Update your installed CLI with:

flea update

Flea verifies the downloaded checksum and version before replacing the executable. A local update does not update your remote host. From a configured site, explicitly run:

flea update-server

Server updates affect every site on that host and ask before restarting it. Keep backups and check compatibility first. An interrupted update can be recovered with flea update-server --recover.

Where Flea fits

Flea is built for small content websites. It is not a general application framework or an ecommerce platform.

• No general field schemas, arbitrary server-side application code or general-purpose form backend.
• No video transcoding or video fields in collections.
• No content revision-history interface. Use the backup and recovery commands.
• Rich text is sanitized; editable content does not accept unrestricted HTML.
• Downloads currently cover Apple Silicon macOS and x86-64 Linux. Clean-machine testing is in progress.

The source repository is private. The binaries are free to use, without an account or license key.

Release notes

0.3.0 · September 29, 2026

The first public test release for Apple Silicon macOS and x86-64 Linux. Install with one command, then use flea update for future CLI releases.

Includes plain-file sites, on-page text and media editing, repeatable collections, theme controls, local email previews, SSH deployment and backup/recovery commands. This is an early release; please test on a small site before relying on it for production work.

Need a hand?

Start with flea status to check your site and flea <command> --help for a command's options.

If you're testing Flea, send feedback to the person who invited you. Include your operating system, processor, Flea version, the command you ran and the exact error. Leave out credentials, sign-in codes and private runtime files.