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. You sign in once with your account, pick any of your sites from a live dashboard, and the CLI pulls each one down as real local files — models, templates, content, and assets — 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, the multi-site dashboard, what it sets up locally, the AI-agent instruction files it injects, building and deploying from the workspace, and the sync mechanics.

What cms-sync Is

cms-sync is a Node CLI distributed as @sleekcms/sync on npm and run through npx. The sleekcms command comes from the install script: it adds a small launcher script that runs npx @sleekcms/sync, so every launch fetches the latest version — the npm package itself doesn't install a sleekcms binary. The CLI does three things:

1. Pulls any of your sites — models, templates, content (including markdown bodies), CSS, JS, plus the workspace's AI-agent reference files — each into its own local folder.
2. Watches those folders. Every save streams the changed files to the SleekCMS API; the server validates and rebuilds.
3. Runs a live dashboard where you manage it all: per-site sync status and logs, pause/resume, build a preview or deploy live, open the result in your browser, create new sites, and jump into the workspace with your editor or AI agent.

You authenticate as a user — sign in once and every site you can access, across all your organizations, shows up. There are no per-site tokens to copy.

Quickstart

1. Install — one command. It sets up Node.js if needed and adds a small sleekcms launcher script that always runs the latest version of the CLI:

# macOS / Linux
curl -fsSL https://app.sleekcms.com/install.sh | sh

# Windows (PowerShell)
irm https://app.sleekcms.com/install.ps1 | iex

2. Run it and sign in:

sleekcms

Enter your email, then the one-time code that lands in your inbox. That's the whole login — the credential is saved (owner-only) under ~/SleekCMS/auth.json, so future launches go straight to the dashboard until you log out with q.

3. Pick a site — or create one. The dashboard lists every site you can reach. Select one with ↑/↓ and press s to start syncing it; the CLI pulls the files into a local workspace and starts watching. Press n instead to create a brand-new blank site and sync it immediately. A brand-new account drops straight into the create-site prompt.

From there, press one of the numbered launcher keys to open the workspace in your editor or agent, and every save syncs automatically.

The Dashboard

sleekcms runs as a live, pm2-style dashboard: a site workspaces list on the left (every site across your orgs, with the currently synced ones on top), the selected site's detail on the right — status, workspace path, last sync, latest build and its URL — and a scrollable per-site log pane below.

Multiple sites can sync at the same time — each gets its own workspace, watcher, and log stream.

Creating a Site from the CLI

Press n, type a name, and hit enter. If your account belongs to several organizations you pick one first; a brand-new account gets a default organization created automatically. The blank site is created and starts syncing immediately — ready for an AI agent to build it out.

Installing Without the Script

The install script is just a convenience — the sleekcms command it adds is a tiny launcher that runs npx @sleekcms/sync. If you already have Node.js (v18+), you can skip the script and run the same thing directly:

npx -y @sleekcms/sync@latest

The npm package doesn't install a sleekcms command of its own — the name comes from the launcher script (or an alias you define yourself).

Command Options

What Gets Created Locally

Workspaces live under ~/SleekCMS/ by default — one folder per site, named after the site. Each contains the full site structure plus the AI-agent reference files and a standalone build script:

~/SleekCMS/<site-name>-<id>/
├── AGENT.md                              Generic agent reference
├── CLAUDE.md                             Claude / Claude Code reference
├── .vscode/
│   ├── copilot-instructions.md           GitHub Copilot in VS Code
│   └── settings.json                     Editor settings
├── build.mjs                             Build/deploy script (see below)
├── sync-errors.log                       Failed-save log — present only while something is failing
├── .cache/                               Sync and build state, managed by the CLI
│
└── 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 local layout of the same files you edit in the online coding environment. Locally, templates nest under src/views/ and assets under src/public/ — the online editor presents them as top-level pages/, blocks/, entries/, layouts/, css/, and js/ folders, and assets are served from /css/... and /js/... either way. 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. When it creates a workspace, the CLI writes 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.

If Claude Code is installed, it even gets its own numbered launcher in the dashboard — one key opens a terminal in the workspace with the agent already running.

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.

Building and Deploying from the Workspace

Every workspace ships with build.mjs, a self-contained script (no npm install needed) that compiles the whole site:

node build.mjs            # build + validate; prints the PREVIEW url, or the build errors
node build.mjs --deploy   # build + publish LIVE; prints the live url

On success it prints ✅ Build … → <url>; on failure it prints ❌ Build failed: followed by the errors to fix. Every run is also appended to build.log in the workspace. The script's output is plain stdout, so AI agents can run it and read the result directly.

The dashboard drives the same script: b builds a preview, B deploys live, and the site's detail panel shows the build status and URL as it progresses (o opens it in your browser). Builds triggered by an agent inside the workspace surface in the dashboard too.

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. Changed files are pushed to the SleekCMS API, which applies them in dependency order (models before templates and content).
3. The server validates each file and rebuilds; the preview reflects the change.

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

The CLI keeps sync state in the workspace's .cache/ folder tracking what the server already has. Only real diffs are pushed, so incidental saves (a formatter pass, whitespace cleanup) don't trigger redundant API calls. Empty files are skipped.

Saving never rewrites your local files — the server applies its own processing (resolving image shortcuts, filling defaults) on its side, and you see that server-side form only when a workspace is freshly pulled.

If a save fails validation, the file gets a line in sync-errors.log at the workspace root (<path>: <error>); the line disappears when the file syncs cleanly, and the log file itself is removed once nothing is failing.

Pull vs. Push

• Push happens automatically on every save in the local workspace.
• Pull happens when a site is started (s). To force a completely fresh copy — for example after heavy editing in the CMS dashboard — disconnect the site (d) and start it again.

Workspace Lifecycle

When you quit the CLI (ctrl+c) or disconnect a site (d), cms-sync stops watching and cleans up that site's src/ files and sync cache. This is intentional — your edits already live on the server, and the next start pulls a fresh copy, so the local copy can never drift. The workspace shell (the agent reference files, build.mjs, editor settings) stays in place.

This means:

• A save pushes; an unsaved edit is lost on exit.
• Pausing (p) is different from disconnecting: a paused site keeps all its files on disk and just stops pushing until you resume.
• If you want a Git-tracked snapshot of the site, commit while the session is running — src/ is cleaned up when it ends. The server is the source of truth either way: git push doesn't push to SleekCMS, the CLI does.

Pairing with VS Code, Cursor, and Other Editors

The dashboard's numbered launcher keys open the selected site's workspace in whatever it detects on your machine — a terminal window, iTerm, VS Code, Cursor, or an AI agent like Claude Code. 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 (including treating .model files as JavaScript) and the Copilot instructions file. Other editors don't need any configuration.

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 — sleekcms, press s on the site, open it in VS Code/Cursor with a launcher key, do the edit, quit when done. Every save pushes; the site files clean up afterward.

Building a new site from a prompt — Press n, name the site, open the fresh workspace in Claude Code or Cursor, and describe the site. The agent generates models, templates, and content, and every save goes live as it lands.

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

Checking the result — b for a preview build, o to open it. B when it's ready to go live.

Troubleshooting

Prerequisites

• Nothing, if you use the install script — it sets up Node.js automatically when it's missing.
• Running via npx directly requires Node.js v18 or later.
• A SleekCMS account. Sign-in is a one-time code sent to your email — there are no tokens to create or manage.

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.