insertr/COMMANDS.md

Insertr Command Reference

Complete reference for the unified insertr binary commands, configuration, and usage patterns.

🔧 Command Overview

insertr [global-flags] <command> [command-flags] [arguments]

📚 Global Flags

Available for all commands:

Flag	Environment Variable	Description	Default
--config	N/A	Config file path	./insertr.yaml
--db	INSERTR_DB_PATH	Database path or connection string	./insertr.db
--api-url	INSERTR_API_URL	Remote content API URL	""
--api-key	INSERTR_API_KEY	API authentication key	""
--site-id	INSERTR_SITE_ID	Site identifier for content	"demo"
--help	N/A	Show help information	N/A
--version	N/A	Show version information	N/A

🔨 enhance Command

Build-time content injection - processes HTML files and injects database content.

insertr enhance [input-dir] [flags]

Arguments

• input-dir - Directory containing HTML files to enhance (required)

Flags

Flag	Description	Default
--output, -o	Output directory for enhanced files	./dist
--mock	Use mock content for development	true

Examples

# Basic enhancement with mock data
./insertr enhance demo-site/

# Production build with custom output
./insertr enhance src/ --output ./build --mock=false

# Use remote API for content  
./insertr enhance src/ --api-url https://cms.example.com --api-key xyz123

# Use local database
./insertr enhance src/ --db ./content.db

# Custom site ID
./insertr enhance src/ --site-id production

Content Sources Priority

1. Remote API (if --api-url provided)
2. Local database (if --db points to valid database)
3. Mock content (if --mock=true or fallback)

🔌 serve Command

Runtime API server - provides HTTP endpoints for content management and server-hosted static site enhancement.

insertr serve [flags]

Flags

Flag	Description	Default
--port, -p	HTTP server port	8080
--dev-mode	Enable development mode features	false

Examples

# Development server
./insertr serve --dev-mode

# Production server
./insertr serve --port 80

# Custom database
./insertr serve --db ./production.db

# PostgreSQL database
./insertr serve --db "postgresql://user:pass@localhost:5432/insertr"

# Custom configuration
./insertr --config production.yaml serve

Server-Hosted Static Sites

When running insertr serve, the server automatically:

• Registers sites from insertr.yaml configuration
• Enhances static files with latest database content
• Auto-updates files when content changes via API
• Creates backups of original files (if enabled)

Development vs Production Behavior:

Development Mode (--dev-mode):

• ✅ Content changes saved to database
• ❌ File enhancement disabled (prevents live-reload loops)
• ✅ Editor loads content dynamically from API
• ✅ Perfect for just dev workflow

Production Mode (no --dev-mode):

• ✅ Content changes saved to database
• ✅ File enhancement enabled
• ✅ Static files updated immediately
• ✅ Changes live instantly

Live Enhancement Process (Production):

1. Content updated via API → Database updated
2. If site has auto_enhance: true AND not in dev mode → File enhancement triggered
3. Static files updated in-place → Changes immediately live

API Endpoints

When running insertr serve, these endpoints are available:

Health Check

• GET /health - Server health status

Content Management

• GET /api/content?site_id={site} - Get all content for site
• GET /api/content/{id}?site_id={site} - Get single content item
• GET /api/content/bulk?site_id={site}&ids[]={id1}&ids[]={id2} - Get multiple items
• POST /api/content - Create new content
• PUT /api/content/{id} - Update existing content

Version Control

• GET /api/content/{id}/versions?site_id={site} - Get content history
• POST /api/content/{id}/rollback - Rollback to previous version

⚙️ Configuration

YAML Configuration File

Default file: insertr.yaml

# Database configuration
database:
  path: "./insertr.db"        # SQLite file or PostgreSQL connection

# Remote API configuration  
api:
  url: ""                     # Content API URL
  key: ""                     # API key

# Server configuration
server:
  port: 8080                  # HTTP port
  dev_mode: false             # Development mode

# Build configuration
build:
  input: "./src"              # Default input directory
  output: "./dist"            # Default output directory

# Global settings
site_id: "demo"              # Site identifier
mock_content: false          # Use mock data

Environment Variables

All configuration can be set via environment variables:

export INSERTR_DB_PATH="./content.db"
export INSERTR_API_URL="https://api.example.com"
export INSERTR_API_KEY="your-api-key"
export INSERTR_SITE_ID="production"

./insertr serve

Configuration Precedence

1. CLI flags (highest priority)
2. Environment variables
3. YAML configuration file
4. Built-in defaults (lowest priority)

📋 Usage Patterns

Development Workflow

# Start full development environment
just dev                     # Uses justfile for convenience

# Manual development setup
./insertr serve --dev-mode --db ./dev.db &
npm run demo                 # Start demo site

# Hot reload development
air                         # Uses .air.toml configuration

Production Deployment

# Build static site with content
./insertr enhance ./src --output ./dist --api-url https://api.prod.com

# Start production API server
./insertr serve --db "postgresql://user:pass@db:5432/prod"

# With custom configuration
./insertr --config ./production.yaml serve

CI/CD Integration

# GitHub Actions example
- name: Build with Insertr
  run: |
    ./insertr enhance ./public --output ./dist
    
- name: Deploy enhanced site
  uses: peaceiris/actions-gh-pages@v3
  with:
    publish_dir: ./dist

🚨 Error Handling

Common Issues

Database Connection Errors:

# Check database path
./insertr --db ./nonexistent.db serve
# Error: failed to initialize database

# Solution: Verify database path or use --mock for development
./insertr serve --dev-mode  # Creates ./insertr.db automatically

Port Already in Use:

# Error: listen tcp :8080: bind: address already in use

# Solution: Use different port
./insertr serve --port 3001

Missing Input Directory:

# Error: Input directory does not exist

# Solution: Verify path exists
ls -la ./src
./insertr enhance ./src

🔍 Debugging

Verbose Logging

# Enable development mode for more detailed output
./insertr serve --dev-mode

# Check server health
curl http://localhost:8080/health

Configuration Validation

# Test configuration loading
./insertr --config ./test.yaml --help

# Verify environment variables
./insertr serve --help  # Shows resolved configuration values

---

For more examples and integration patterns, see:

• Main README - Getting started and overview
• Integration Summary - Architecture details
• Development Guide - Contributing and setup