@appkit/llamacpp-cli 2.0.0 → 2.1.0

package/README.md

@@ -14,6 +14,7 @@ CLI tool to manage local llama.cpp servers on macOS. Provides an Ollama-like exp
 ## Features
 
 - 🚀 **Easy server management** - Start, stop, and monitor llama.cpp servers
+- 🏷️ **Server aliases** - Friendly, stable identifiers that persist across model changes
 - 🔀 **Unified router** - Single OpenAI-compatible endpoint for all models with automatic routing and request logging
 - 🌐 **Admin Interface** - REST API + modern web UI for remote management and automation
 - 🤖 **Model downloads** - Pull GGUF models from Hugging Face
@@ -21,7 +22,7 @@ CLI tool to manage local llama.cpp servers on macOS. Provides an Ollama-like exp
 - ⚙️ **Smart defaults** - Auto-configure threads, context size, and GPU layers based on model size
 - 🔌 **Auto port assignment** - Automatically find available ports (9000-9999)
 - 📊 **Real-time monitoring TUI** - Multi-server dashboard with drill-down details, live GPU/CPU/memory metrics, token generation speeds, and animated loading states
-- 🪵 **Smart logging** - Compact one-line request format with optional full JSON details
+- 🪵 **Unified logging** - Activity logs (HTTP requests) and System logs (diagnostics) for all services
 - ⚡️ **Optimized metrics** - Batch collection and caching prevent CPU spikes (10x fewer processes)
 
 ## Why llamacpp-cli?
