Quickstart

Build your first Primo site in 5 minutes — locally with the CLI or deployed and pulled down.

Primo has two starting points. Pick the one that matches how you work:

Start local

Run primo init and primo new to create a workspace on your machine. Build the site locally, then deploy when ready.

Start deployed

Deploy Primo to Railway or a VPS first, then pull it down to your laptop with primo pull for local edits.

Both paths land at the same place: a workspace on disk that you can edit with code, AI agents, or the visual CMS.

Start local

Path 1: Build locally, deploy later

Best for: starting from scratch, prototyping, or experimenting before committing to a host.

1. Install the CLI

   npm install -g primo-cli
   

   Requires Node.js 18+.

2. Create a workspace and a site

   primo init my-workspace
   cd my-workspace
   primo new my-site
   

   primo init creates the workspace and offers to connect your AI agent to the Primo MCP tools. primo new creates the site and starts the local CMS. If the port is busy, Primo picks the next free one and prints the URLs it’s using.

   Open http://my-site.localhost:3000/admin/site to see the site in the visual editor. File edits show up there immediately. By default your files are the source of truth and the editor is read-only; see authoring modes to edit in the CMS instead.

3. Edit blocks and pages

   Open the workspace in your editor:

   my-workspace/
   ├── server.yaml
   ├── AGENTS.md
   ├── library/
   └── sites/my-site/
       ├── site.yaml
       ├── blocks/
       ├── pages/
       ├── page-types/
       └── site/
   

   Edit sites/my-site/blocks/<name>/component.svelte in your editor — the CMS reflects changes immediately. See Local Development for the full workflow including --author modes.

4. Let AI agents help

   The workspace includes an AGENTS.md guide (and a CLAUDE.md that imports it), so Claude Code, Cursor, and other agents know how Primo sites are structured. If you skipped MCP setup during primo init, connect the Primo MCP tools so agents can validate edits and scaffold blocks correctly:

   primo mcp install
   

   See the MCP server reference for details.

5. Deploy when ready

   primo deploy
   

   Interactive picker for Railway or Fly.io. See Deploy with the CLI for other options.

Start deployed

Path 2: Deploy first, pull down to edit

Best for: when you want a shared server from day one — collaborators on a CMS UI, agents pulling/pushing files, your team editing visually.

1. Self-host Primo

   Pick one:

   • Railway — one-click deploy with persistent storage
   • Fly.io — generous free tier
   • Docker / VPS — docker run -d -p 8080:8080 ghcr.io/primocms/primo:latest

   See the Installation Guide for full instructions.

2. Create a site in the browser

   Visit your deployed URL and follow the site creation wizard. Pick a starter (Blog, Portfolio, Restaurant, Business, or Blank) or clone an existing site.

   You can build the entire site in the browser without ever installing the CLI. The CLI is optional.

3. Edit content visually

   Open https://your-domain.com/admin and edit pages by clicking on them. See Using the Editor for the full visual workflow.

   The admin panel is always at /admin/ on your domain. Your published site lives at the root.

4. (Optional) Pull to your laptop

   Once you want to edit blocks in code or hand things off to AI agents:

   npm install -g primo-cli
   primo login https://your-domain.com
   primo pull https://your-domain.com
   

   You’ll get a full workspace on disk. Push changes back with primo push. See Push and Pull for the sync model.

5. Publish changes

   Browser edits auto-save. To publish, click Publish (or press ⌘P / Ctrl+P). Primo compiles your blocks, generates static HTML, and serves it from your domain.

What’s Next

Core Concepts

Sites, page types, pages, blocks, fields

Build from Scratch

Walk through building a complete site end-to-end

Local Development

primo dev, author modes, uploads folder

Invite Collaborators

Hand the site off to non-technical editors