fastmode

免费创建、部署和托管网站。从头开始构建一个完整的网站，并将其部署到具有免费托管、免费 SSL 和自定义域的云中 — 所有这些都通过终端进行。完整的 CMS 包括：管理博客文章、团队成员、页面、产品、投资组合、服务、推荐、常见问题解答或任何结构化内容。添加和编辑 CMS 内容、同步数据库架构、验证 HTML 模板、邀请客户访问白标签门户以及推送实时部署。将任何现有 HTML 网站转换为 CMS 支持的网站。一次性浏览器登录 OAuth，然后每项操作都完全在终端中运行 - 专为 AI 代理在几分钟内从零到可公开访问的网站而设计。

## 概述（中文）

免费创建、部署和托管网站。从头开始构建一个完整的网站，并将其部署到具有免费托管、免费 SSL 和自定义域的云中 — 所有这些都通过终端进行。完整的 CMS 包括：管理博客文章、团队成员、页面、产品、投资组合、服务、推荐、常见问题解答或任何结构化内容。添加和编辑 CMS 内容、同步数据库架构、验证 HTML 模板、邀请客户访问白标签门户以及推送实时部署。将任何现有 HTML 网站转换为 CMS 支持的网站。一次性浏览器登录 OAuth，然后每项操作都完全在终端中运行 - 专为 AI 代理在几分钟内从零到可公开访问的网站而设计。

## 原文

# 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](#end-to-end-workflow)
2. [CRITICAL: Before You Build Anything](#critical-before-you-build-anything)
3. [Website Analysis](#website-analysis-do-this-before-writing-code)
4. [Command Reference](#command-reference)
5. [Project Resolution](#project-resolution)
6. [Schema & Field Types](#schema--field-types)
7. [Content Items](#content-items)
8. [Client Portal Management](#client-portal-management)
9. [Package Structure](#package-structure)
10. [Manifest Format](#manifest-format)
11. [Template Syntax](#template-syntax) (includes SEO rules, image handling, forms, inline editing)
12. [Deployment & Build Status](#deployment--build-status)
13. [Validation](#validation)
14. [Common Mistakes & How to Fix Them](#common-mistakes--how-to-fix-them)
15. [Pre-Deployment Checklist](#pre-deployment-checklist)
15. [Error Handling & Exit Codes](#error-handling--exit-codes)

---

## End-to-End Workflow

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

```bash
# 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

```bash
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

| Requirement | How to Get It |
|-------------|---------------|
| Project selected/created | `fastmode projects` / `fastmode projects create` |
| Default set | `fastmode use "Project Name"` |
| Schema known (existing) | `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

```bash
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

```bash
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

```bash
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

```bash
fastmode items list <collection>                          # List all items
fastmode items list posts --limit 10 --sort publishedAt --order desc
fas