> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primo.build/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CardGroup cols={2}>
  <Card title="Start local" icon="laptop-code">
    Run `primo new` to create a workspace on your machine. Build the site locally, then deploy when ready.
  </Card>

  <Card title="Start deployed" icon="cloud-arrow-up">
    Deploy Primo to Railway or a VPS first, then pull it down to your laptop with `primo pull` for local edits.
  </Card>
</CardGroup>

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

<Tabs>
  <Tab title="Start local">
    ## Path 1: Build locally, deploy later

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

    <Steps>
      <Step title="Install the CLI">
        ```bash theme={null}
        npm install -g primo-cli
        ```

        Requires Node.js 18+.
      </Step>

      <Step title="Create a site">
        ```bash theme={null}
        primo new my-site
        ```

        This scaffolds a workspace and starts the local CMS at `http://my-site.localhost:3000`.

        <Tip>
          Open `http://my-site.localhost:3000/admin` to use the visual editor. Edits round-trip to your files in real time.
        </Tip>
      </Step>

      <Step title="Edit blocks and pages">
        Open the workspace in your editor:

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

        Edit `blocks/<name>/component.svelte` in your editor — the CMS reflects changes immediately. See [Local Development](/cli/local-development) for the full workflow including `--author` modes.
      </Step>

      <Step title="Let AI agents help">
        For Claude Code, Cursor, or other agents, install the MCP server so they can validate edits and scaffold blocks correctly:

        ```bash theme={null}
        npm install -g primo-mcp
        claude mcp add --transport stdio primo -- primo-mcp
        ```

        See the [MCP server reference](/reference/mcp-server) for details.
      </Step>

      <Step title="Deploy when ready">
        ```bash theme={null}
        primo deploy
        ```

        Interactive picker for Railway or Fly.io. See [Deploy with the CLI](/cli/deploy) for other options.
      </Step>
    </Steps>
  </Tab>

  <Tab title="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.

    <Steps>
      <Step title="Self-host Primo">
        Pick one:

        * **[Railway](https://railway.com/deploy/primo?referralCode=RCPU7k)** — one-click deploy with persistent storage
        * **[Fly.io](https://fly.io)** — generous free tier
        * **Docker / VPS** — `docker run -d -p 8080:8080 ghcr.io/primocms/primo:latest`

        See the [Installation Guide](/getting-started/installation) for full instructions.
      </Step>

      <Step title="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.

        <Tip>
          You can build the entire site in the browser without ever installing the CLI. The CLI is optional.
        </Tip>
      </Step>

      <Step title="Edit content visually">
        Open `https://your-domain.com/admin` and edit pages by clicking on them. See [Using the Editor](/content-management/using-the-editor) for the full visual workflow.

        <Tip>
          The admin panel is always at `/admin/` on your domain. Your published site lives at the root.
        </Tip>
      </Step>

      <Step title="(Optional) Pull to your laptop">
        Once you want to edit blocks in code or hand things off to AI agents:

        ```bash theme={null}
        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](/cli/sync) for the sync model.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## What's Next

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="lightbulb" href="/getting-started/core-concepts">
    Sites, page types, pages, blocks, fields
  </Card>

  <Card title="Build from Scratch" icon="hammer" href="/building-sites/your-first-site">
    Walk through building a complete site end-to-end
  </Card>

  <Card title="Local Development" icon="laptop-code" href="/cli/local-development">
    `primo dev`, author modes, uploads folder
  </Card>

  <Card title="Invite Collaborators" icon="users" href="/collaboration/inviting-collaborators">
    Hand the site off to non-technical editors
  </Card>
</CardGroup>