Local Workspace (cms-sync)

The browser-based coding environment is enough for many edits. For substantial template work, multi-file refactors, or building entire sites with AI agents, drop into a local workspace using cms-sync, the SleekCMS CLI. It downloads your site's models, templates, content, and assets to a local folder, watches for changes, and pushes saves back to SleekCMS in real time. You edit in VS Code, Cursor, or any editor; the CLI handles the round trip.

This page covers what cms-sync is, the one-line install-and-run, what it sets up locally, the AI-agent instruction files it injects, and the sync mechanics.

What cms-sync Is

cms-sync is a Node CLI distributed as @sleekcms/sync on npm. It does three things:

1. Pulls your full site state — models, templates, content (including markdown bodies), CSS, JS, and the workspace's AI-agent reference files — into a local folder.
2. Watches the folder. Every save streams the changed file to the SleekCMS API; the server validates and rebuilds.
3. Cleans up on exit. Workspaces are ephemeral — your edits live on the server, and the next run re-fetches a fresh copy.

The package is @sleekcms/sync; the binary it installs is sleekcms. The same CLI is what the Set Up Local Workspace option in the SleekCMS builder hands you on a copy-paste command.

Quickstart

The fastest way to get started — no install, run directly with npx:

npx @sleekcms/sync@latest -t <your-auth-token>

Grab the auth token from the Builder area of your site in the SleekCMS dashboard (the Set Up Local Workspace option shows the exact command with your token pre-filled).

That's the whole setup. The CLI:

1. Authenticates and fetches your site to a local folder named after the site.
2. Writes AGENT.md, CLAUDE.md, and .vscode/copilot-instructions.md so any AI agent picks up the SleekCMS reference.
3. Offers to open the folder in VS Code or Cursor if either is detected.
4. Starts watching. Every save pushes to SleekCMS within seconds.

While watching, two keys are bound:

Install Globally (Optional)

If you'll use the CLI often, install once globally and drop the npx prefix:

npm install -g @sleekcms/sync
sleekcms -t <your-auth-token>

The global binary is sleekcms. Both npx @sleekcms/sync and sleekcms accept the same options.

Command Options

A non-default environment is encoded in the token itself, so you usually only need --token.

What Gets Created Locally

The first run creates a workspace folder with the full site structure plus the AI-agent reference files:

<site-name>/
├── AGENT.md                              Generic agent reference
├── CLAUDE.md                             Claude / Claude Code reference
├── .vscode/
│   ├── copilot-instructions.md           GitHub Copilot in VS Code
│   └── settings.json                     Editor settings
│
└── src/
    ├── models/
    │   ├── pages/<key>.model             Page schemas
    │   ├── entries/<key>.model           Entry schemas
    │   └── blocks/<key>.model            Block schemas
    │
    ├── views/
    │   ├── pages/<key>.ejs               Page templates
    │   ├── entries/<key>.ejs             Entry templates
    │   ├── blocks/<key>.ejs              Block templates
    │   └── layouts/<name>.ejs            Layout wrappers
    │
    ├── content/
    │   ├── pages/<key>.json              Single page content
    │   ├── pages/<key+>/<slug>.json      Collection page items
    │   ├── pages/<key+>/<slug>.md        Markdown collection items (when the model qualifies)
    │   ├── entries/<key>.json            Single entry content
    │   ├── entries/<key+>.json           Collection entry content
    │   └── images.json                   Site-level reusable images
    │
    └── public/
        ├── css/<name>.css                Stylesheets (tailwind.css is special)
        └── js/<name>.js                  Scripts

This is the same file layout used everywhere in the SleekCMS reference. Edits to any of these files sync back to the CMS.

AI-Agent Workflow

The headline feature of cms-sync — beyond plain local editing — is that it sets up your workspace for AI agents to build and maintain your site. On every run, the CLI injects three reference files:

Each file contains the full SleekCMS reference: file naming conventions, model syntax, template helpers, content shapes, the image-shortcut convention, the rules for what's allowed where. An AI session opened in this workspace knows your site — it doesn't have to be re-taught how the platform works.

Generating a Site with AI

Open the workspace in Cursor, VS Code with Copilot, or Claude Code, and describe the site you want:

