Promptheus Usage Guide

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:

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:

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

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:

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

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

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

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

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

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

# 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

# Basic validation
promptheus validate

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

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

Model Discovery

# 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

# Generate multi-provider template
promptheus template openai,google

# Alternative syntax
promptheus template --providers openai,anthropic

History Management

# Display history
promptheus history

# Limited history display
promptheus history --limit 50

# Purge history
promptheus history --clear

Telemetry & Analytics

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

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:

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:

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:

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:

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

# Interactive setup for any provider
promptheus auth

# Setup for specific provider
promptheus auth openai
promptheus auth google

Validation:

# 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

Composite Usage:

promptheus -s -c -o json "Pitch deck outline"

History Management System

Command-Line Interface

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

Utility Commands

History Commands

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:

# 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

Slash Command Reference

Information and Navigation:

Session Configuration:

Utility Operations:

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:

promptheus web

With Custom Options:

# 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

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

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

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:

# Client calls refine_prompt with basic prompt
# Server returns either refined prompt or clarification questions
# Client handles AskUserQuestion workflow if needed

Pipeline Integration:

# MCP server can be integrated into AI toolchains
# Use refined prompts with other LLM providers
# Maintain session state across multiple refinement operations

Error Handling:

# All MCP tools return structured error responses
# Consistent error format across all operations
# Detailed error messages for troubleshooting

MCP Server Configuration

Environment Setup:

# 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