@@ -172,17 +173,21 @@ llamacpp
 
 ![Server Monitoring TUI](https://raw.githubusercontent.com/appkitstudio/llamacpp-cli/main/docs/images/monitor-detail.png)
 
-### Overview
+### Main Features
 
-The TUI provides a comprehensive interface for:
-- **Monitoring** - Real-time metrics for all servers (GPU, CPU, memory, token generation)
-- **Server Management** - Create, start, stop, remove, and configure servers
-- **Model Management** - Browse, search, download, and delete models
-- **Historical Metrics** - View time-series charts of past performance
+**Dashboard** - Monitor all servers at a glance with real-time metrics (GPU, CPU, memory, token speed)
 
-### Multi-Server Dashboard
+**Server Management** - Create, start, stop, configure, and remove servers with inline editors
 
-The main view shows all your servers at a glance:
+**Model Management** (press `M`) - Browse local models, search/download from HuggingFace, delete with cascade
+
+**Router Management** (press `R`) - Control router service, view configuration, access activity/system logs
+
+**Historical Charts** (press `H`) - View time-series graphs with Recent (1-3min) or Hour (60min) views
+
+**Logs** (press `L`) - Toggle between Activity (HTTP) and System (diagnostics) logs with auto-refresh
+
+### Dashboard View
 
 ```
 ┌─────────────────────────────────────────────────────────┐
@@ -192,173 +197,14 @@ The main view shows all your servers at a glance:
 │ Servers (3 running, 0 stopped)                          │
 │   │ Server ID      │ Port │ Status │ Slots │ tok/s    │
 │───┼────────────────┼──────┼────────┼───────┼──────────┤
-│ ► │ llama-3-2-3b   │ 9000 │ ● RUN  │ 2/4   │ 245      │  (highlighted)
+│ ► │ llama-3-2-3b   │ 9000 │ ● RUN  │ 2/4   │ 245      │
 │   │ qwen2-7b       │ 9001 │ ● RUN  │ 1/4   │ 198      │
 │   │ llama-3-1-8b   │ 9002 │ ○ IDLE │ 0/4   │ -        │
 └─────────────────────────────────────────────────────────┘
-↑/↓ Navigate | Enter for details | [N]ew [M]odels [H]istory [Q]uit
+↑/↓ Navigate | Enter for details | [N]ew [M]odels [R]outer [H]istory [Q]uit
 ```
 
-**Features:**
-- System resource overview (GPU, CPU, memory)
-- List of all servers (running and stopped)
-- Real-time status updates every 2 seconds
-- Color-coded status indicators
-- Navigate with arrow keys or vim keys (k/j)
-
-### Single-Server Detail View
-
-Press `Enter` on any server to see detailed information:
-
-**Running servers show:**
-- Server information (status, uptime, model name, endpoint)
-- Request metrics (active/idle slots, prompt speed, generation speed)
-- Active slots detail (per-slot token generation rates)
-- System resources (GPU/CPU/ANE utilization, memory usage)
-
-**Stopped servers show:**
-- Server configuration (threads, context, GPU layers)
-- Last activity timestamps
-- Quick action commands (start, config, logs)
-
-### Models Management
-
-Press `M` from the main view to access Models Management.
-
-**Features:**
-- Browse all installed models with size and modified date
-- View which servers are using each model
-- Delete models with cascade option (removes associated servers)
-- Search HuggingFace for new models
-- Download models with real-time progress tracking
-
-**Models View:**
-- View all GGUF files in scrollable table
-- Color-coded server usage (green = safe to delete, yellow = in use)
-- Delete selected model with `Enter` or `D` key
-- Confirmation dialog with cascade warning
-
-**Search View** (press `S` from Models view):
-- Search HuggingFace models by text input
-- Browse results with downloads, likes, and file counts
-- Expand model to show available GGUF files
-- Download with real-time progress, speed, and ETA
-- Cancel download with `ESC` (cleans up partial files)
-
-### Server Operations
-
-**Create Server** (press `N` from main view):
-1. Select model from list (shows existing servers per model)
-2. Edit configuration (threads, context size, GPU layers, port)
-3. Review smart defaults based on model size
-4. Create and automatically start server
-5. Return to main view with new server visible
-
-**Start/Stop Server** (press `S` from detail view):
-- Toggle server state with progress modal
-- Stays in detail view after operation
-- Shows updated status immediately
-
-**Remove Server** (press `R` from detail view):
-- Confirmation dialog with option to delete model file
-- Warns if other servers use the same model
-- Cascade deletion removes all associated data
-- Returns to main view after deletion
-
-**Configure Server** (press `C` from detail view):
-- Edit all server parameters inline
-- Modal dialogs for different field types
-- Model migration support (handles server ID changes)
-- Automatic restart prompts for running servers
-- Port conflict detection and validation
-
-### Historical Monitoring
-
-Press `H` from any view to see historical time-series charts.
-
-**Single-Server Historical View:**
-- Token generation speed over time
-- GPU usage (%) with avg/max/min stats
-- CPU usage (%) with avg/max/min
-- Memory usage (%) with avg/max/min
-- Auto-refresh every 3 seconds
-
-**Multi-Server Historical View:**
-- Aggregated metrics across all servers
-- Total token generation speed (sum)
-- System GPU usage (average)
-- Total CPU usage (sum of per-process)
-- Total memory usage (sum in GB)
-
-**View Modes** (toggle with `H` key):
-
-- **Recent View (default):**
-  - Shows last 40-80 samples (~1-3 minutes)
-  - Raw data with no downsampling - perfect accuracy
-  - Best for: "What's happening right now?"
-
-- **Hour View:**
-  - Shows all ~1,800 samples from last hour
-  - Absolute time-aligned downsampling (30:1 ratio)
-  - Bucket max for GPU/CPU/token speed (preserves peaks)
-  - Bucket mean for memory (shows average)
-  - Chart stays perfectly stable as data streams in
-  - Best for: "What happened over the last hour?"
-
-**Data Collection:**
-- Automatic during monitoring (piggyback on polling loop)
-- Stored in `~/.llamacpp/history/<server-id>.json` per server
-- Retention: Last 24 hours (circular buffer, auto-prune)
-- File size: ~21 MB per server for 24h @ 2s interval
-
-### Keyboard Shortcuts
-
-**List View (Multi-Server):**
-- `↑/↓` or `k/j` - Navigate server list
-- `Enter` - View details for selected server
-- `N` - Create new server
-- `M` - Switch to Models Management
-- `H` - View historical metrics (all servers)
-- `ESC` - Exit TUI
-- `Q` - Quit immediately
-
-**Detail View (Single-Server):**
-- `S` - Start/Stop server (toggles based on status)
-- `C` - Open configuration screen
-- `R` - Remove server (with confirmation)
-- `H` - View historical metrics (this server)
-- `ESC` - Back to list view
-- `Q` - Quit immediately
-
-**Models View:**
-- `↑/↓` or `k/j` - Navigate model list
-- `Enter` or `D` - Delete selected model
-- `S` - Open search view
-- `R` - Refresh model list
-- `ESC` - Back to main view
-- `Q` - Quit immediately
-
-**Search View:**
-- `/` or `I` - Focus search input
-- `Enter` (in input) - Execute search
-- `↑/↓` or `k/j` - Navigate results or files
-- `Enter` (on result) - Show GGUF files for model
-- `Enter` (on file) - Download/install model
-- `R` - Refresh results (re-execute search)
-- `ESC` - Back to models view (or results list if viewing files)
-- `Q` - Quit immediately
-
-**Historical View:**
-- `H` - Toggle between Recent/Hour view
-- `ESC` - Return to live monitoring
-- `Q` - Quit immediately
-
-**Configuration Screen:**
-- `↑/↓` or `k/j` - Navigate fields
-- `Enter` - Open modal for selected field
-- `S` - Save changes (prompts for restart if running)
-- `ESC` - Cancel (prompts if unsaved changes)
-- `Q` - Quit immediately
+Navigate with arrow keys or vim keys (k/j). Press `Enter` on any server to see detailed metrics, active slots, and resource usage. All keyboard shortcuts are shown in the footer of each view.
 
 ### Optional: GPU/CPU Metrics
 
@@ -398,8 +244,8 @@ llamacpp router start       # Start the router service
 llamacpp router stop        # Stop the router service
 llamacpp router status      # Show router status and available models
 llamacpp router restart     # Restart the router
-llamacpp router config      # Update router settings (--port, --host, --timeout, --health-interval, --verbose)
-llamacpp router logs        # View router logs (with --follow, --verbose, --clear options)
+llamacpp router config      # Update router settings (--port, --host, --timeout, --health-interval)
+llamacpp router logs        # View router logs (with --follow, --activity, --system, --clear options)
 ```
 
 ### Usage Example
@@ -419,8 +265,22 @@ response = client.chat.completions.create(
     model="llama-3.2-3b-instruct-q4_k_m.gguf",
     messages=[{"role": "user", "content": "Hello!"}]
 )
+
+# Or use server aliases for cleaner code
+response = client.chat.completions.create(
+    model="thinking",  # Routes to server with alias "thinking"
+    messages=[{"role": "user", "content": "Hello!"}]
+)
 ```
 
+**Model Name Resolution:**
+The router accepts model names in multiple formats:
+- Full model filename: `llama-3.2-3b-instruct-q4_k_m.gguf`
+- Server alias: `thinking` (set with `--alias` flag)
+- Partial model name: `llama-3.2-3b` (fuzzy match)
+
+Aliases provide a stable, friendly identifier that persists across model changes.
+
 ### Supported Endpoints
 
 **OpenAI-Compatible:**
@@ -453,34 +313,28 @@ llamacpp router config --health-interval 3000 --restart
 # Change bind address (for remote access)
 llamacpp router config --host 0.0.0.0 --restart
 
-# Enable verbose logging (saves detailed JSON logs)
-llamacpp router config --verbose true --restart
-
-# Disable verbose logging
-llamacpp router config --verbose false --restart
 ```
 
 **Note:** Changes require a restart to take effect. Use `--restart` flag to apply immediately.
 
 ### Logging
 
-The router uses separate log streams for different purposes (nginx-style):
+The router provides two log types:
 
-| Log File | Purpose | Content |
-|----------|---------|---------|
-| `router.stdout` | Request activity | Model routing, status codes, timing, prompts |
-| `router.stderr` | System messages | Startup, shutdown, errors, proxy failures |
-| `router.log` | Structured JSON | Detailed entries for programmatic parsing (verbose mode) |
+| Log Type | CLI Flag | Content |
+|----------|----------|---------|
+| **Activity** | (default) | Request routing, status codes, timing, backend selection |
+| **System** | `--system` | Startup, shutdown, errors, diagnostic messages |
 
-**View recent logs:**
+**View logs:**
 ```bash
-# Show activity logs (default - stdout)
+# Activity logs (default) - router request routing
 llamacpp router logs
 
-# Show system logs (errors, startup messages)
-llamacpp router logs --stderr
+# System logs - diagnostics and errors
+llamacpp router logs --system
 
-# Follow activity in real-time
+# Follow logs in real-time
 llamacpp router logs --follow
 
 # Show last 10 lines
@@ -489,50 +343,38 @@ llamacpp router logs --lines 10
 
 **Log formats:**
 
-Activity logs (stdout):
+Activity logs:
 ```
 200 POST /v1/chat/completions → llama-3.2-3b-instruct-q4_k_m.gguf (127.0.0.1:9001) 1234ms | "What is..."
 404 POST /v1/chat/completions → unknown-model 3ms | "test" | Error: No server found
 ```
 
-System logs (stderr):
+System logs:
 ```
 [Router] Listening on http://127.0.0.1:9100
 [Router] PID: 12345
 [Router] Proxy request failed: ECONNREFUSED
 ```
 
-Verbose JSON logs (router.log) - enable with `--verbose true`:
-```bash
-llamacpp router logs --verbose
-```
-
 **Log management:**
 ```bash
-# Clear activity log
+# Clear current log file (activity or system)
 llamacpp router logs --clear
 
-# Clear all router logs (stdout, stderr, verbose)
+# Clear all router logs (both activity and system)
 llamacpp router logs --clear-all
 
 # Rotate log files with timestamp
 llamacpp router logs --rotate
-
-# View system logs instead of activity
-llamacpp router logs --stderr
 ```
 
-**What's logged (activity):**
-- ✅ Model name used
-- ✅ HTTP status code (color-coded)
+**What's logged:**
+- ✅ Model name and routing decisions
+- ✅ HTTP status codes (color-coded)
 - ✅ Request duration (ms)
-- ✅ Backend server (host:port)
+- ✅ Backend server selection (host:port)
 - ✅ First 50 chars of prompt
-- ✅ Error messages (if failed)
-
-**Verbose mode benefits:**
-- Detailed JSON logs for LLM/script parsing
-- Stored in `~/.llamacpp/logs/router.log`
+- ✅ Error messages and diagnostics
 - Automatic rotation when exceeding 100MB
 - Machine-readable format with timestamps
 
@@ -676,8 +518,8 @@ llamacpp admin start       # Start admin service
 llamacpp admin stop        # Stop admin service
 llamacpp admin status      # Show status and API key
 llamacpp admin restart     # Restart service
-llamacpp admin config      # Update settings (--port, --host, --regenerate-key, --verbose)
-llamacpp admin logs        # View admin logs (with --follow, --clear, --rotate options)
+llamacpp admin config      # Update settings (--port, --host, --regenerate-key)
+llamacpp admin logs        # View admin logs (with --follow, --activity, --system, --clear options)
 ```
 
 ### REST API
@@ -688,6 +530,8 @@ The Admin API provides full CRUD operations for servers and models via HTTP.
 
 **Authentication:** Bearer token (API key auto-generated on first start)
 
+**API Documentation:** Interactive Swagger UI available at `http://localhost:9200/api-docs`
+
 #### Server Endpoints
 
 | Method | Endpoint | Description |
@@ -700,7 +544,7 @@ The Admin API provides full CRUD operations for servers and models via HTTP.
 | POST | `/api/servers/:id/start` | Start stopped server |
 | POST | `/api/servers/:id/stop` | Stop running server |
 | POST | `/api/servers/:id/restart` | Restart server |
-| GET | `/api/servers/:id/logs?type=stdout\|stderr&lines=100` | Get server logs |
+| GET | `/api/servers/:id/logs?type=activity\|system\|all&lines=100` | Get server logs (activity=HTTP, system=diagnostics) |
 
 #### Model Endpoints
 
@@ -712,6 +556,17 @@ The Admin API provides full CRUD operations for servers and models via HTTP.
 | GET | `/api/models/search?q=query` | Search HuggingFace |
 | POST | `/api/models/download` | Download model from HF |
 
+#### Router Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/router` | Get router status and config |
+| POST | `/api/router/start` | Start router service |
+| POST | `/api/router/stop` | Stop router service |
+| POST | `/api/router/restart` | Restart router service |
+| PATCH | `/api/router` | Update router config |
+| GET | `/api/router/logs?type=activity\|system&lines=100` | Get router logs (Activity from stdout, System from stderr) |
+
 #### System Endpoints
 
 | Method | Endpoint | Description |
@@ -752,6 +607,28 @@ curl -X DELETE "http://localhost:9200/api/models/llama-3.2-3b-instruct-q4_k_m.gg
   -H "Authorization: Bearer YOUR_API_KEY"
 ```
 
+**Get server logs:**
+```bash
+# Activity logs (HTTP requests) - default
+curl "http://localhost:9200/api/servers/llama-3-2-3b/logs?type=activity&lines=50" \
+  -H "Authorization: Bearer YOUR_API_KEY"
+
+# System logs (diagnostics)
+curl "http://localhost:9200/api/servers/llama-3-2-3b/logs?type=system&lines=100" \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+**Get router logs:**
+```bash
+# Activity logs (router requests)
+curl "http://localhost:9200/api/router/logs?type=activity&lines=50" \
+  -H "Authorization: Bearer YOUR_API_KEY"
+
+# System logs (diagnostics)
+curl "http://localhost:9200/api/router/logs?type=system&lines=100" \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
 ### Web UI
 
 The web UI provides a modern, browser-based interface for managing servers and models.
@@ -811,8 +688,8 @@ llamacpp admin config --host 0.0.0.0 --restart
 # Regenerate API key (invalidates old key)
 llamacpp admin config --regenerate-key --restart
 
-# Enable verbose logging
-llamacpp admin config --verbose true --restart
+# Enable logging
+llamacpp admin config --logging true --restart
 ```
 
 **Note:** Changes require a restart to take effect. Use `--restart` flag to apply immediately.
@@ -846,29 +723,31 @@ llamacpp admin config --regenerate-key --restart
 
 ### Logging
 
-The admin service maintains separate log streams:
+The admin service provides two log types:
+
+| Log Type | CLI Flag | Content |
+|----------|----------|---------|
+| **Activity** | `--activity` | HTTP API requests (endpoint, status, duration) |
+| **System** | `--system` | Startup, shutdown, errors, diagnostic messages |
 
-| Log File | Purpose | Content |
-|----------|---------|---------|
-| `admin.stdout` | Request activity | Endpoint, status, duration |
-| `admin.stderr` | System messages | Startup, shutdown, errors |
+**Default:** Shows both Activity and System logs (useful for debugging).
 
 **View logs:**
 ```bash
-# Show activity logs (default - stdout)
+# Both activity and system logs (default)
 llamacpp admin logs
 
-# Show system logs (errors, startup)
-llamacpp admin logs --stderr
+# Activity logs only (HTTP API requests)
+llamacpp admin logs --activity
+
+# System logs only (diagnostics and errors)
+llamacpp admin logs --system
 
 # Follow in real-time
 llamacpp admin logs --follow
 
 # Clear all logs
 llamacpp admin logs --clear
-
-# Rotate logs with timestamp
-llamacpp admin logs --rotate
 ```
 
 ### Example Output
@@ -912,8 +791,9 @@ Web UI:     http://localhost:9200
 
 Configuration:
   Config:   ~/.llamacpp/admin.json
-  Plist:    ~/Library/LaunchAgents/com.llama.admin.plist
-  Logs:     ~/.llamacpp/logs/admin.{stdout,stderr}
+  Plist:    ~/Library/LaunchAgents/studio.appkit.llamacpp-cli.admin.plist
+  Logs:     ~/.llamacpp/logs/admin.stdout  # Activity logs
+            ~/.llamacpp/logs/admin.stderr  # System logs
 
 Quick Commands:
   llamacpp admin stop          # Stop service
@@ -1081,8 +961,8 @@ llamacpp logs --rotate
 ```
 
 **Displays:**
-- Current stderr size per server
-- Current stdout size per server
+- Activity logs (.http) size per server
+- System logs (.stderr, .stdout) size per server
 - Archived logs size and count
 - Total log usage per server
 - Grand total across all servers
@@ -1095,6 +975,64 @@ llamacpp logs --rotate
 
 **Use case:** Quickly see which servers are accumulating large logs, or clean up all logs at once.
 
+## Server Aliases
+
+Server aliases provide stable, user-friendly identifiers for your servers that persist across model changes. Instead of using auto-generated IDs like `llama-3-2-3b-instruct-q4-k-m`, you can use memorable names like `thinking`, `coder`, or `gpt-oss`.
+
+### Why Use Aliases?
+
+**Stability:** When you change a server's model, the server ID changes (because it's derived from the model name). Aliases stay the same, preventing broken references in scripts and workflows.
+
+**Convenience:** Shorter, more memorable names are easier to type and read.
+
+**Router Integration:** Aliases work with the router, allowing cleaner API requests.
+
+### Usage Examples
+
+```bash
+# Create server with alias
+llamacpp server create llama-3.2-3b-instruct-q4_k_m.gguf --alias thinking
+
+# Use alias in all commands
+llamacpp server start thinking
+llamacpp server stop thinking
+llamacpp server logs thinking
+llamacpp ps thinking
+
+# Update alias
+llamacpp server config thinking --alias smart-model
+
+# Remove alias
+llamacpp server config thinking --alias ""
+
+# Alias persists across model changes
+llamacpp server config thinking --model mistral-7b.gguf --restart
+llamacpp server start thinking  # Still works with new model!
+
+# Use alias in router requests
+curl -X POST http://localhost:9100/v1/messages \
+  -H "Content-Type: application/json" \
+  -d '{"model": "thinking", "max_tokens": 100, "messages": [{"role": "user", "content": "Hello"}]}'
+```
+
+### Validation Rules
+
+- **Format:** Alphanumeric characters, hyphens, and underscores only
+- **Length:** 1-64 characters
+- **Uniqueness:** Case-insensitive (can't have both "Thinking" and "thinking")
+- **Reserved names:** Cannot use "router", "admin", or "server"
+- **Storage:** Case-sensitive (preserves your input)
+
+### Lookup Priority
+
+When you reference a server, the CLI checks identifiers in this order:
+1. **Alias** (exact match, case-sensitive)
+2. **Port** (if identifier is numeric)
+3. **Server ID** (exact match)
+4. **Model name** (fuzzy match)
+
+This means aliases always take precedence, providing predictable behavior.
+
 ## Server Management
 
 ### `llamacpp server create <model> [options]`
@@ -1104,11 +1042,21 @@ Create and start a new llama-server instance.
 llamacpp server create llama-3.2-3b-instruct-q4_k_m.gguf
 llamacpp server create llama-3.2-3b-instruct-q4_k_m.gguf --port 8080 --ctx-size 16384 --verbose
 
+# Create with a friendly alias
+llamacpp server create llama-3.2-3b-instruct-q4_k_m.gguf --alias thinking
+
+# Create multiple servers with the same model (different configurations)
+llamacpp server create llama-3.2-3b-instruct-q4_k_m.gguf --ctx-size 8192 --alias short-context
+llamacpp server create llama-3.2-3b-instruct-q4_k_m.gguf --ctx-size 32768 --alias long-context
+
 # Enable remote access (WARNING: security implications)
 llamacpp server create llama-3.2-3b-instruct-q4_k_m.gguf --host 0.0.0.0
 ```
 
+**Note:** You can create multiple servers using the same model file with different configurations (context size, GPU layers, etc.). Each server gets a unique ID automatically.
+
 **Options:**
+- `-a, --alias <name>` - Friendly alias for the server (alphanumeric, hyphens, underscores, 1-64 chars)
 - `-p, --port <number>` - Port number (default: auto-assign from 9000)
 - `-h, --host <address>` - Bind address (default: `127.0.0.1` for localhost only, use `0.0.0.0` for remote access)
 - `-t, --threads <number>` - Thread count (default: half of CPU cores)
@@ -1124,11 +1072,12 @@ Show detailed configuration and status information for a server.
 ```bash
 llamacpp server show llama-3.2-3b       # By partial name
 llamacpp server show 9000               # By port
+llamacpp server show thinking           # By alias
 llamacpp server show llama-3-2-3b       # By server ID
 ```
 
 **Displays:**
-- Server ID, model name, and path
+- Server ID, alias (if set), model name, and path
 - Current status (running/stopped/crashed)
 - Host and port
 - PID (process ID)
@@ -1138,7 +1087,7 @@ llamacpp server show llama-3-2-3b       # By server ID
 - System paths (plist file, log files)
 - Quick commands for common next actions
 
-**Identifiers:** Port number, server ID, partial model name
+**Identifiers:** Alias, port number, server ID, partial model name
 
 ### `llamacpp server config <identifier> [options]`
 Update server configuration parameters without recreating the server.
@@ -1147,6 +1096,12 @@ Update server configuration parameters without recreating the server.
 # Change model while keeping all other settings
 llamacpp server config llama-3.2-3b --model llama-3.2-1b-instruct-q4_k_m.gguf --restart
 
+# Add or update alias
+llamacpp server config llama-3.2-3b --alias thinking
+
+# Remove alias (use empty string)
+llamacpp server config thinking --alias ""
+
 # Update context size and restart
 llamacpp server config llama-3.2-3b --ctx-size 8192 --restart
 
@@ -1164,6 +1119,7 @@ llamacpp server config llama-3.2-3b --threads 8 --ctx-size 16384 --gpu-layers 40
 ```
 
 **Options:**
+- `-a, --alias <name>` - Set or update alias (use empty string `""` to remove)
 - `-m, --model <filename>` - Update model (filename or path)
 - `-h, --host <address>` - Update bind address (`127.0.0.1` for localhost, `0.0.0.0` for remote access)
 - `-t, --threads <number>` - Update thread count
@@ -1173,22 +1129,23 @@ llamacpp server config llama-3.2-3b --threads 8 --ctx-size 16384 --gpu-layers 40
 - `--no-verbose` - Disable verbose logging
 - `-r, --restart` - Automatically restart server if running
 
-**Note:** Changes require a server restart to take effect. Use `--restart` to automatically stop and start the server with the new configuration.
+**Note:** Changes require a server restart to take effect. Use `--restart` to automatically stop and start the server with the new configuration. Aliases persist across model changes, providing a stable identifier for your server.
 
 **⚠️ Security Warning:** Using `--host 0.0.0.0` binds the server to all network interfaces, allowing remote access. Only use this if you understand the security implications.
 
-**Identifiers:** Port number, server ID, partial model name
+**Identifiers:** Alias, port number, server ID, partial model name
 
 ### `llamacpp server start <identifier>`
 Start an existing stopped server.
 
 ```bash
+llamacpp server start thinking           # By alias
 llamacpp server start llama-3.2-3b       # By partial name
 llamacpp server start 9000               # By port
 llamacpp server start llama-3-2-3b       # By server ID
 ```
 
-**Identifiers:** Port number, server ID, partial model name, or model filename
+**Identifiers:** Alias, port number, server ID, partial model name, or model filename
 
 ### `llamacpp server run <identifier> [options]`
 Run an interactive chat session with a model, or send a single message.
@@ -1228,41 +1185,44 @@ llamacpp server rm 9000
 ```
 
 ### `llamacpp server logs <identifier> [options]`
-View server logs with smart filtering.
 
-**Default (verbose enabled):**
-```bash
-llamacpp server logs llama-3.2-3b
-# Output: 2025-12-09 18:02:23 POST /v1/chat/completions 127.0.0.1 200 "What is..." 305 22 1036
-```
+View server logs with flexible filtering.
 
-**Without `--verbose` on server:**
+**Log Types:**
+- **Activity logs** (default): HTTP request/response logs in compact format
+- **System logs** (`--system`): Server diagnostic output (stderr + stdout)
+
+**Basic usage:**
 ```bash
+# Activity logs (default) - HTTP requests
 llamacpp server logs llama-3.2-3b
-# Output: Only internal server logs (cache, slots) - no HTTP request logs
-```
-
-**More examples:**
+# Output: 2025-12-09 18:02:23 POST /v1/chat/completions 127.0.0.1 200 "What is..." 305 22 1036
 
-# Full HTTP JSON request/response
-llamacpp server logs llama-3.2-3b --http
+# System logs - diagnostics and errors
+llamacpp server logs llama-3.2-3b --system
 
 # Follow logs in real-time
 llamacpp server logs llama-3.2-3b --follow
 
-# Last 100 requests
+# Last 100 lines
 llamacpp server logs llama-3.2-3b --lines 100
+```
 
-# Show only errors
-llamacpp server logs llama-3.2-3b --errors
+**Advanced filtering:**
+```bash
+# System logs with errors only
+llamacpp server logs llama-3.2-3b --system --errors
 
-# Show all messages (including debug internals)
-llamacpp server logs llama-3.2-3b --verbose
+# Custom grep pattern
+llamacpp server logs llama-3.2-3b --system --filter "error|warning"
 
-# Custom filter pattern
-llamacpp server logs llama-3.2-3b --filter "error|warning"
+# Include health check requests (filtered by default)
+llamacpp server logs llama-3.2-3b --include-health
+```
 
-# Clear log file (truncate to zero bytes)
+**Log management:**
+```bash
+# Clear current log file (truncate to zero bytes)
 llamacpp server logs llama-3.2-3b --clear
 
 # Delete only archived logs (preserves current)
@@ -1278,15 +1238,15 @@ llamacpp server logs llama-3.2-3b --rotate
 **Options:**
 - `-f, --follow` - Follow log output in real-time
 - `-n, --lines <number>` - Number of lines to show (default: 50)
-- `--http` - Show full HTTP JSON request/response logs
-- `--errors` - Show only error messages
-- `--verbose` - Show all messages including debug internals
+- `--activity` - Show HTTP activity logs (default)
+- `--system` - Show system logs (all server output)
+- `--errors` - Filter system logs for errors only
 - `--filter <pattern>` - Custom grep pattern for filtering
-- `--stdout` - Show stdout instead of stderr (rarely needed)
+- `--include-health` - Include health check requests (/health, /slots, /props)
 - `--clear` - Clear (truncate) log file to zero bytes
 - `--clear-archived` - Delete only archived logs (preserves current logs)
 - `--clear-all` - Clear current logs AND delete all archived logs (frees most space)
-- `--rotate` - Rotate log file with timestamp (e.g., `server.2026-01-22-19-30-00.stderr`)
+- `--rotate` - Rotate log file with timestamp (e.g., `server.2026-01-22-19-30-00.http`)
 
 **Automatic Log Rotation:**
 Logs are automatically rotated when they exceed 100MB during:
@@ -1295,9 +1255,7 @@ Logs are automatically rotated when they exceed 100MB during:
 
 Rotated logs are saved with timestamps in the same directory: `~/.llamacpp/logs/`
 
-**Output Formats:**
-
-Default compact format:
+**Activity Log Format:**
 ```
 TIMESTAMP METHOD ENDPOINT IP STATUS "MESSAGE..." TOKENS_IN TOKENS_OUT TIME_MS
 ```
@@ -1306,10 +1264,7 @@ The compact format shows one line per HTTP request and includes:
 - User's message (first 50 characters)
 - Token counts (prompt tokens in, completion tokens out)
 - Total response time in milliseconds
-
-**Note:** Verbose logging is now enabled by default. HTTP request logs are available by default.
-
-Use `--http` to see full request/response JSON, or `--verbose` option to see all internal server logs.
+- Health checks filtered by default (use `--include-health` to show)
 
 ## Configuration
 
@@ -1322,11 +1277,14 @@ llamacpp-cli stores its configuration in `~/.llamacpp/`:
 ├── admin.json            # Admin service configuration (includes API key)
 ├── servers/              # Server configurations
 │   └── <server-id>.json
-├── logs/                 # Server logs
-│   ├── <server-id>.stdout
-│   ├── <server-id>.stderr
-│   ├── router.{stdout,stderr,log}
-│   └── admin.{stdout,stderr}
+├── logs/                 # All service logs
+│   ├── <server-id>.http      # Activity: HTTP request logs
+│   ├── <server-id>.stderr    # System: diagnostics
+│   ├── <server-id>.stdout    # System: additional output
+│   ├── router.stdout         # Router activity logs
+│   ├── router.stderr         # Router system logs
+│   ├── admin.stdout          # Admin activity logs
+│   └── admin.stderr          # Admin system logs
 └── history/              # Historical metrics (TUI)
     └── <server-id>.json
 ```
@@ -1344,6 +1302,12 @@ llamacpp-cli automatically configures optimal settings based on model size:
 
 All servers include `--embeddings` and `--jinja` flags by default.
 
+**GPU Layers explained:**
+- **Default: 60** - Conservative value that works reliably on all Apple Silicon devices
+- **-1 (all)** - Maximum performance, uses all available GPU layers. May cause OOM on very large models with limited VRAM.
+- **0 (CPU only)** - Useful for testing or when GPU is busy with other tasks
+- **Specific number** - Fine-tune based on your GPU memory and model size
+
 ## How It Works
 
 llamacpp-cli uses macOS launchctl to manage llama-server processes:
@@ -1353,7 +1317,7 @@ llamacpp-cli uses macOS launchctl to manage llama-server processes:
 3. Starts the server with `launchctl start`
 4. Monitors status via `launchctl list` and `lsof`
 
-Services are named `com.llama.<model-id>`.
+Services are named `studio.appkit.llamacpp-cli.<model-id>`.
 
 **Auto-Restart Behavior:**
 - When you **start** a server, it's registered with launchd and will auto-restart on crash
@@ -1361,8 +1325,8 @@ Services are named `com.llama.<model-id>`.
 - Crashed servers will automatically restart (when loaded)
 
 **Router and Admin Services:**
-- The **Router** (`com.llama.router`) provides a unified OpenAI-compatible endpoint for all models
-- The **Admin** (`com.llama.admin`) provides REST API + web UI for remote management
+- The **Router** (`studio.appkit.llamacpp-cli.router`) provides a unified OpenAI-compatible endpoint for all models
+- The **Admin** (`studio.appkit.llamacpp-cli.admin`) provides REST API + web UI for remote management
 - Both run as launchctl services similar to individual model servers
 
 ## Known Limitations
@@ -1423,6 +1387,36 @@ Or regenerate a new one:
 llamacpp admin config --regenerate-key --restart
 ```
 
+### `llamacpp migrate-labels`
+Migrate service labels from old format (`com.llama.*`) to new format (`studio.appkit.llamacpp-cli.*`).
+
+> **Note:** This command is automatically triggered on first run after upgrading from versions prior to v2.1.0.
+
+```bash
+# Show what would be migrated without making changes
+llamacpp migrate-labels --dry-run
+
+# Perform migration (with confirmation prompt)
+llamacpp migrate-labels
+
+# Skip confirmation prompt
+llamacpp migrate-labels --force
+```
+
+**What it does:**
+1. Creates a backup of all current configurations
+2. Stops running services
+3. Updates service labels and plist files
+4. Restarts services that were running
+5. Creates a marker file to prevent re-migration
+
+**Troubleshooting:**
+If migration fails, configurations are automatically rolled back. You can also manually rollback:
+
+```bash
+llamacpp rollback-labels
+```
+
 ## Development
 
 ### CLI Development
@@ -1538,7 +1532,7 @@ Contributions are welcome! If you'd like to contribute:
 **CLI Development:**
 - Use `npm run dev -- <command>` to test commands without building
 - Check logs with `llamacpp server logs <server> --errors` when debugging
-- Test launchctl integration with `launchctl list | grep com.llama`
+- Test launchctl integration with `launchctl list | grep studio.appkit.llamacpp-cli`
 - All server configs are in `~/.llamacpp/servers/`
 - Test interactive chat with `npm run dev -- server run <model>`