1588 Usage 706db835

# Promptheus Usage Guide

This document provides comprehensive coverage of Promptheus command-line interface patterns, operational modes, and integration workflows.

## Operational Modes

### Interactive Session (REPL)

**Invocation:**
```bash
promptheus
```

**Characteristics:**
- Persistent session maintaining provider, model, and flag configuration across multiple prompt executions
- Command history with arrow-key navigation
- Built-in session management commands: `/history`, `/load <n>`, `/clear-history`
- Session termination via `exit`, `quit`, or `Ctrl+C`

**Use Cases:**
- Multi-prompt workflows requiring consistent configuration
- Exploratory prompt development with iterative refinement
- Rapid prototyping with immediate feedback

### Single Execution Mode

**Invocation Patterns:**
```bash
# Inline argument
promptheus "Write a haiku"

# File input (flag syntax)
promptheus -f idea.txt

# File input (shorthand syntax)
promptheus @idea.txt

# Standard input
cat idea.txt | promptheus
```

**Use Cases:**
- Automated processing pipelines
- Script integration
- Batch operations
- Single-purpose prompt execution

## Input Source Specification

**Available Methods:**

| Method | Syntax | Description |
|--------|--------|-------------|
| File flag | `-f <path>` | Explicit file path specification |
| @ shorthand | `@<path>` | Abbreviated file input syntax |
| Standard input | (pipe) | Stream-based input via stdin |

## Pipeline Integration and Stream Processing

Promptheus implements clean stdout/stderr stream separation for integration with Unix pipelines and command substitution workflows.

### Standard Pipeline Operations

**Basic Patterns:**
```bash
# Automatic quiet mode activation when stdout is piped
promptheus "Write a story" | cat
promptheus "Explain Docker" | less

# File redirection (interactive prompts on stderr)
promptheus "Write docs" > output.txt

# Integration with external AI toolchains
promptheus "Create a haiku" | claude exec
promptheus "Write code" | codex run
```

### Command Substitution Patterns

**Shell Integration:**
```bash
# Feed refined output to external tools
claude "$(promptheus 'Write a technical prompt')"
codex "$(promptheus 'Generate function spec')"

# Variable capture for scripting
REFINED=$(promptheus "Optimize this query")
echo "$REFINED" | mysql -u user -p
```

### Unix Utility Integration

**Standard Utility Patterns:**
```bash
# Simultaneous file save and display
promptheus "Long explanation" | tee output.txt

# Output filtering
promptheus "List best practices" | grep -i "security"

# Metrics extraction
promptheus "Write essay" | wc -w

# Stream transformation
promptheus "Generate list" | sed 's/^/- /' > checklist.md

# Multi-file composition
cat template.txt | promptheus | cat header.txt - footer.txt > final.txt
```

### JSON Output Processing

**Structured Data Manipulation:**
```bash
# Extract specific fields
promptheus -o json "Create API schema" | jq '.endpoints'
promptheus -o json "Config template" | jq -r '.settings.database'

# Format and persist
promptheus -o json "Data structure" | jq '.' > formatted.json
```

### Advanced Integration Patterns

**Complex Workflow Examples:**
```bash
# Batch processing
cat prompts.txt | while read line; do
  promptheus "$line" >> results.txt
done

# Conditional execution
if promptheus "Check status" | grep -q "success"; then
  echo "All systems operational"
fi

# Multi-stage processing pipeline
promptheus "Draft outline" | \
  promptheus "Expand this outline" | \
  tee expanded.txt

# Parallel execution (GNU parallel)
cat prompts.txt | parallel -j 4 "promptheus {} > output_{#}.txt"

# Stream-specific error handling
promptheus "Generate code" 2> errors.log > output.txt
```

### Output Format Specification

**Format Control:**
```bash
# Plain text output (default)
promptheus -o plain "Write haiku"

# Structured JSON output with metadata
promptheus -o json "Create schema"

# Explicit plain text specification
promptheus -o plain "Write story" > story.txt
```

