Joakim
ae9ae7e442
📚 **Complete Documentation Overhaul** **Updated Files:** ✅ **README.md** - Updated commands, configuration, and workflow ✅ **COMMANDS.md** - New comprehensive command reference ✅ **INTEGRATION-SUMMARY.md** - Updated architecture overview ✅ **insertr-server/README.md** - Redirect to unified binary docs **Key Documentation Changes:** 🔧 **Unified Binary Commands:** - Updated all examples to use `./insertr enhance` and `./insertr serve` - Removed references to separate CLI/server binaries - Added comprehensive configuration documentation ⚙️ **Configuration Section:** - Added YAML configuration examples (`insertr.yaml`) - Documented environment variables (`INSERTR_*`) - Explained configuration precedence (CLI → env → YAML → defaults) 📖 **Command Reference (COMMANDS.md):** - Complete reference for all commands and flags - Usage patterns for development and production - API endpoint documentation - Error handling and debugging guides - CI/CD integration examples 🏗️ **Architecture Updates:** - Updated development workflow instructions - Fixed CLI → Binary terminology - Updated hot reload and build process documentation **Migration Notes:** - All functionality preserved in unified binary - Simplified development workflow with `just dev` - Single executable for all operations
269 lines
6.3 KiB
Markdown
269 lines
6.3 KiB
Markdown
# Insertr Command Reference
|
|
|
|
Complete reference for the unified `insertr` binary commands, configuration, and usage patterns.
|
|
|
|
## 🔧 Command Overview
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
insertr serve [flags]
|
|
```
|
|
|
|
### Flags
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--port`, `-p` | HTTP server port | `8080` |
|
|
| `--dev-mode` | Enable development mode features | `false` |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
### 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`
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```yaml
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# Error: listen tcp :8080: bind: address already in use
|
|
|
|
# Solution: Use different port
|
|
./insertr serve --port 3001
|
|
```
|
|
|
|
**Missing Input Directory:**
|
|
```bash
|
|
# Error: Input directory does not exist
|
|
|
|
# Solution: Verify path exists
|
|
ls -la ./src
|
|
./insertr enhance ./src
|
|
```
|
|
|
|
## 🔍 Debugging
|
|
|
|
### Verbose Logging
|
|
|
|
```bash
|
|
# Enable development mode for more detailed output
|
|
./insertr serve --dev-mode
|
|
|
|
# Check server health
|
|
curl http://localhost:8080/health
|
|
```
|
|
|
|
### Configuration Validation
|
|
|
|
```bash
|
|
# 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](README.md) - Getting started and overview
|
|
- [Integration Summary](INTEGRATION-SUMMARY.md) - Architecture details
|
|
- [Development Guide](DEVELOPMENT.md) - Contributing and setup |