primo-cli 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # Primo CLI
 
-Local development CLI for [Primo](https://primocms.org) - build and edit sites with a visual CMS.
+Local development CLI for [Primo](https://primo.page) - build and edit sites with a visual CMS.
 
 ## Installation
 
@@ -15,19 +15,30 @@ npm install -g primo-cli
 primo new my-site
 
 # This starts the local CMS automatically
-# Edit at: http://my-site.localhost:3000/admin/site
-# Preview at: http://my-site.localhost:3000/
+# It scaffolds a workspace like:
+# ./server.yaml
+# ./library/
+# ./sites/my-site/
 ```
 
 ## Commands
 
+### `primo init [name]`
+
+Initialize a new Primo workspace (server) in a new folder or the current directory.
+
+```bash
+primo init                   # Initialize in the current directory
+primo init my-workspace      # Create and initialize "my-workspace"
+```
+
 ### `primo new [name]`
 
 Create a new site with starter files.
 
 ```bash
 primo new                    # Interactive prompt for name
-primo new my-site            # Create "my-site" directory
+primo new my-site            # Create "sites/my-site" in the current workspace
 primo new --skip-dev         # Create files without starting CMS
 ```
 
@@ -38,37 +49,73 @@ Start the local CMS server. Watches for file changes and syncs edits from the CM
 ```bash
 primo dev                    # Start in current directory
 primo dev -p 8080            # Use custom port
+primo dev --author files     # Push file edits to the CMS; CMS UI is read-only (default)
+primo dev --author cms       # CMS edits write to files; file edits revert
+primo dev --author both      # Bidirectional sync (beta; CMS edits often lost on conflict)
 ```
 
 ### `primo push`
 
-Push local files to a hosted Primo instance.
+Sync local changes to an existing hosted Primo server. Requires a server you've
+already deployed (run `primo deploy` first) and authenticated against (`primo
+login -s <server-url>`).
 
 ```bash
-primo push -s https://cms.example.com --site abc123
+primo push https://cms.example.com --site abc123
+primo push --only my-site    # Push just one site folder (workspace root)
 primo push --preview         # Preview changes without applying
+primo push --dry-run         # Show what would be sent without making requests
 ```
 
 Options:
 - `-s, --server <url>` - Server URL
 - `--site <id>` - Site ID
+- `--only <slug>` - Push only the named site folder under `sites/` (skips library)
 - `-d, --dir <dir>` - Directory (default: `.`)
 - `-t, --token <token>` - Auth token
 - `--preview` - Preview only
+- `--dry-run` - Show what would be pushed without sending requests
 
 ### `primo pull`
 
-Pull from a hosted Primo instance to local files.
+Pull an entire hosted Primo server — all sites plus the shared library — to local files.
+
+```bash
+primo pull https://cms.example.com
+primo pull https://cms.example.com -o ./my-workspace
+```
+
+Options:
+- `-s, --server <url>` - Server URL (auto-detects local)
+- `-o, --output <dir>` - Output directory (defaults to `./<server-hostname>`)
+- `-t, --token <token>` - Auth token
+
+### `primo library pull`
+
+Pull the shared block library into a workspace root.
 
 ```bash
-primo pull -s https://cms.example.com
-primo pull --site abc123 -o ./my-site
+primo library pull https://cms.example.com
+primo library pull -o ./my-workspace
 ```
 
 Options:
 - `-s, --server <url>` - Server URL (auto-detects local)
-- `--site <id>` - Site ID (interactive if not provided)
-- `-o, --output <dir>` - Output directory (default: `.`)
+- `-o, --output <dir>` - Workspace output directory (default: `.`)
+- `-t, --token <token>` - Auth token
+
+### `primo library push`
+
+Push the local shared block library back to a hosted Primo instance.
+
+```bash
+primo library push https://cms.example.com
+primo library push https://cms.example.com -d ./my-workspace
+```
+
+Options:
+- `-s, --server <url>` - Server URL
+- `-d, --dir <dir>` - Workspace directory containing `library/` (default: `.`)
 - `-t, --token <token>` - Auth token
 
 ### `primo login`
@@ -80,16 +127,30 @@ primo login https://cms.example.com
 primo login https://cms.example.com -e user@example.com
 ```
 
-### `primo publish`
+### `primo deploy`
 
-Deploy your site with CMS to Railway or Fly.io.
+Deploy the entire workspace — all sites under `sites/`, plus `library/` and
+`server.yaml` — as one editable-CMS unit, to Railway or Fly.io. Must be run
+from the workspace root (the directory containing `server.yaml`).
 
 ```bash
-primo publish                # Interactive provider selection
-primo publish -p railway     # Deploy to Railway
-primo publish -p fly         # Deploy to Fly.io
+primo deploy                 # Interactive provider selection
+primo deploy -p railway      # Deploy to Railway
+primo deploy -p fly          # Deploy to Fly.io
+primo deploy --dry-run       # Show what would be deployed without doing anything
 ```
 
+For other hosts (Netlify, Vercel, Cloudflare, GitHub Pages), use `primo build`
+on a single site and deploy the output folder with that host's CLI.
+
+#### Picking the right "going-live" command
+
+| You want to…                                  | Use            |
+| --------------------------------------------- | -------------- |
+| Let collaborators edit content from a CMS UI  | `primo deploy` |
+| Ship a static site to any static host         | `primo build`  |
+| Sync local edits to an existing hosted server | `primo push`   |
+
 ### `primo validate`
 
 Check site structure for errors.
@@ -125,45 +186,56 @@ npx wrangler pages deploy dist
 ## Site Structure
 
 ```
-my-site/
-├── primo.json          # Site config (name, site_id, host)
-├── blocks/             # Svelte components
-│   └── hero/
-│       ├── component.svelte
-│       ├── fields.json
-│       └── content.yaml
-├── pages/              # Page content (YAML)
-│   └── index.yaml
-├── page-types/         # Page templates
-│   └── default/
-│       └── config.json
-├── site/               # Site-wide settings
-│   ├── fields.json
-│   ├── content.yaml
-│   └── head.svelte
-└── uploads/            # Media files
+workspace/
+├── server.yaml
+├── library/
+└── sites/
+    └── my-site/
+        ├── site.yaml
+        ├── blocks/
+        ├── pages/
+        ├── page-types/
+        └── site/
 ```
 
 ## Multiple Sites
 
-Run `primo dev` from a parent folder to work on multiple sites at once:
+Run `primo dev` from a workspace folder to work on multiple sites at once:
 
 ```
 workspace/
-├── server.json         # Optional: { "port": 3000 }
-├── site-one/
-│   └── primo.json
-└── site-two/
-    └── primo.json
+├── server.yaml         # Optional: port + site_groups
+└── sites/
+    ├── site-one/
+    │   └── site.yaml   # includes group: default
+    └── site-two/
+        └── site.yaml   # includes group: default
 ```
 
 Each site gets its own subdomain: `site-one.localhost:3000`, `site-two.localhost:3000`
 
+## Shared Library Workspace
+
+The shared block library can live at the workspace root alongside the `sites/` folder:
+
+```text
+workspace/
+├── server.yaml
+├── library/
+│   ├── marketing/
+│   │   └── hero/
+│   └── shared/
+│       └── footer/
+└── sites/
+    ├── site-one/
+    └── site-two/
+```
+
 ## Documentation
 
-Full documentation: [docs.primocms.org](https://docs.primocms.org)
+Full documentation: [primo.page/docs](https://primo.page/docs)
 
 ## Requirements
 
 - Node.js 18+
-- For `primo publish`: Railway CLI or Fly.io CLI
+- For `primo deploy`: Railway CLI or Fly.io CLI