FastMode CLI — Complete Agent Reference

FastMode lets you create a live website, deploy it to the cloud, and manage all its content — entirely from the command line. One-time browser login for OAuth authentication, then every operation runs in the terminal. No local servers, no manual dashboards.

• Free cloud hosting — every site gets a live URL at

  yoursite.fastmode.ai

• Free SSL — HTTPS included automatically
• Custom domains — connect any domain (e.g.

  www.example.com

  )
• Full CMS — any content structure (blog, team, products, portfolios, anything)
• Agent-native — every operation works via CLI, zero human intervention needed

Table of Contents

1. End-to-End Workflow
2. CRITICAL: Before You Build Anything
3. Website Analysis
4. Command Reference
5. Project Resolution
6. Schema & Field Types
7. Content Items
8. Client Portal Management
9. Package Structure
10. Manifest Format
11. Template Syntax (includes SEO rules, image handling, forms, inline editing)
12. Deployment & Build Status
13. Validation
14. Common Mistakes & How to Fix Them
15. Pre-Deployment Checklist
16. Error Handling & Exit Codes

End-to-End Workflow

This is the complete sequence to go from nothing to a live website.

# 1. Authenticate (one-time — credentials persist at ~/.fastmode/credentials.json)
fastmode login

# 2. Create a project (gets a free hosted URL instantly)
fastmode projects create "Acme Corp"
fastmode use "Acme Corp"

# 3. Define content structure (write schema.json, then sync it)
fastmode schema sync -f schema.json

# 4. Add content
fastmode items create posts -n "Welcome" -d '{"title": "Welcome to Acme", "body": "<p>We build great things.</p>"}'
fastmode items create team -n "Jane Doe" -d '{"role": "Founder", "bio": "<p>Visionary leader.</p>"}'

# 5. Build HTML templates with {{tokens}}, package into a zip, validate, deploy
fastmode validate package site.zip
fastmode deploy site.zip
# Deploy waits for build to finish and reports success or failure with error details

# 6. If the build failed, check what went wrong
fastmode status
# Fix the issue, then re-deploy

CRITICAL: Before You Build Anything

STOP. Before writing ANY HTML, templates, or manifest.json, complete these steps.

Step 1: Check for Existing Projects

fastmode projects

This lists all the user's existing FastMode projects.

Step 2: Decide — Existing or New Project

If projects exist: Ask the user: "Is this website for one of your existing projects, or should I create a new one?" Let the user choose.

If NO projects exist: This is a new user — ask: "What would you like to name your new project?"

Step 3a: For EXISTING Projects

1. User selects the project from the list
2. Run

   fastmode use "Project Name"

   to set it as default
3. Run

   fastmode schema show

   to get the current collections and fields
4. Use this schema to build templates with the correct field names

Step 3b: For NEW Projects

1. Ask for the project name if you don't have it
2. Run

   fastmode projects create "Project Name"

3. Run

   fastmode use "Project Name"

4. You'll create the schema later with

   fastmode schema sync

5. Optionally generate sample content:

   fastmode generate-samples

Checkpoint — Confirm Before Continuing

fastmode projects

fastmode projects create

fastmode use "Project Name"

fastmode schema show

If you don't have a project set, DO NOT PROCEED. Go back to Step 1.

WHY THIS MATTERS:

• For existing projects: The schema determines which fields to use in templates — get it wrong and the build fails
• For new projects: You need the project before you can deploy
• Always: The user must confirm which project to use — never assume

Website Analysis (Do This Before Writing Code)

Before writing any HTML or templates, analyze the site:

1. Map ALL URLs — document every page path (

   /

   ,

   /about

   ,

   /blog

   ,

   /blog/post-slug

   , etc.)
2. Categorize each page — Static (fixed content), List (shows multiple items), or Detail (single item from a collection)
3. Identify collections — repeating content that should be CMS-managed (blog posts, team members, products, testimonials, etc.)
4. Document assets — all CSS, JS, image, and font file locations
5. PRESERVE original URLs — if the site uses

   /resources

   for articles, keep

   /resources

   . Do NOT change it to

   /blog

   . Use the manifest's path configuration.

Command Reference

Authentication

fastmode login                          # Open browser for OAuth device flow
fastmode logout                         # Delete ~/.fastmode/credentials.json
fastmode whoami                         # Show current user email and name

• login

  uses OAuth 2.0 device authorization flow: opens a browser window where the user approves access on

  fastmode.ai

  , then credentials are saved automatically. The browser is only needed for this one-time login step.
• OAuth scopes: The token grants access to the user's FastMode projects only (project management, schema editing, content CRUD, deployments). No third-party service access is requested.
• Credentials persist at

  ~/.fastmode/credentials.json

  with restricted file permissions (

  0o600

  — owner read/write only). Treat this file as a sensitive secret.
• Tokens auto-refresh. If a token expires, the next command will refresh it silently using the stored refresh token.
• If credentials are missing or invalid, most commands will trigger the login flow automatically.

• logout

  deletes

  ~/.fastmode/credentials.json

  and revokes the stored tokens.

Projects

fastmode projects                       # List all projects (default action)
fastmode projects list                  # Same as above
fastmode projects create "Name"         # Create a new project
fastmode projects create "Name" --subdomain custom-sub  # Custom subdomain
fastmode projects create "Name" --force                  # Skip similar-name check
fastmode use <project>                  # Set default project for all commands

