Pagelove - The CLI

Overview

The Pagelove CLI is a command-line tool that helps you create, develop, and manage Pagelove projects. It provides a local development server with built-in support for CSS Selector Range units, DOM primitives, and live editing capabilities.

Installation

Prerequisites

• Node.js 16.x or higher
• npm or yarn
• Git (for cloning templates)

Install from npm

npm install -g @pagelove/cli

Install from source

git clone https://github.com/pagelove/cli.git
cd cli
npm install
npm link

Quick Start

The fastest way to get started with Pagelove:

# Create a new project
pagelove create my-project

# The CLI will prompt you to choose:
# - Use the starter kit (recommended for beginners)
# - Start from scratch (minimal configuration)

# Navigate to your project
cd my-project

# Start the development server
pagelove serve

Your site will be available at http://localhost:5683

Commands

create

Create a new Pagelove project in a new directory.

pagelove create [name] [options]

Arguments:

• name (optional) - Project name. If not provided, you'll be prompted for one.

Options:

• -t, --template <url> - Use a custom Git repository as template
• -f, --force - Overwrite existing directory

Examples:

# Interactive mode - prompts for name and project type
pagelove create

# Create with a specific name
pagelove create my-website

# Use a custom template
pagelove create my-app --template https://github.com/myorg/my-template.git

init

Initialize a Pagelove project in the current directory.

pagelove init [options]

Options:

• -n, --name <name> - Project name
• -t, --template <url> - Git repository URL to use as template
• -f, --force - Overwrite existing files
• --in-place - Initialize in current directory when using --name with template

Examples:

# Interactive mode - choose between starter kit or minimal setup
pagelove init

# Initialize with a specific name
pagelove init --name "My Site"

# Use the starter kit template explicitly
pagelove init --template https://github.com/pagelove/serve-starter-kit.git

serve

Start the local development server.

pagelove serve [options]

Options:

• -p, --port <port> - Port to run on (default: 5683)
• -h, --host <host> - Host to bind to (default: localhost)
• --no-open - Don't open browser automatically

Examples:

# Start with defaults
pagelove serve

# Use a different port
pagelove serve --port 3000

# Bind to all interfaces
pagelove serve --host 0.0.0.0

# Don't open browser
pagelove serve --no-open

Project Structure

Starter Kit Project

When you create a project using the starter kit, you get:

my-project/
├── docs/
│   ├── index.html       # Main HTML file with examples
│   └── styles.css       # Custom styles
├── pagelove.json        # Project configuration
├── .gitignore           # Git ignore file
└── README.md            # Project documentation

Minimal Project

When starting from scratch:

my-project/
├── docs/
│   └── index.html       # Basic HTML file
└── pagelove.json        # Project configuration

Features

DOM Primitives

DOM primitives extend HTML elements with HTTP-like methods. To use them, import the library as a module:

<script type="module" src="https://pagelove.org/js/dom-primitives/index.mjs"></script>

Then you can use the HTTP-like methods on any HTML element:

// POST - Add content
document.querySelector('#list').POST('<li>New Item</li>');

// PUT - Replace content
document.querySelector('#list').PUT('<ul><li>Replaced</li></ul>');

// DELETE - Remove element
document.querySelector('#list li:last-child').DELETE();

CSS Selector Range Units

Request specific parts of HTML using CSS selectors:

# Get just the header
curl -H "Range: selector=header" http://localhost:5683/

# Update specific content
curl -X PUT -H "Range: selector=#content" \
  -d '<div id="content">New content</div>' \
  http://localhost:5683/

Examples

Creating a Blog

# Create the project
pagelove create my-blog

# Choose starter kit when prompted
# Navigate to the project
cd my-blog

# Start developing
pagelove serve

Adding to Existing Project

# Navigate to your project
cd existing-website

# Initialize Pagelove
pagelove init

# Choose "Start from scratch" to keep existing files
# Start the server
pagelove serve

Using Custom Templates

# Create from your organization's template
pagelove create company-site \
  --template https://github.com/mycompany/pagelove-template.git

Configuration

The pagelove.json file configures your project:

{
  "name": "my-project",
  "version": "1.0.0",
  "port": 5683,
  "build": {
    "webroot": "docs"
  }
}

Development Server Features

• Live Reload - Changes to files are reflected immediately
• CORS Support - Built-in CORS headers for development
• Microdata to JSON-LD - Automatic conversion of microdata
• Request Logging - Colored output showing all requests
• Error Handling - Detailed error messages in development mode

Troubleshooting

Port Already in Use

If port 5683 is already in use:

pagelove serve --port 3000

Permission Denied

If you get permission errors during global installation:

sudo npm install -g @pagelove/cli

Or use a Node version manager like nvm to avoid permission issues.

Template Clone Failed

Ensure you have Git installed and network access to GitHub:

git --version

Getting Help

• Documentation: https://pagelove.org/docs
• GitHub Issues: https://github.com/pagelove/cli/issues
• Website: https://pagelove.org

License

MIT © Pagelove

Happy coding with Pagelove! 🧡