Build a portfolio site with:
- A home page with a hero section, featured projects, and a contact form
- A blog with individual post pages
- A shared header and footer
- Tailwind CSS styling
- SEO meta tags on every page

The AI creates models, templates, layouts, content, and assets in the right places. As each file lands on disk, the watcher pushes it to SleekCMS. The site is live before the agent finishes summarizing what it built.

Editing an Existing Site

The same instruction files apply when an agent is making changes to an existing site. Ask it to add a dark-mode toggle, refactor a block, generate ten more blog posts, or build out a new page type — it has the full SleekCMS reference plus the existing site's files for context.

The site is plain files — EJS, JSON, CSS, JS. No proprietary format, no lock-in. Anything the AI writes is the same kind of file you'd write by hand.

How Sync Works

After the initial fetch, cms-sync runs a local file watcher (debounced to batch rapid edits). When you save a file:

1. The watcher detects the change.
2. The file is classified — model, template, content record, CSS, or JS.
3. It's pushed to the SleekCMS API in dependency order (models first, then templates, then content).
4. The SleekCMS server validates, rebuilds, and the preview reflects the change.

Your editor → save → watcher → SleekCMS API → rebuild → preview

The CLI keeps a local .cache/ folder tracking the server-known state of each file. Only real diffs are pushed, so no redundant API calls on incidental saves (formatter pass, whitespace cleanup, etc.).

Pull vs. Push

The sync is two-way:

• Push happens automatically on every save in the local workspace.
• Pull happens on startup (initial fetch) and on demand via the r key. Use r after editing content in the SleekCMS dashboard to get those changes into the local files.

Ephemeral Workspaces

By default, the workspace folder is wiped when the CLI exits (Ctrl+C or x). This is intentional — your edits already live on the server, and a fresh re-run downloads them again. There's no risk of the local copy drifting from the server.

This means:

• Don't store edits-in-progress in the workspace without saving them. A save pushes; an unsaved edit is lost on exit.
• If you want a persistent local copy (for a Git-tracked snapshot, for example), use -p <dir> to write to a directory you control and skip the auto-cleanup. The CLI still pushes on save; the folder just persists between runs.

Pairing with VS Code, Cursor, Other Editors

When the CLI starts, it offers to open the workspace in VS Code or Cursor if either is detected on your PATH. You can also open the folder manually in any editor — vim, Zed, Sublime, JetBrains, anything that opens a folder. cms-sync watches the filesystem, not your editor, so editor choice is purely personal.

The .vscode/ folder is created automatically with sensible defaults and the Copilot instructions file. Other editors don't need any configuration — they just open the folder.

Common Workflows

Single small edit — Open the SleekCMS browser editor directly; don't bother spinning up the CLI for one template tweak.

Multi-file refactor — Run cms-sync, open in VS Code/Cursor, do the multi-file edit, exit. The CLI ensures every save pushes; the workspace cleans up afterward.

Building a new site from a prompt — Run cms-sync on an empty (or near-empty) site. Open in Cursor or Claude Code. Describe the site. Let the agent generate models, templates, and content.

Maintaining an AI-built site — Same workspace, any AI session. The instruction files in the workspace mean any new agent session — today, next week, next year — picks up the same site context.

Local Git history — Use -p <dir> pointed at a Git-tracked folder. Each run pulls the latest server state into the folder; you commit between runs to keep a versioned history. Note that the server is the source of truth — git push doesn't push to SleekCMS, the CLI does.

Troubleshooting

For build-side issues (template errors, model mismatches, image resolution failures), check sync-errors.log in the workspace root — this is the same error log surfaced in the CMS, mirrored locally.

Prerequisites

• Node.js v16 or later — install via nodejs.org, Homebrew (brew install node), or your distribution's package manager.
• A SleekCMS auth token — generated in the site's Builder area, available on the Set Up Local Workspace dialog.

That's it. No global config files, no environment variables to set, no project bootstrapping.

What's Next

• Online Coding Environment — The browser-based editor for quick edits.
• Model Templates — The template files you'll be editing.
• Layout — The wrapper template.
• Template Context and Data Access — The complete API surface for templates.
• Site Builder Architecture — How the templates you edit locally compose during a build.