• projects create

  checks for existing projects with similar names. Use

  --force

  to skip.
• Subdomain auto-generated from name if not provided (lowercase, hyphens, max 30 chars).

• use

  stores the default in

  ~/.fastmode/config.json

  . Does NOT validate the project exists.

Schema

fastmode schema show                    # Show all collections and fields
fastmode schema show -p "Project Name"  # Specify project
fastmode schema sync -f schema.json     # Create collections and fields from JSON file
fastmode schema field-types             # List all available field types (no auth needed)

• schema show

  requires authentication and a project.

• schema sync

  reads a local JSON file and creates/updates the schema. Skips duplicates. Two-phase: creates collections first, then fields (handles relation dependencies).

• schema field-types

  works without authentication.

Content Items

fastmode items list <collection>                          # List all items
fastmode items list posts --limit 10 --sort publishedAt --order desc
fastmode items get <collection> <slug>                    # Get single item
fastmode items create <collection> -n "Name" -d '{"field": "value"}'
fastmode items create posts -n "Title" -f data.json       # Data from file
fastmode items create posts -n "Draft Post" -d '{}' --draft
fastmode items update <collection> <slug> -d '{"field": "new value"}'
fastmode items update posts my-post -n "New Title"
fastmode items update posts my-post --publish             # Publish a draft
fastmode items update posts my-post --unpublish           # Revert to draft
fastmode items delete <collection> <slug> --confirm       # REQUIRES --confirm
fastmode items relations <collection>                     # Show linkable items for relation fields
fastmode items relations posts --field author             # Options for specific field

See the Content Items section below for detailed rules on data formats, relation fields, and drafts.

Client Portal Management

fastmode clients list                              # List portal clients with access
fastmode clients invite client@example.com         # Invite with default permissions
fastmode clients invite client@example.com -n "Jane" --permissions cms.read,cms.write
fastmode clients invitations                       # List pending invitations
fastmode clients update-permissions <accessId> --permissions cms.read,editor
fastmode clients revoke <accessId> --confirm       # REQUIRES --confirm
fastmode clients cancel-invite <invitationId> --confirm  # REQUIRES --confirm

See the Client Portal Management section below for details on permissions, invite flow, and examples.

Deployment & Build Status

fastmode deploy site.zip                # Deploy and wait for build to finish
fastmode deploy site.zip --force        # Skip GitHub sync check
fastmode deploy site.zip --no-wait      # Upload only, don't wait for build
fastmode deploy site.zip --timeout 300000  # Custom timeout in ms (default: 120000)
fastmode status                         # Check current build/deploy status
fastmode deploys                        # List deployment history
fastmode deploys --limit 5             # Limit number of results

See Deployment & Build Status below for the full deploy lifecycle.

Validation

fastmode validate manifest manifest.json
fastmode validate template index.html -t custom_index
fastmode validate template post.html -t custom_detail -c posts
fastmode validate template post.html -t custom_detail -c posts -p "My Project"
fastmode validate template about.html -t static_page
fastmode validate package site.zip

• Template types:

  custom_index

  (collection listing),

  custom_detail

  (single item),

  static_page

  (fixed page).

• -c

  specifies the collection slug (required for

  custom_index

  and

  custom_detail

  ).

• -p

  validates tokens against the actual project schema (reports missing fields).
• All validation commands exit with code 1 on errors — safe for CI/CD pipelines.

Documentation & Examples

fastmode examples <type>                # Code examples for a specific pattern
fastmode guide                          # Full website conversion guide
fastmode guide templates                # Template syntax guide
fastmode guide common_mistakes          # Common pitfalls to avoid
fastmode generate-samples               # Generate placeholder content for empty collections
fastmode generate-samples -c posts team # Specific collections only

Available example types:

manifest_basic

manifest_custom_paths

blog_index_template

blog_post_template

team_template

downloads_template

form_handling

asset_paths

data_edit_keys

each_loop

conditional_if

nested_fields

featured_posts

parent_context

equality_comparison

comparison_helpers

youtube_embed

nested_collection_loop

loop_variables

common_mistakes

Available guide sections:

full

first_steps

analysis

structure

seo

manifest

templates

tokens

forms

assets

checklist

common_mistakes

Project Resolution

Every project-scoped command (schema, items, deploy, status, etc.) needs a project. Resolution order:

1. -p

   /

   --project

   flag — explicit on the command:

   -p "My Project"

   or

   -p abc123-uuid

2. FASTMODE_PROJECT

   environment variable — set in shell:

   export FASTMODE_PROJECT="My Project"

3. Default project — saved by

   fastmode use "My Project"

   in

   ~/.fastmode/config.json

If none is set, the command prints an error and exits with code 1:

Error: No project specified.
Use -p <id-or-name>, set FASTMODE_PROJECT env var, or run: fastmode use <project>

Project identifiers can be:

• UUID — used directly (e.g.

  550e8400-e29b-41d4-a716-446655440000

  )
• Project name — resolved via API (exact match first, then partial match, case-insensitive)

Schema & Field Types

Creating a Schema

Write a

schema.json

fastmode schema sync -f schema.json

schema.json Format

