CLI Overview

The Primo CLI (primo-cli) lets you build and edit Primo sites from local files using your own editor and version control. It runs a local CMS, syncs according to your chosen author mode, and provides commands for deployment. By default, a push saves a hosted draft. Publish it separately with primo publish, or combine both steps with primo push --publish.

The CLI is optional. You can still build everything in the in-browser editor — the CLI is for developers who prefer working in files and Git.

Installation

npm install -g primo-cli

Requirements:

A supported Node.js LTS release, version 22.13 or later. The CLI’s interactive dependencies do not support Node 18.
For primo deploy: Railway CLI or Fly.io CLI

Quick Start

# Create a workspace, then a site inside it
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 (skip with --no-mcp). In an interactive terminal, primo new then starts the local CMS, with the site at http://my-site.localhost:3000. From scripts and CI, or with --skip-dev, it only creates the files; start the CMS yourself with primo dev.

Workspace Structure

A Primo workspace contains one or more sites and a shared block library:

workspace/
├── server.yaml          # Port, site groups, server-level config
├── AGENTS.md            # Guide for AI agents working in this workspace
├── CLAUDE.md            # Imports AGENTS.md for Claude Code
├── library/             # Shared blocks reusable across sites
│   ├── groups.yaml      # Library groups and their folders
│   ├── marketing/
│   │   └── hero/
│   └── shared/
│       └── footer/
└── sites/
    ├── site-one/
    │   ├── site.yaml    # Site name, id, group
    │   ├── blocks/      # Site-specific blocks
    │   ├── pages/
    │   ├── page-types/
    │   ├── site/        # Site-wide fields, head, foot
    │   └── uploads/     # Images and files synced to the CMS
    └── site-two/
        └── site.yaml

Each site is served on its own subdomain in dev: site-one.localhost:3000, site-two.localhost:3000.

Command Summary

Command	What it does
`primo init [name]`	Initialize a new workspace
`primo new [name]`	Create a new site (and start the CMS in an interactive terminal; `--skip-dev` to only create files)
`primo add <site>`	Register a hand-made `sites/` folder with the CMS (stop `primo dev` first)
`primo dev`	Run the local CMS with file/CMS sync
`primo status`	Show local workspace state; `--hosted` checks hosted publication status
`primo preview --dir sites/<name>`	Rebuild a site’s preview (needs `primo dev` running)
`primo pull <server>`	Pull a hosted server into local files
`primo push <server>`	Upload local changes as a hosted draft; `--publish` also publishes
`primo publish [server]`	Publish the hosted draft without uploading local files
`primo library pull/push`	Sync just the shared block library
`primo login <server>`	Authenticate with a hosted instance
`primo deploy`	Deploy the workspace to Railway or Fly.io
`primo build -d sites/<name>`	Build one site as static files (default output: `_site/`)
`primo validate`	Check site structure for errors (from the workspace root, checks every site)
`primo mcp install`	Connect your agent client to the Primo MCP tools

When to Use Which Command

You want to…	Use
Let collaborators edit content from a CMS UI	`primo deploy`
Export static HTML and CSS	`primo build` (limitations)
Sync local edits to an existing hosted server	`primo push`
Publish saved changes on a compatible hosted server	`primo publish`
Pull a hosted server’s content into Git	`primo pull`

Next Steps

Local Development

Run the local CMS and learn the file/CMS sync model

Sync with a Hosted Server

Use primo push and primo pull against a deployed instance

Deploy

Deploy your workspace to Railway, Fly.io, or any static host

MCP Server

Let AI agents work inside your Primo workspace safely

Getting Started

Building Sites

CLI

Collaboration

Content Management

Dashboard

Reference

Installation

Quick Start

Workspace Structure

Command Summary

When to Use Which Command

Next Steps

Local Development

Sync with a Hosted Server

Deploy

MCP Server

​Installation

​Quick Start

​Workspace Structure

​Command Summary

​When to Use Which Command

​Next Steps

Local Development

Sync with a Hosted Server

Deploy

MCP Server

Installation

Quick Start

Workspace Structure

Command Summary

When to Use Which Command

Next Steps