## Authentication Management

### Interactive Authentication Setup

The `auth` subcommand provides an interactive workflow for configuring provider API keys:

```bash
# Interactive provider selection
promptheus auth

# Direct provider specification
promptheus auth google
promptheus auth anthropic
promptheus auth openai

# Skip validation for testing
promptheus auth openai --skip-validation
```

**Authentication Workflow:**

1. **Provider Selection**: If no provider specified, displays interactive menu with priority ordering
2. **API Key URL**: System displays provider-specific API key acquisition URL when available
3. **Key Input**: User enters API key via secure password prompt (input masked)
4. **Validation**: System validates key against provider API (unless `--skip-validation` flag used)
5. **Storage**: Valid key saved to `.env` file with appropriate environment variable

**Features:**
- Automatic `.env` file creation and management
- API key format validation
- Live API connectivity testing
- Support for all configured providers
- Recommended providers highlighted in selection menu

## Subcommand Architecture

Promptheus implements a subcommand-based interface for utility operations:

### Environment Validation
```bash
# Basic validation
promptheus validate

# Test live API connectivity
promptheus validate --test-connection

# Provider-specific validation
promptheus validate --providers openai,google
```

### Model Discovery
```bash
# List all available models
promptheus list-models

# Provider-filtered listing
promptheus list-models --providers openai

# Limited output
promptheus list-models --limit 10
```

### Environment Template Generation
```bash
# Generate multi-provider template
promptheus template openai,google

# Alternative syntax
promptheus template --providers openai,anthropic
```

### History Management
```bash
# Display history
promptheus history

# Limited history display
promptheus history --limit 50

# Purge history
promptheus history --clear
```

### Telemetry & Analytics
```bash
# Display telemetry summary (aggregate metrics only, no sensitive data)
promptheus telemetry summary
```

**Telemetry Data Collected:**
- Performance metrics: processing latency, LLM latency, total run time
- Usage patterns: task types (analysis/generation), question counts, skip/refine modes
- Provider metrics: provider name, model, token usage (when available)
- Environment: Python version, platform, interface type (cli/web/mcp)
- Success rates and error types (sanitized)

**Privacy Features:**
- No prompts, API keys, or sensitive data stored
- Local JSONL storage only (default: same directory as history)
- Can be disabled: `export PROMPTHEUS_TELEMETRY_ENABLED=0`
- Custom storage location: `export PROMPTHEUS_TELEMETRY_FILE=/path/to/file.jsonl`
- Sampling rate control: `export PROMPTHEUS_TELEMETRY_SAMPLE_RATE=0.5` (50% of runs)

### Shell Completion Installation
```bash
# Bash completion script generation
promptheus completion bash

# Zsh completion script generation
promptheus completion zsh

# Automatic installation
promptheus completion --install
```

### Stream Behavior Characteristics

**Automatic Adjustments:**
- **Auto-quiet**: Quiet mode activation when stdout is piped
- **stderr routing**: UI elements (questions, status messages) directed to stderr
- **stdout isolation**: Refined output exclusively on stdout
- **Non-interactive detection**: Question workflow bypass when stdin is piped

## Refinement Workflow Modes

| Mode | Flag | Behavior |
| --- | --- | --- |
| Adaptive (default) | None | Automatic task classification determines question workflow activation |
| Skip Questions | `-s` / `--skip-questions` | Bypass interactive questions, apply direct enhancement |
| Refine | `-r` / `--refine` | Force interactive question workflow regardless of task type |

**Flag Composition:**
Flags may be combined. Example: `promptheus -s -c @brief.md`

## Provider and Model Selection

### Auto-Detection
The system auto-detects available providers based on configured API keys in the `.env` file. The supported providers are: google, anthropic, openai, groq, qwen, glm.

### Manual Override

