@appkit/llamacpp-cli 1.14.1 → 2.1.0

package/README.md

@@ -1,5 +1,7 @@
 # llamacpp-cli
 
+> **Note:** llamacpp-cli only works on **macOS** and requires [llama.cpp](https://github.com/ggerganov/llama.cpp) to be installed.
+
 > Manage llama.cpp servers like Ollama—but faster. Full control over llama-server with macOS launchctl integration.
 
 CLI tool to manage local llama.cpp servers on macOS. Provides an Ollama-like experience for managing GGUF models and llama-server instances, with **significantly faster response times** than Ollama.
@@ -12,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
@@ -19,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?
@@ -170,17 +173,21 @@ llamacpp
 
 ![Server Monitoring TUI](https://raw.githubusercontent.com/appkitstudio/llamacpp-cli/main/docs/images/monitor-detail.png)
 
-### Overview
+### Main Features
+
+**Dashboard** - Monitor all servers at a glance with real-time metrics (GPU, CPU, memory, token speed)
+
+**Server Management** - Create, start, stop, configure, and remove servers with inline editors
+
+**Model Management** (press `M`) - Browse local models, search/download from HuggingFace, delete with cascade
 
-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
+**Router Management** (press `R`) - Control router service, view configuration, access activity/system logs
 
-### Multi-Server Dashboard
+**Historical Charts** (press `H`) - View time-series graphs with Recent (1-3min) or Hour (60min) views
 
-The main view shows all your servers at a glance:
+**Logs** (press `L`) - Toggle between Activity (HTTP) and System (diagnostics) logs with auto-refresh
+
+### Dashboard View
 
 ```
 ┌─────────────────────────────────────────────────────────┐
@@ -190,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
 
@@ -377,7 +225,7 @@ The `llamacpp server monitor` command is deprecated. Use `llamacpp` instead to l
 
 ## Router (Unified Endpoint)
 
-The router provides a single OpenAI-compatible endpoint that automatically routes requests to the correct backend server based on the model name. This is perfect for LLM clients that don't support multiple endpoints.
+The router provides a single unified endpoint that automatically routes requests to the correct backend server based on the model name. Supports both OpenAI and Anthropic API formats. Perfect for LLM clients that don't support multiple endpoints.
 
 ### Quick Start
 
@@ -396,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
@@ -417,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:**
@@ -427,8 +289,8 @@ response = client.chat.completions.create(
 - `GET /v1/models` - List all available models from running servers
 
 **Anthropic-Compatible:**
-- `POST /v1/messages` - Anthropic Messages API (with tool calling support)
-- `POST /v1/messages/count_tokens` - Token counting
+- `POST /v1/messages` - Anthropic Messages API (with streaming and tool calling support)
+- `POST /v1/messages/count_tokens` - Token counting (estimated)
 - `GET /v1/models/{model}` - Retrieve specific model info
 
 **System:**
@@ -451,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
@@ -487,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
 
@@ -674,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
@@ -686,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 |
@@ -698,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
 
@@ -710,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 |
@@ -750,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.
@@ -809,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.
@@ -844,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
@@ -910,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
@@ -1079,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
@@ -1093,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]`
@@ -1102,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)
@@ -1122,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)
@@ -1136,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.
@@ -1145,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
 
@@ -1162,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
@@ -1171,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.
@@ -1226,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.
+
+**Log Types:**
+- **Activity logs** (default): HTTP request/response logs in compact format
+- **System logs** (`--system`): Server diagnostic output (stderr + stdout)
 
-**Without `--verbose` on server:**
+**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)
@@ -1276,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:
@@ -1293,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
 ```
@@ -1304,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
 
@@ -1320,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
 ```
@@ -1342,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:
@@ -1351,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
@@ -1359,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
@@ -1421,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
@@ -1536,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>`