Docs / Building Your Site / Deploying with the CLI
Back to FastMode

Deploying with the CLI

Overview

The FastMode CLI gives you a complete deploy workflow from the terminal: create your site package, validate it, deploy, and monitor the build. This guide walks through the end-to-end process.

If you haven't installed the CLI yet, see CLI Setup first.

Step 1: Build Your Package

A FastMode deployment package is a .zip file with this structure:

site.zip
├── manifest.json              # Defines pages and CMS templates
├── pages/                     # Static HTML pages
│   ├── index.html             # Homepage (required)
│   ├── about.html
│   └── contact.html
├── templates/                 # CMS-powered templates
│   ├── posts_index.html       # Collection listing page
│   └── posts_detail.html      # Single item page
└── public/                    # ALL static assets
    ├── css/style.css
    ├── js/main.js
    └── images/logo.png

Key rules:

  • manifest.json must be at the root of the zip
  • All static assets (CSS, JS, images, fonts) must go in public/
  • Reference assets with /public/ prefix: <link href="/public/css/style.css">
  • A homepage with path / is required

For full details on folder structure, see Package Structure. For manifest configuration, see Manifest Reference. For template tokens, see Template Syntax.

Step 2: Validate Before Deploying

Always validate your package before deploying. This catches errors that would cause the build to fail.

Validate the Full Package

fastmode validate package site.zip

This checks everything: manifest structure, all templates for correct token syntax, folder layout, and asset references. If there are errors, fix them before deploying.

Validate Individual Files

You can also validate files individually during development:

# Check manifest
fastmode validate manifest manifest.json

# Check a static page
fastmode validate template pages/index.html -t static_page

# Check collection templates
fastmode validate template templates/posts_index.html -t custom_index -c posts
fastmode validate template templates/posts_detail.html -t custom_detail -c posts

# Validate against your actual schema (catches missing fields)
fastmode validate template templates/posts_detail.html -t custom_detail -c posts -p "My Site"

All validation commands exit with code 1 on errors, so you can use them in scripts.

Step 3: Deploy

fastmode deploy site.zip

This uploads your package and waits for the build to complete. You'll see progress updates while the build runs, then a final result:

  • Success: Shows build duration, pages rendered, and version number
  • Failure: Shows the error message and build logs so you can diagnose the issue

Deploy Options

FlagWhat it does
--forceDeploy even if the project has GitHub auto-deploy connected. Without this, the CLI blocks to prevent conflicts.
--no-waitUpload only — don't wait for the build. Useful for fire-and-forget. Check results later with fastmode status.
--timeout <ms>How long to wait for the build (default: 120000ms = 2 minutes). Increase for large sites.

Step 4: Check Build Status

After deploying, always verify the build succeeded:

fastmode status

This shows:

  • Whether the site is currently building
  • The latest deploy status (success, failed, or in progress)
  • Published version number
  • Pages rendered and files uploaded
  • Error details and build logs if the build failed

The command exits with code 1 if the latest deploy failed, so you can use it in scripts.

View Deployment History

fastmode deploys
fastmode deploys --limit 5

Shows past deployments with their status, version, duration, and any errors.

When a Build Fails

If the build fails, here's how to diagnose and fix it:

1. Get the Error Details

fastmode status

The output includes the error message and build logs. Common causes:

  • Template errors — Unbalanced {{#each}}/{{/each}} or {{#if}}/{{/if}} tags
  • Invalid tokens — Referencing fields that don't exist in the schema
  • Missing files — manifest.json references a file that's not in the zip
  • Wrong asset paths — CSS/JS/images not in public/ or paths missing /public/ prefix
  • Manifest format — Using nested cmsTemplates instead of flat keys

2. Fix the Issue

Edit your source files based on the error message.

3. Validate and Re-deploy

fastmode validate package site.zip
fastmode deploy site.zip

Content Changes Also Trigger Builds

When you create, update, or delete CMS items via the CLI, the site rebuilds automatically to reflect the content changes. After making content edits, check that the rebuild succeeded:

# Make content changes
fastmode items create posts -n "New Post" -d '{"title": "New Post", "body": "<p>Content here.</p>"}'

# Verify the rebuild succeeded
fastmode status

Complete Example

Here's the full workflow from project creation to live site:

# Setup
fastmode login
fastmode projects create "My Blog"
fastmode use "My Blog"

# Define content structure
fastmode schema sync -f schema.json

# Add content
fastmode items create posts -n "First Post" -d '{"title": "First Post", "body": "<p>Hello world!</p>"}'
fastmode items create team -n "Jane Doe" -d '{"role": "Founder", "bio": "<p>CEO and founder.</p>"}'

# Validate and deploy
fastmode validate package site.zip
fastmode deploy site.zip

# Verify the build
fastmode status

Your site is now live at my-blog.fastmode.ai.

Tips

  • Always validate first. fastmode validate package site.zip catches most issues before they hit the build server.
  • Always check status after deploy. Even if the upload succeeds, the build can still fail.
  • Use --force carefully. If your project has GitHub auto-deploy, CLI deploys may be overwritten on the next git push.
  • Rich text uses triple braces. In templates, {} renders HTML correctly. Double braces escape it.
  • Relation fields need UUIDs. Run fastmode items relations <collection> to find the IDs.

Related Docs

Built in Fast Mode