**Provider Selection:**
```bash
promptheus --provider google "Idea"
promptheus --provider anthropic "Idea"
promptheus --provider openai "Idea"
promptheus --provider groq "Idea"
promptheus --provider qwen "Idea"
promptheus --provider glm "Idea"
```

**Model Selection:**
```bash
promptheus --model gemini-1.5-pro "Idea"
promptheus --model claude-3-5-sonnet-20241022 "Idea"
promptheus --model gpt-4o "Idea"
promptheus --model llama-3.1-70b-versatile "Idea"
```

**Supported Providers:** google, anthropic, openai, groq, qwen, glm

**Model Discovery:**
```bash
promptheus list-models
promptheus list-models --providers openai,google

# Include non-text-generation models (embeddings, TTS, etc.)
promptheus list-models --include-nontext
```

**Model Cache Management:**
Model information is dynamically fetched from the models.dev API and cached locally for 24 hours:
```bash
# Cache location: ~/.promptheus/models_cache.json
# Cache refreshes automatically when expired

# In Web UI:
# Use the "Refresh Model Cache" button in Settings to manually refresh cache
```

### Provider Validation and Configuration

**Interactive Provider Setup:**
```bash
# Interactive setup for any provider
promptheus auth

# Setup for specific provider
promptheus auth openai
promptheus auth google
```

**Validation:**
```bash
# Validate provider configuration
promptheus validate --providers google,openai

# Test API connectivity
promptheus validate --test-connection
```

### Provider Management in Web UI

The web interface provides comprehensive provider management features:

- **Provider Selection:** Dropdown to switch between configured providers
- **Model Selection:** Per-provider model selection with available model listing
- **API Key Management:** Secure API key storage and validation
- **Availability Status:** Visual indicators showing which providers are configured and available
- **Provider-Specific Configuration:** Model-specific settings and options

**Supported Provider Configuration:**
- Google: Requires `GOOGLE_API_KEY`
- OpenAI: Requires `OPENAI_API_KEY`
- Anthropic Claude: Requires `ANTHROPIC_API_KEY`
- Groq: Requires `GROQ_API_KEY`
- Alibaba Cloud Qwen: Requires `DASHSCOPE_API_KEY`
- Zhipu AI GLM: Requires `ZHIPUAI_API_KEY`

## Output Control Flags

| Flag | Function |
|------|----------|
| `-c` / `--copy` | Copy refined output to system clipboard |
| `-o` / `--output-format` | Specify format: `plain` or `json` |

**Composite Usage:**
```bash
promptheus -s -c -o json "Pitch deck outline"
```

## History Management System

### Command-Line Interface
```bash
promptheus history                 # Display all history
promptheus history --limit 50      # Display last 50 entries
promptheus history --clear         # Purge history
```

### Interactive Mode Commands
- `/history` - Display session history
- `/load <n>` - Load entry at index n
- `/clear-history` - Purge all history
- Arrow key navigation (↑/↓) for recent prompts
- `/copy` - Copy last refined result to clipboard
- `/status` - Display current session configuration

### Web UI History Features

The web interface provides enhanced history management capabilities:

- **Paginated History View:** Displays history entries with pagination controls
- **Search and Filter:** Find specific entries by content or timestamp
- **Provider and Model Information:** Each history entry includes the provider and model used
- **Click to Load:** Click any history entry to load both the original prompt and refined output
- **Individual Entry Deletion:** Delete specific entries without clearing all history
- **Bulk Clear:** Clear all history entries with confirmation
- **Metadata Display:** Shows timestamp, task type, provider, and model for each entry

### Storage Characteristics
- Automatic persistence of refined prompts
- Metadata includes timestamps, task classifications, provider, model, original and refined versions
- Local storage with no external transmission
- JSONL format for efficient append-only operations
- Default location: `~/.promptheus` (Unix/Mac) or `%APPDATA%/promptheus` (Windows)
- Customizable location: `export PROMPTHEUS_HISTORY_DIR=/custom/path`