{
  "collections": [
    {
      "slug": "posts",
      "name": "Blog Posts",
      "nameSingular": "Blog Post",
      "fields": [
        { "slug": "title", "name": "Title", "type": "text", "isRequired": true },
        { "slug": "excerpt", "name": "Excerpt", "type": "textarea" },
        { "slug": "body", "name": "Body", "type": "richText" },
        { "slug": "featured-image", "name": "Featured Image", "type": "image" },
        { "slug": "category", "name": "Category", "type": "select", "options": "News, Tutorial, Update" },
        { "slug": "tags", "name": "Tags", "type": "multiSelect", "options": "JavaScript, Python, DevOps, AI" },
        { "slug": "featured", "name": "Featured", "type": "boolean" },
        { "slug": "author", "name": "Author", "type": "relation", "referenceCollection": "team" }
      ]
    },
    {
      "slug": "team",
      "name": "Team Members",
      "nameSingular": "Team Member",
      "fields": [
        { "slug": "role", "name": "Role", "type": "text" },
        { "slug": "bio", "name": "Bio", "type": "richText" },
        { "slug": "photo", "name": "Photo", "type": "image" },
        { "slug": "email", "name": "Email", "type": "email" }
      ]
    }
  ]
}

To add fields to existing collections, use

fieldsToAdd

{
  "fieldsToAdd": [
    {
      "collectionSlug": "posts",
      "fields": [
        { "slug": "reading-time", "name": "Reading Time", "type": "number" }
      ]
    }
  ]
}

You can combine

collections

fieldsToAdd

Available Field Types

text

{{field}}

textarea

{{field}}

richText

{{{field}}}

number

{{field}}

boolean

