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

Live Enhancement Process:

1. Content updated via API → Database updated
2. If site has auto_enhance: true → 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 or update content (upsert)
• DELETE /api/content/{id}?site_id={site} - Delete content

Site Enhancement

• POST /api/enhance?site_id={site} - Manually trigger site file enhancement

Version Control

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

Authentication

• GET /auth/login - Initiate OAuth flow (returns redirect URL for Authentik)
• GET /auth/callback - OAuth callback handler (processes authorization code)

Content Management API Details

Create/Update Content (Upsert)

POST /api/content[?site_id={site}]

Request Body:

{
  "id": "optional-content-id",
  "site_id": "site-identifier",
  "value": "content-value",
  "type": "text|markdown|link",
  "element_context": {
    "tag": "h1",
    "classes": ["insertr", "title"],
    "original_content": "Default Title",
    "parent_context": "hero-section"
  }
}

Key Features:

• Automatic ID Generation: If no id provided, generates deterministic ID from element_context
• Content Type Detection: Automatically determines type if not specified
• Version History: Preserves existing content as version before update
• Flexible Site ID: Can be provided in URL parameter or request body
• Auto-Enhancement: Triggers file enhancement if site has auto_enhance: true

Response:

{
  "id": "generated-or-provided-id",
  "site_id": "site-identifier", 
  "value": "content-value",
  "type": "text|markdown|link",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "last_edited_by": "user-id"
}

Usage Examples:

# Create with automatic ID generation
curl -X POST http://localhost:8080/api/content?site_id=demo \
  -H "Content-Type: application/json" \
  -d '{
    "value": "New Homepage Title",
    "element_context": {
      "tag": "h1",
      "classes": ["insertr"],
      "original_content": "Welcome"
    }
  }'

# Update existing content by ID
curl -X POST http://localhost:8080/api/content \
  -H "Content-Type: application/json" \
  -d '{
    "id": "homepage-title-abc123",
    "site_id": "demo",
    "value": "Updated Title",
    "type": "text"
  }'

# Create markdown content
curl -X POST http://localhost:8080/api/content?site_id=demo \
  -H "Content-Type: application/json" \
  -d '{
    "value": "# New Article\n\nThis is **markdown** content.",
    "type": "markdown",
    "element_context": {
      "tag": "div",
      "classes": ["insertr", "content"]
    }
  }'

⚙️ 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

# Authentication configuration
auth:
  provider: "mock"            # "mock", "authentik"
  jwt_secret: ""              # JWT signing secret (auto-generated in dev)
  oidc:                       # Authentik OIDC configuration
    endpoint: ""              # https://auth.example.com/application/o/insertr/
    client_id: ""             # OAuth2 client ID
    client_secret: ""         # OAuth2 client secret

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

# Authentication environment variables (recommended for production)
export AUTHENTIK_CLIENT_SECRET="your-oidc-secret"
export AUTHENTIK_ENDPOINT="https://auth.example.com/application/o/insertr/"

./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 with authentication
export AUTHENTIK_CLIENT_SECRET="prod-secret"
./insertr serve --db "postgresql://user:pass@db:5432/prod"

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

Authentication Setup

Mock Authentication (Development)

# Default - no setup required
./insertr serve --dev-mode

# Configuration
auth:
  provider: "mock"

Authentik OIDC (Production)

# Set environment variables (recommended)
export AUTHENTIK_CLIENT_SECRET="your-secret-from-authentik"
export AUTHENTIK_ENDPOINT="https://auth.example.com/application/o/insertr/"

# Start server
./insertr serve

Required Authentik Configuration:

1. Create OAuth2/OIDC Provider in Authentik
2. Set redirect URI: https://your-domain.com/auth/callback
3. Note the endpoint URL and client credentials
4. Configure in insertr.yaml or environment variables

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