## Iterative Refinement Interface

Post-refinement, the system offers an iterative modification workflow:

```
Tweak? (Enter to accept, or describe your change): make it punchier
```

**Modification Commands:**
- Natural language instructions: "make it more formal", "remove the section on pricing", "add a call-to-action"
- Each modification applies targeted AI-based editing
- Empty input (Enter) accepts current version

## Command Reference Summary

### Authentication Commands

| Command | Description |
|---------|-------------|
| `promptheus auth` | Interactive provider selection and API key configuration |
| `promptheus auth <provider>` | Configure specific provider |
| `promptheus auth <provider> --skip-validation` | Skip API key validation |

### Utility Commands

| Command | Description |
|---------|-------------|
| `promptheus --help` | Display usage information |
| `promptheus --version` | Display version information |
| `promptheus list-models` | Display available providers and models |
| `promptheus validate` | Validate API configuration |
| `promptheus validate --test-connection` | Test live API connectivity |
| `promptheus template <providers>` | Generate environment template |

### History Commands

| Command | Description |
|---------|-------------|
| `promptheus history` | Display all history |
| `promptheus history --limit N` | Display last N entries |
| `promptheus history --clear` | Purge history |

## Workflow Examples

### Content Generation with Interactive Refinement
```
$ promptheus "Write a blog post"
✓ Creative task detected with clarifying questions
Ask clarifying questions to refine your prompt? (Y/n): y
...
╭─ Refined Prompt ───────────────────────────────╮
│ Write a thought-provoking blog post on AI ethics│
│ ... include real-world examples ...             │
╰─────────────────────────────────────────────────╯
```

### Analysis Task with Question Bypass
```
$ promptheus -s "Analyze the main.py file and explain the key functions"
✓ Skip questions mode - improving prompt directly
╭─ Refined Prompt ───────────────────────────────╮
│ [Improved prompt shown here]                   │
╰────────────────────────────────────────────────╯
```

## Environment Configuration Template Generation

Generate `.env` file templates for provider configuration:

```bash
# Single provider template
promptheus template openai > .env

# Multi-provider template
promptheus template openai,google,anthropic > .env
```

## Python Version Compatibility

### Python 3.14 Support Status

**Gemini Provider:** Full support via unified `google-genai` SDK

**Other Providers:** Compatibility status varies by SDK version

**Mitigation Strategies:**
1. Monitor provider SDK updates for Python 3.14 compatibility
2. Use Python 3.10-3.13 for providers without Python 3.14 support
3. Utilize virtual environments for version management

## Interactive Mode Features

### Keyboard Bindings

| Key Combination | Function |
|----------------|----------|
| Enter | Submit prompt |
| Shift+Enter | Insert newline (multiline mode) |
| Option/Alt+Enter | Insert newline (alternative) |
| Ctrl+J | Insert newline (alternative) |
| ↑/↓ Arrow Keys | Navigate command history |
| Tab | Display command completion suggestions |

### Slash Command Reference

**Information and Navigation:**

| Command | Function |
|---------|----------|
| `/help` | Display available commands |
| `/history` | Display recent prompts |
| `/load <n>` | Load prompt at index n |
| `/clear-history` | Purge history |
| `/about` | Display version and configuration |
| `/bug` | Access bug report interface |

**Session Configuration:**

| Command | Function |
|---------|----------|
| `/status` | Display current settings |
| `/set provider <name>` | Modify active provider |
| `/set model <name>` | Modify active model |
| `/toggle refine` | Toggle refinement mode |
| `/toggle skip-questions` | Toggle question bypass mode |

**Utility Operations:**

| Command | Function |
|---------|----------|
| `/copy` | Copy last refined result to clipboard |

## Web UI Features

Promptheus includes a modern Web UI accessible via the `web` subcommand for browser-based prompt refinement workflows.