{{#if field}}

date

{{field}}

datetime

{{field}}

image

{{field}}

file

{{field}}

<a href="{{field}}" download>

url

{{field}}

videoEmbed

{{field}}

email

{{field}}

select

{{field}}

"options": "A, B, C"

multiSelect

{{field}}

"options": "A, B, C"

relation

{{field.name}}

"referenceCollection": "slug"

Relation Fields — CRITICAL

Relation fields link items between collections (e.g. a post has an author from the team collection). When creating or updating items with relation fields:

• You MUST use the item's UUID, not its name or slug
• Use

  fastmode items relations <collection>

  to get the available IDs
• Example:

  fastmode items relations posts --field author

  shows team member IDs

# First, find the author's item ID
fastmode items relations posts --field author
# Output shows: ID: 550e8400-..., Name: Jane Doe, Slug: jane-doe

# Then use that ID when creating a post
fastmode items create posts -n "My Post" -d '{"title": "My Post", "author": "550e8400-e29b-41d4-a716-446655440000"}'

WRONG:

"author": "Jane Doe"

"author": "550e8400-e29b-41d4-a716-446655440000"

Content Items

Creating Items

fastmode items create <collection> -n "Item Name" -d '{"field": "value"}'

-n, --name <name>

-s, --slug <slug>

-d, --data <json>

-f, --file <path>

-d

-p, --project <id>

--draft

Data rules:

• -d

  value must be valid JSON. Keys are field slugs.

• -f

  reads from a JSON file. If both

  -f

  and

  -d

  are given,

  -f

  wins.
• If neither

  -d

  nor

  -f

  is given, the item is created with just the name (no field data).
• Rich text fields accept raw HTML:

  "body": "<h2>Title</h2><p>Content here.</p>"

• Relation fields require UUIDs (see above).
• Without

  --draft

  , items are published immediately (

  publishedAt

  set to now).

Updating Items

fastmode items update <collection> <slug> -d '{"field": "new value"}'

-n, --name <name>

-d, --data <json>

-f, --file <path>

-p, --project <id>

--publish

publishedAt

--unpublish

publishedAt

Update is a partial merge. Only the fields you provide in

-d

Deleting Items

fastmode items delete <collection> <slug> --confirm

The

--confirm

Always ask the user for confirmation before deleting.

Draft / Publish Mechanics

fastmode items create posts -n "Title" -d '{...}'

fastmode items create posts -n "Title" -d '{...}' --draft

fastmode items update posts my-slug --publish

fastmode items update posts my-slug --unpublish

• Draft items have

  publishedAt: null

  and are not visible on the live site.
• Published items have a

  publishedAt

  timestamp and appear on the live site.
• Without

  --draft

  , new items are published immediately.

Client Portal Management

The client portal lets you give external clients (your customers, collaborators) limited access to manage content on your FastMode site. Clients get their own login, separate from your admin account, with configurable permissions.

How It Works

1. You invite a client by email — they receive a unique invite link
2. Client clicks the link — creates a password and gets portal access
3. Client manages content — based on the permissions you assigned
4. You control access — update permissions or revoke access at any time

The portal is auto-enabled on the project when you send the first invitation. No manual setup needed.

Available Permissions

cms.read

cms.write

editor

forms.read

dns

api

notifications

billing

Default permissions (used when none specified):

cms.read

cms.write

editor

forms.read

Inviting Clients

# Invite with default permissions
fastmode clients invite client@example.com

# Invite with a name
fastmode clients invite client@example.com -n "Jane Smith"

# Invite with specific permissions
fastmode clients invite client@example.com -n "Jane Smith" --permissions cms.read,forms.read

# Invite with all permissions
fastmode clients invite client@example.com --permissions cms.read,cms.write,editor,forms.read,dns,api,notifications,billing

The command returns an invite URL — share this with the client. The link expires in 7 days.

Important:

• Each email can only be invited once per project
• If a client already has access, the invite will fail
• If a pending invitation already exists for the email, the invite will fail

Listing Clients and Invitations

# See who has portal access
fastmode clients list

# See pending (unaccepted) invitations
fastmode clients invitations

clients list

Updating Permissions

# First, get the access ID from the list
fastmode clients list

# Update permissions (replaces ALL existing permissions)
fastmode clients update-permissions <accessId> --permissions cms.read,cms.write,editor

Permissions are replaced entirely — if a client had

cms.read,cms.write,editor,forms.read

--permissions cms.read

cms.read

Revoking Access

# Revoke a client's portal access (requires --confirm)
fastmode clients revoke <accessId> --confirm

The

--confirm

Always ask the user for confirmation before revoking access.

Revoking access is a soft delete — the client's account still exists but they cannot access this project's portal. Their active sessions are terminated immediately.

Canceling Invitations

# Cancel a pending invitation (requires --confirm)
fastmode clients cancel-invite <invitationId> --confirm

The invitation link will no longer work. Use

fastmode clients invitations

Typical Workflow

# 1. Invite your client
fastmode clients invite designer@agency.com -n "Design Agency" --permissions cms.read,cms.write,editor

# 2. Share the invite URL from the output with the client

# 3. Later, check who has access
fastmode clients list

# 4. Restrict a client to read-only
fastmode clients update-permissions abc12345 --permissions cms.read

# 5. Remove a client who no longer needs access
fastmode clients revoke abc12345 --confirm

Package Structure

The deployment package is a

.zip

site.zip
├── manifest.json              # REQUIRED — defines pages and CMS templates
├── pages/                     # Static HTML pages
│   ├── index.html             # Homepage (REQUIRED — must have path "/")
│   ├── about.html
│   └── contact.html
├── templates/                 # CMS-powered templates (if using collections)
│   ├── posts_index.html       # Blog listing page
│   ├── posts_detail.html      # Single blog post page
│   └── team_index.html        # Team listing page
└── public/                    # ALL static assets (CSS, JS, images, fonts)
    ├── css/
    │   └── style.css
    ├── js/
    │   └── main.js
    └── images/
        ├── logo.png
        └── favicon.ico

Strict Rules

1. manifest.json

   MUST be at the root of the zip.
2. Static pages go in

   pages/

   . One HTML file per page.
3. CMS templates go in

   templates/

   . Convention:

   {collection}_index.html

   and

   {collection}_detail.html

   .
4. ALL static assets go in

   public/

   . CSS, JavaScript, images, fonts — everything.
5. Reference assets with

   /public/

   prefix in HTML. Example:

   <link href="/public/css/style.css" rel="stylesheet">

   .
6. A homepage is required. One page must have

   "path": "/"

   in the manifest.

Critical: Asset Paths

WRONG — will 404:

<link href="/assets/css/style.css" rel="stylesheet">
<link href="/css/style.css" rel="stylesheet">
<link href="../css/style.css" rel="stylesheet">
<script src="js/main.js"></script>

CORRECT:

<link href="/public/css/style.css" rel="stylesheet">
<script src="/public/js/main.js"></script>
<img src="/public/images/logo.png" alt="Logo">

This also applies inside CSS files — background images AND fonts:

/* WRONG */
background-image: url('../images/bg.jpg');
background-image: url('images/bg.jpg');
src: url('../fonts/custom.woff2');

/* CORRECT */
background-image: url('/public/images/bg.jpg');
src: url('/public/fonts/custom.woff2');

Asset path conversion table:

css/style.css

/public/css/style.css

../css/style.css

/public/css/style.css

./images/logo.png

/public/images/logo.png

/images/logo.png

/public/images/logo.png

../fonts/custom.woff

/public/fonts/custom.woff

External URLs (Google Fonts, CDNs, etc.) stay unchanged.

Manifest Format

The

manifest.json

Basic Example (Static Only)

{
  "pages": [
    { "path": "/", "file": "pages/index.html", "title": "Home" },
    { "path": "/about", "file": "pages/about.html", "title": "About" },
    { "path": "/contact", "file": "pages/contact.html", "title": "Contact" }
  ]
}

With CMS Collections

{
  "pages": [
    { "path": "/", "file": "pages/index.html", "title": "Home" },
    { "path": "/about", "file": "pages/about.html", "title": "About" }
  ],
  "cmsTemplates": {
    "postsIndex": "templates/posts_index.html",
    "postsIndexPath": "/blog",
    "postsDetail": "templates/posts_detail.html",
    "postsDetailPath": "/blog",
    "teamIndex": "templates/team_index.html",
    "teamIndexPath": "/team"
  }
}

CMS Template Keys — FLAT Format

Each collection needs 2-4 keys in

cmsTemplates

{collectionSlug}Index

{collectionSlug}IndexPath

{collectionSlug}Detail

{collectionSlug}DetailPath

{slug}Index

{slug}IndexPath

/blog

{slug}Detail

{slug}DetailPath

/blog

/blog/item-slug

Example for a "services" collection:

"cmsTemplates": {
  "servicesIndex": "templates/services_index.html",
  "servicesIndexPath": "/services",
  "servicesDetail": "templates/services_detail.html",
  "servicesDetailPath": "/services"
}

Common Manifest Mistakes — AI Agents Frequently Get This Wrong

AI agents frequently use a nested object format or "collections" key that FastMode does NOT support. Read carefully.

WRONG — using "collections" key (MOST COMMON AI MISTAKE):

{
  "collections": {
    "posts": {
      "indexPath": "/blog",
      "indexFile": "collections/posts/index.html",
      "detailPath": "/blog/:slug",
      "detailFile": "collections/posts/detail.html"
    }
  }
}

WRONG — nested objects inside cmsTemplates:

"cmsTemplates": {
  "posts": {
    "indexPath": "/blog",
    "detailPath": "/blog"
  }
}

WRONG — singular slug names:

"postIndex": "..."   // Should be "postsIndex"
"postDetail": "..."  // Should be "postsDetail"

CORRECT — flat keys using

cmsTemplates

"cmsTemplates": {
  "postsIndex": "templates/posts_index.html",
  "postsIndexPath": "/blog",
  "postsDetail": "templates/posts_detail.html",
  "postsDetailPath": "/blog"
}

Key rules:

• Use

  cmsTemplates

  , NOT

  collections

• Use FLAT keys:

  {slug}Index

  ,

  {slug}Detail

  ,

  {slug}IndexPath

  ,

  {slug}DetailPath

• Do NOT nest objects inside collection names
• Use

  fastmode validate manifest manifest.json

  to catch these errors before deploying

Optional: Head/Body Injection

{
  "pages": [...],
  "cmsTemplates": {...},
  "defaultHeadHtml": "<link rel=\"stylesheet\" href=\"/public/css/global.css\">",
  "defaultBodyEndHtml": "<script src=\"/public/js/analytics.js\"></script>"
}

Template Syntax

FastMode templates use Handlebars-style tokens. There are three types of templates:

• Static pages (

  pages/

  ): Fixed HTML with optional

  data-edit-key

  attributes for inline CMS editing and optional

  {{#each}}

  loops for dynamic content.
• Index templates (

  templates/

  ): Collection listing pages. MUST contain at least one

  {{#each collectionSlug}}

  loop.
• Detail templates (

  templates/

  ): Single item pages. MUST contain CMS tokens like

  {{name}}

  ,

  {{{body}}}

  , etc.

SEO Tags — Do NOT Include

FastMode automatically manages all SEO meta tags. Including them in your HTML will cause duplicate tags (bad for SEO ranking). Remove ALL of these from your templates:

<title>...</title>

<meta name="description">

<meta name="keywords">

<meta property="og:*">

<meta name="twitter:*">

<link rel="icon">

<link rel="shortcut icon">

<link rel="apple-touch-icon">

<meta name="google-site-verification">

Correct

<head>

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <!-- SEO managed by Fast Mode — do not add title, description, or OG tags -->
  <link rel="stylesheet" href="/public/css/style.css">
  <!-- External fonts, scripts, etc. are fine -->
  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap" rel="stylesheet">
</head>

Built-in Fields (Every Item Has These)

{{name}}

<h1>{{name}}</h1>

{{slug}}

<a href="/posts/{{slug}}">

{{url}}

<a href="{{url}}">Read more</a>

{{publishedAt}}

<time>{{publishedAt}}</time>

{{createdAt}}

{{updatedAt}}

Regular Fields — Double Braces

{{field}}

Used for text, number, date, image, url, email, select, boolean fields:

<h1>{{name}}</h1>
<p>{{excerpt}}</p>
<img src="{{featured-image}}" alt="{{name}}">
<span>Category: {{category}}</span>
<a href="{{website-url}}">Visit</a>

Rich Text Fields — Triple Braces

{{{field}}}

CRITICAL: Rich text fields contain HTML. You MUST use triple braces

{{{ }}}

<!-- CORRECT — HTML renders properly -->
<div class="content">{{{body}}}</div>
<div class="bio">{{{bio}}}</div>

<!-- WRONG — HTML appears as escaped text like &lt;p&gt;Hello&lt;/p&gt; -->
<div class="content">{{body}}</div>

Loops —

{{#each collection}}

Used in index templates and static pages to iterate over collection items.

Basic loop:

{{#each posts}}
  <article>
    <h2><a href="{{url}}">{{name}}</a></h2>
    <p>{{excerpt}}</p>
  </article>
{{/each}}

Loop modifiers:

limit=N

{{#each posts limit=6}}

sort="field"

{{#each posts sort="publishedAt"}}

order="asc|desc"

{{#each posts sort="name" order="asc"}}

featured=true

{{#each posts featured=true limit=3}}

where="field.slug:{{slug}}"

{{#each posts where="author.slug:{{slug}}"}}

Combined modifiers:

<!-- Latest 3 featured posts, newest first -->
{{#each posts featured=true limit=3 sort="publishedAt" order="desc"}}
  <article>{{name}}</article>
{{/each}}

Loop Variables

Available only inside

{{#each}}

{{@index}}

Item {{@index}}

{{@first}}

{{#if @first}}hero{{/if}}

{{@last}}

{{#unless @last}},{{/unless}}

{{@length}}

Showing {{@length}} items

Do NOT use loop variables outside

{{#each}}

{{#each posts}}
  {{#if @first}}
    <div class="hero">
      <h1>{{name}}</h1>
    </div>
  {{else}}
    <div class="card">
      <h3>{{name}}</h3>
    </div>
  {{/if}}
{{/each}}

Conditionals —

{{#if}}

,

{{#unless}}

<!-- Show if field has a value -->
{{#if image}}
  <img src="{{image}}" alt="{{name}}">
{{/if}}

<!-- Show if field has a value, with fallback -->
{{#if thumbnail}}
  <img src="{{thumbnail}}" alt="">
{{else}}
  <div class="placeholder">No image</div>
{{/if}}

<!-- Show if field is empty/missing -->
{{#unless posts}}
  <p>No posts yet.</p>
{{/unless}}

Equality & Comparison Helpers

<!-- Equal -->
{{#if (eq status "published")}}
  <span class="badge">Published</span>
{{/if}}

<!-- Not equal — useful for "Related Items" excluding current item -->
{{#unless (eq slug ../slug)}}
  <a href="{{url}}">{{name}}</a>
{{/unless}}

<!-- Numeric comparisons -->
{{#if (lt @index 1)}}   <!-- Less than -->
{{#if (gt @index 0)}}   <!-- Greater than -->
{{#if (lte price 100)}} <!-- Less than or equal -->
{{#if (gte stock 5)}}   <!-- Greater than or equal -->
{{#if (ne status "draft")}} <!-- Not equal -->

Hero + grid layout pattern:

{{#each posts}}
  {{#if (lt @index 1)}}
    <div class="hero"><h1>{{name}}</h1></div>
  {{else}}
    {{#if (lt @index 4)}}
      <div class="featured"><h3>{{name}}</h3></div>
    {{else}}
      <div class="list-item">{{name}}</div>
    {{/if}}
  {{/if}}
{{/each}}

Relation Fields — Dot Notation

Access fields on related items using dot notation:

{{#each posts}}
  <article>
    <h2>{{name}}</h2>
    {{#if author}}
      <span class="author">By {{author.name}}</span>
      {{#if author.photo}}
        <img src="{{author.photo}}" alt="{{author.name}}">
      {{/if}}
    {{/if}}
  </article>
{{/each}}

Available:

{{relation.name}}

{{relation.slug}}

{{relation.url}}

{{relation.anyField}}

Parent Context —

../

Inside a loop, access the parent scope (the current page's item) with

../

<!-- On an author detail page, show only THIS author's posts -->
<h1>{{name}}</h1>

<h2>Posts by {{name}}</h2>
{{#each posts}}
  {{#if (eq author.name ../name)}}
    <article>
      <h2><a href="{{url}}">{{name}}</a></h2>
    </article>
  {{/if}}
{{/each}}

Nested Loops with

@root.

When nesting loops, use

@root.

{{#each categories}}
  <h3>{{name}}</h3>
  {{#each @root.posts where="category.slug:{{slug}}"}}
    <a href="{{url}}">{{name}}</a>
  {{/each}}
{{/each}}

Inline Editing —

data-edit-key

(CRITICAL for Static Pages)

Without

data-edit-key

<!-- Static pages — REQUIRED for editable content -->
<h1 data-edit-key="home-hero-title">Welcome to Our Site</h1>
<p data-edit-key="home-hero-subtitle">We build amazing things.</p>
<p data-edit-key="home-about-text">Our story began in 2020...</p>

<!-- Hierarchical naming for sections -->
<section class="about">
  <h2 data-edit-key="about-section-title">About Us</h2>
  <p data-edit-key="about-section-paragraph-1">First paragraph...</p>
  <p data-edit-key="about-section-paragraph-2">Second paragraph...</p>
</section>

<!-- CMS templates — optional, for hardcoded headers -->
<h1 data-edit-key="blog-page-title">Our Blog</h1>

Naming convention:

{page}-{section}-{element}

Examples:

home-hero-title

about-team-heading

contact-form-intro

services-cta-button

Rules:

• Keys must be unique across the entire site (not just the page).
• Use lowercase with hyphens.
• For different pages, prefix with the page name.
• Static pages without edit keys will appear in the CMS but have nothing editable.

Video Embeds

{{#if video}}
  <iframe
    src="{{video}}"
    allowfullscreen
    referrerpolicy="strict-origin-when-cross-origin"
    title="Video"
  ></iframe>
{{/if}}

The

referrerpolicy="strict-origin-when-cross-origin"

Images — Static vs CMS Content

There are two types of images and they are handled differently:

1. Static/UI images — logos, icons, decorative backgrounds bundled with the site:

<!-- KEEP these as static /public/ paths -->
<img src="/public/images/logo.png" alt="Company Logo">
<img src="/public/images/icons/arrow.svg" alt="">

2. CMS content images — post images, team photos, product images managed through the CMS:

<!-- USE CMS tokens — NEVER hardcode content image URLs -->
{{#if image}}
  <img src="{{image}}" alt="{{name}}">
{{/if}}

Rule of thumb: If it's site branding/design → keep static. If it's content that changes per item → use CMS tokens.

Always wrap CMS images in

{{#if}}

{{#if image}}
  <img src="{{image}}" alt="{{name}}">
{{else}}
  <div class="placeholder-image"></div>
{{/if}}

Common mistake — mixing static and CMS images:

<!-- WRONG: hardcoded image inside a CMS loop -->
{{#each products}}
  <img src="/images/product-placeholder.jpg" alt="Product">  <!-- BAD -->
  <h2>{{name}}</h2>
{{/each}}

<!-- CORRECT: all content comes from CMS -->
{{#each products}}
  {{#if image}}
    <img src="{{image}}" alt="{{name}}">
  {{/if}}
  <h2>{{name}}</h2>
{{/each}}

Forms

<form data-form-name="contact" action="/_forms/contact" method="POST">
  <input type="text" name="name" placeholder="Your name" required>
  <input type="email" name="email" placeholder="Your email" required>
  <textarea name="message" placeholder="Your message" required></textarea>
  <button type="submit">Send Message</button>
</form>

Rules:

• data-form-name

  attribute is required.

• action

  must point to

  /_forms/{formName}

  .
• All inputs must have

  name

  attributes.
• A submit button is required.

CRITICAL: Remove Original Form Handlers

If the source site has JavaScript that handles form submissions, you MUST remove or replace it. Original site JS often does

e.preventDefault()

// PROBLEM: This blocks real submissions!
form.addEventListener('submit', (e) => {
  e.preventDefault();
  showToast('Message sent!');  // FAKE! Data not saved!
});

Option A (simplest): Remove the original JavaScript form handler entirely. The native

<form action="/_forms/contact" method="POST">

Option B (keep JS UX): Replace the handler with one that actually POSTs to FastMode:

form.addEventListener('submit', async (e) => {
  e.preventDefault();
  const formName = form.dataset.formName;
  const response = await fetch('/_forms/' + formName, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(Object.fromEntries(new FormData(form)))
  });
  if (response.ok) {
    form.reset();
    alert('Message sent!');  // NOW it's real!
  }
});

Deployment & Build Status

How Deployment Works

1. Upload:

   fastmode deploy site.zip

   reads the zip, validates it, and uploads it to the server.
2. Build: The server processes the package (renders templates, publishes pages). This happens asynchronously.
3. Wait: By default,

   deploy

   polls for build status every 3 seconds until the build completes or times out (default 2 minutes).
4. Result: Success message with page count and version, or failure message with error details.

Deploy Flags

--force

--no-wait

--timeout <ms>

120000

Checking Build Status

After every deploy or content change, check the build status:

fastmode status

If the build failed,

status

• The error message
• Build logs
• What went wrong

Always run

fastmode status

If a build fails:

1. Run

   fastmode status

   to see the error
2. Fix the issue (template errors, invalid tokens, missing files, etc.)
3. Re-deploy with

   fastmode deploy site.zip

Deploy History

fastmode deploys                # Show last 10 deployments
fastmode deploys --limit 5     # Show last 5

Shows status, version, duration, source, and errors for each deployment.

Exit Codes

• deploy

  : Exits 1 if the build fails (when waiting).

• status

  : Exits 1 if the latest deploy shows "Failed".
• Both: Exit 1 if no project is specified.

Validation

Always validate before deploying. Validation catches errors that would cause build failures.

Validation Workflow

# 1. Validate the manifest
fastmode validate manifest manifest.json

# 2. Validate each template
fastmode validate template pages/index.html -t static_page
fastmode validate template templates/posts_index.html -t custom_index -c posts
fastmode validate template templates/posts_detail.html -t custom_detail -c posts

# 3. Validate the complete package
fastmode validate package site.zip

What Gets Checked

Manifest validation:

• Valid JSON syntax

• pages

  array exists and is not empty
• Homepage (path

  /

  ) exists
• All file paths are valid

• cmsTemplates

  format is correct (flat keys, not nested)

Template validation:

• Balanced tags:

  {{#each}}

  has matching

  {{/each}}

  ,

  {{#if}}

  has

  {{/if}}

• Index templates have at least one

  {{#each}}

  loop
• Detail templates have CMS tokens
• Rich text fields use triple braces

  {{{field}}}

• Loop variables only used inside loops
• Asset paths use

  /public/

  prefix
• Forms have required attributes
• YouTube iframes have

  referrerpolicy

Package validation:

• manifest.json exists at root
• All referenced files exist in the zip
• Assets are in

  public/

  (not

  assets/

  or root)
• Templates are in

  templates/

  (not

  collections/

  )
• All templates pass individual validation

Validation with Schema Check

Add

-p

fastmode validate template templates/posts_detail.html -t custom_detail -c posts -p "My Project"

This reports which tokens reference fields that don't exist in the schema yet, with instructions to create them via

fastmode schema sync

Common Mistakes & How to Fix Them

1. Assets return 404

Problem: CSS, JS, or images don't load. Cause: Files are in

/assets/

/public/

/public/

public/

/public/css/style.css

2. Rich text shows as raw HTML

Problem: Content displays

<p>Hello</p>

{{body}}

{{{body}}}

3. Collection listing page is blank

Problem: Index template shows no items. Cause: Missing

{{#each collectionSlug}}

{{#each posts}}...{{/each}}

4. All detail pages look the same

Problem: Every item page shows identical content. Cause: Detail template has no CMS tokens — just static HTML. Fix: Use tokens like

{{name}}

{{{body}}}

{{image}}

5. Manifest uses wrong format

Problem: Build fails with manifest errors. Cause: Using nested objects or

"collections"

"cmsTemplates"

"postsIndex"

"postsIndexPath"

"postsDetail"

"postsDetailPath"

6. Relation field is empty after create

Problem: Created an item with a relation field but it's null. Cause: Used the item's name instead of its UUID. Fix: Run

fastmode items relations <collection> --field <field>

7. Forms don't submit

Problem: Form appears to submit (shows toast/alert) but no data is received. Cause: Original JavaScript calls

preventDefault()

data-form-name

action="/_forms/formName"

8. Static pages can't be edited in CMS

Problem: Pages appear in the CMS but have no editable content. Cause: Missing

data-edit-key

data-edit-key="unique-key"

9. Deploy blocked by GitHub

Problem:

deploy

--force

fastmode deploy site.zip --force

10. Build fails after deploy

Problem: Upload succeeds but build fails. Fix: Run

fastmode status

11. Template URLs don't match manifest

Problem: Links in templates point to wrong paths. Cause: Template hardcodes

/posts/

"postsIndexPath": "/blog"

manifest.json

12. Loop variables undefined

Problem:

{{@index}}

{{@first}}

{{#each}}

{{#each}}...{{/each}}

13. Duplicate SEO meta tags

Problem: SEO tags show up twice in the rendered HTML. Cause: HTML templates include

<title>

<meta name="description">

14. CSS background images and fonts broken

Problem: Background images or custom fonts don't load. Cause: CSS files use relative paths like

url('../images/bg.jpg')

url('../fonts/custom.woff')

/public/

url('/public/images/bg.jpg')

url('/public/fonts/custom.woff2')

15. Hardcoded example content instead of CMS tokens

Problem: Index page shows static placeholder cards instead of real CMS data. Cause: Template has hardcoded HTML cards instead of

{{#each}}

{{#each collection}}...{{/each}}

Pre-Deployment Checklist

Run through this checklist before every deploy:

Structure:

• manifest.json

  at package root
• Static pages in

  pages/

  folder
• CMS templates in

  templates/

  folder
• ALL assets in

  public/

  folder (not

  assets/

  )

SEO (CRITICAL):

• NO

  <title>

  tags in HTML
• NO

  <meta name="description">

  tags
• NO

  <meta property="og:*">

  tags
• NO

  <link rel="icon">

  tags

Manifest:

• Homepage page with

  "path": "/"

  exists
• CMS templates use flat

  cmsTemplates

  keys (NOT nested, NOT

  collections

  )
• Paths match original site URLs

Templates:

• Index templates have

  {{#each}}

  loops
• Detail templates have CMS tokens (

  {{name}}

  ,

  {{{body}}}

  , etc.)
• Rich text fields use triple braces

  {{{field}}}

• All

  {{#each}}

  have matching

  {{/each}}

• All

  {{#if}}

  have matching

  {{/if}}

• Static UI images use

  /public/

  paths
• Content images use CMS tokens with

  {{#if}}

  wrappers

Static Pages:

• data-edit-key

  on every editable text element
• Keys are unique across the entire site
• Forms have

  data-form-name

  and

  action="/_forms/{name}"

• Original form JavaScript handlers removed or replaced

Assets:

• All HTML asset paths use

  /public/

  prefix
• CSS

  background-image

  and font

  url()

  paths use

  /public/

  prefix
• External URLs (Google Fonts, CDNs) unchanged

Validation:

fastmode validate manifest manifest.json
fastmode validate template <each-template> -t <type> [-c <collection>]
fastmode validate package site.zip

Error Handling & Exit Codes

All commands exit with code 0 on success and code 1 on failure.

Commands that exit 1

schema sync

items create -f

validate *

schema sync

items create -d

items update -d

validate manifest

validate template

validate package

deploy

status

--confirm

items delete

Error Messages

Error: No project specified.
Use -p <id-or-name>, set FASTMODE_PROJECT env var, or run: fastmode use <project>

Error: File not found: schema.json

Error: Invalid JSON in --data argument

Error: Deletion requires the --confirm flag. This action cannot be undone.

Authentication Errors

Most commands auto-trigger

fastmode login

1. Run

   fastmode login

   manually
2. Complete the browser flow
3. Retry the command

File Locations

~/.fastmode/credentials.json

login

~/.fastmode/config.json

use

Both files have restricted permissions (0o600 — owner read/write only).

Notes

• All project-scoped commands use your default project (set with

  fastmode use

  ). Override with

  -p <name-or-id>

  .
• Item data (

  -d

  ) must be valid JSON. For complex data, write a file and use

  -f data.json

  .
• Rich text fields accept HTML content (e.g.

  <p>

  ,

  <h2>

  ,

  <ul>

  ,

  <a>

  ). Always use triple braces in templates.
• Relation fields require item IDs (UUIDs). Use

  fastmode items relations

  to find available IDs.
• The

  --draft

  flag creates unpublished items. Use

  --publish

  /

  --unpublish

  to change status.
• Every site gets free hosting, free SSL, and a

  .fastmode.ai

  subdomain. Custom domains can be configured.
• After deploying or making content changes, always run

  fastmode status

  to verify the build succeeded.
• Use

  fastmode examples <type>

  and

  fastmode guide [section]

  for built-in documentation and code snippets.

Package Provenance

• npm package: fastmode-cli
• Source code: github.com/arihgoldstein/fastmode-mcp
• Website: fastmode.ai
• Author: Arih Goldstein
• License: MIT