FastMode CLI — Complete Agent Reference

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

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 [email protected]         # Invite with default permissions
fastmode clients invite [email protected] -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 file and sync it:

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 and fieldsToAdd in the same file. Duplicate collections and fields are automatically skipped.

Available Field Types

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" — this will NOT work. CORRECT: "author": "550e8400-e29b-41d4-a716-446655440000" — use the UUID.

Content Items

Creating Items

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

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"}'

Update is a partial merge. Only the fields you provide in -d are changed. All other fields remain as they are.

Deleting Items

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

The --confirm flag is required. Without it, the command refuses to run and exits with code 1. This is a safety measure — deletion is permanent and cannot be undone.

Always ask the user for confirmation before deleting.

Draft / Publish Mechanics

• 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

Default permissions (used when none specified): cms.read, cms.write, editor, forms.read

Inviting Clients

# Invite with default permissions
fastmode clients invite [email protected]

# Invite with a name
fastmode clients invite [email protected] -n "Jane Smith"

# Invite with specific permissions
fastmode clients invite [email protected] -n "Jane Smith" --permissions cms.read,forms.read

# Invite with all permissions
fastmode clients invite [email protected] --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 shows the access ID for each client — you need this ID to update permissions or revoke access.

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 and you set --permissions cms.read, they will ONLY have cms.read.

Revoking Access

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

The --confirm flag is required. Without it, the command refuses to run.

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 to get the invitation ID.

Typical Workflow

# 1. Invite your client
fastmode clients invite [email protected] -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 file with this exact structure:

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');