### Starting the Web UI

**Basic Usage:**
```bash
promptheus web
```

**With Custom Options:**
```bash
# Specify custom port
promptheus web --port 3000

# Use different host (default: 127.0.0.1)
promptheus web --host 0.0.0.0

# Start server without opening browser
promptheus web --no-browser
```

**Web UI Features:**
- Modern, responsive interface with dark theme
- Real-time prompt refinement with streaming responses
- Interactive question-and-answer workflows
- Prompt history with pagination and search
- Provider and model selection controls
- API key management and validation
- Prompt tweaking and iterative refinement
- Copy-to-clipboard functionality
- Settings management for configuration

### Web UI Command Reference

| Command | Description |
|---------|-------------|
| `promptheus web` | Start the web server and open browser automatically |
| `promptheus web --port N` | Start server on specific port (default: auto-find) |
| `promptheus web --host hostname` | Bind to specific host (default: 127.0.0.1) |
| `promptheus web --no-browser` | Start server without opening browser |

**Web UI Security:**
- Server binds to localhost (127.0.0.1) by default for security
- CORS restricted to local origins only
- All API endpoints require same-origin requests
- API keys are masked in the UI and never exposed in client-side code

## MCP Server Integration

Promptheus includes a **Model Context Protocol (MCP) server** that exposes prompt refinement capabilities as standardized tools for integration with MCP-compatible clients.

### Starting the MCP Server

```bash
# Start the MCP server
promptheus mcp

# Or run directly with Python
python -m promptheus.mcp_server
```

**Prerequisites:**
- MCP package installed: `pip install mcp` (included in requirements.txt)
- At least one provider API key configured (see [Authentication Management](#authentication-management))

### Available MCP Tools

The MCP server exposes five core tools:

#### `refine_prompt`
Intelligent prompt refinement with optional clarification questions.

**Workflow:**
1. Call with initial prompt: `refine_prompt("Write a blog post")`
2. Handle response types:
   - `{"type": "refined", "prompt": "..."}`: Success with refined prompt
   - `{"type": "clarification_needed", "questions_for_ask_user_question": [...]}`: Questions needed
   - `{"type": "error", "error_type": "...", "message": "..."}`: Error occurred
3. If clarification needed, use AskUserQuestion tool with provided questions
4. Call again with answers: `refine_prompt(prompt, answers={"q0": "answer"}, answer_mapping={...})`

#### `tweak_prompt`
Apply targeted modifications to existing prompts.

**Usage:** `tweak_prompt(prompt, modification="make it shorter")`

#### `list_models`
Discover available models from configured providers.

**Usage:** `list_models(providers=["google", "openai"], limit=10)`

#### `list_providers`
Check provider configuration status.

**Usage:** `list_providers()` - Returns configuration status for all providers

#### `validate_environment`
Test environment configuration and API connectivity.

**Usage:** `validate_environment(test_connection=True)` - Validates config and tests API connectivity

### MCP Server Integration Patterns

**Basic Refinement:**
```bash
# Client calls refine_prompt with basic prompt
# Server returns either refined prompt or clarification questions
# Client handles AskUserQuestion workflow if needed
```

**Pipeline Integration:**
```bash
# MCP server can be integrated into AI toolchains
# Use refined prompts with other LLM providers
# Maintain session state across multiple refinement operations
```

**Error Handling:**
```bash
# All MCP tools return structured error responses
# Consistent error format across all operations
# Detailed error messages for troubleshooting
```

### MCP Server Configuration

**Environment Setup:**
```bash
# Ensure MCP package is available
pip install mcp

# Configure provider API keys
promptheus auth google  # or any supported provider

# Validate configuration
promptheus validate --test-connection
```

**Integration Requirements:**
- MCP-compatible client that supports tool calling
- AskUserQuestion tool support for interactive clarification
- JSON processing capabilities for structured responses