CLI API Reference

Complete reference for PromptKit’s command-line interface and CLI utilities.

Overview

PromptKit provides a comprehensive command-line interface for prompt management, execution, and development workflows. The CLI is designed to integrate seamlessly with development pipelines and supports both interactive and batch operations.

Installation and Setup

The CLI is automatically available after installing PromptKit:

pip install promptkit-core
promptkit --help

Environment Configuration

Set up environment variables for common configurations:

# OpenAI Configuration
export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="gpt-4"

# Azure OpenAI Configuration
export AZURE_OPENAI_API_KEY="your-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_DEPLOYMENT="your-deployment"

# Anthropic Configuration
export ANTHROPIC_API_KEY="your-key"

# Default prompt directory
export PROMPTKIT_PROMPT_DIR="./prompts"

Main Command: promptkit

Global Options

promptkit [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS]

Global Options:
  --config PATH              Configuration file path [default: ~/.promptkit/config.yaml]
  --prompt-dir PATH          Directory containing prompt files [default: ./prompts]
  --engine TEXT              Engine to use [default: openai]
  --verbose, -v              Enable verbose logging
  --quiet, -q                Suppress output except errors
  --format [json|yaml|text]  Output format [default: text]
  --help                     Show help message
  --version                  Show version information

Core Commands

run - Execute Prompts

Execute a prompt with input data.

promptkit run PROMPT_NAME [OPTIONS]

Options:
  --input PATH               JSON/YAML file with input data
  --input-json TEXT          Input data as JSON string
  --var KEY=VALUE            Set individual input variables (multiple allowed)
  --output PATH              Save output to file
  --stream                   Enable streaming output
  --temperature FLOAT        Sampling temperature [0.0-2.0]
  --max-tokens INTEGER       Maximum tokens to generate
  --top-p FLOAT             Nucleus sampling parameter [0.0-1.0]
  --stop TEXT               Stop sequence (multiple allowed)
  --cost-estimate           Show cost estimate before execution
  --dry-run                 Validate inputs without execution

Examples:
  # Run with input file
  promptkit run summarize --input data.json

  # Run with inline variables
  promptkit run greet --var name="John" --var age=30

  # Run with streaming
  promptkit run write_story --var topic="space" --stream

  # Estimate cost first
  promptkit run analyze_data --input large_dataset.json --cost-estimate

list - List Available Prompts

List and search prompts in the prompt directory.

promptkit list [OPTIONS]

Options:
  --search TEXT              Search prompts by name or description
  --tag TEXT                 Filter by tag (multiple allowed)
  --format [table|json|yaml] Output format [default: table]
  --show-details             Show detailed information
  --show-schema              Include input schema information

Examples:
  # List all prompts
  promptkit list

  # Search prompts
  promptkit list --search "analysis"

  # Filter by tags
  promptkit list --tag data --tag report

  # Detailed view with schemas
  promptkit list --show-details --show-schema

validate - Validate Prompts

Validate prompt files and input data.

promptkit validate [PROMPT_NAME] [OPTIONS]

Options:
  --input PATH               Validate specific input file
  --input-json TEXT          Validate JSON input string
  --schema-only              Only validate schema, not template
  --fix                      Attempt to fix common issues
  --strict                   Enable strict validation mode

Examples:
  # Validate all prompts
  promptkit validate

  # Validate specific prompt
  promptkit validate user_profile

  # Validate with input data
  promptkit validate user_profile --input test_data.json

  # Schema validation only
  promptkit validate user_profile --schema-only

create - Create New Prompts

Create new prompt files from templates or interactively.

promptkit create PROMPT_NAME [OPTIONS]

Options:
  --template TEXT            Template to use [basic|chat|analysis|creative]
  --interactive, -i          Interactive prompt creation
  --description TEXT         Prompt description
  --input-schema PATH        Input schema file (JSON/YAML)
  --output PATH              Output file path
  --tags TEXT                Comma-separated tags
  --overwrite                Overwrite existing prompt

Examples:
  # Interactive creation
  promptkit create my_prompt --interactive

  # Create from template
  promptkit create analysis_prompt --template analysis

  # Create with metadata
  promptkit create report_gen --description "Generate reports" --tags "report,business"

edit - Edit Prompts

Edit existing prompts with validation.

promptkit edit PROMPT_NAME [OPTIONS]

Options:
  --editor TEXT              Editor to use [default: $EDITOR]
  --validate                 Validate after editing
  --backup                   Create backup before editing
  --field TEXT               Edit specific field [template|schema|description]

Examples:
  # Edit prompt in default editor
  promptkit edit user_profile

  # Edit specific field
  promptkit edit user_profile --field template

  # Edit with auto-validation
  promptkit edit user_profile --validate

test - Test Prompts

Run test suites for prompts.

promptkit test [PROMPT_NAME] [OPTIONS]

Options:
  --test-file PATH           Test configuration file
  --input-dir PATH           Directory with test input files
  --output-dir PATH          Directory to save test outputs
  --baseline PATH            Baseline results for comparison
  --coverage                 Generate test coverage report
  --parallel INTEGER         Number of parallel test workers
  --timeout INTEGER          Test timeout in seconds

Examples:
  # Test all prompts
  promptkit test

  # Test specific prompt
  promptkit test summarize --test-file tests/summarize_tests.yaml

  # Run with baseline comparison
  promptkit test --baseline results/baseline.json

init - Initialize Project

Initialize a new PromptKit project.

promptkit init [PROJECT_NAME] [OPTIONS]

Options:
  --template TEXT            Project template [basic|advanced|enterprise]
  --engine TEXT              Default engine to configure
  --git                      Initialize git repository
  --examples                 Include example prompts
  --config                   Create configuration files

Examples:
  # Basic initialization
  promptkit init my_project

  # Advanced project with examples
  promptkit init ai_app --template advanced --examples --git

Engine Management

engine - Engine Operations

Manage and configure engines.

promptkit engine COMMAND [OPTIONS]

Commands:
  list                       List available engines
  info ENGINE               Show engine information
  configure ENGINE          Configure engine settings
  test ENGINE               Test engine connectivity
  benchmark ENGINE          Benchmark engine performance

Examples:
  # List available engines
  promptkit engine list

  # Show engine info
  promptkit engine info openai

  # Configure engine
  promptkit engine configure azure_openai

  # Test connectivity
  promptkit engine test anthropic

Batch Operations

batch - Batch Processing

Execute prompts in batch mode.

promptkit batch [OPTIONS]

Options:
  --jobs PATH                Batch job configuration file
  --input-dir PATH           Directory with input files
  --output-dir PATH          Directory for output files
  --workers INTEGER          Number of parallel workers [default: 4]
  --resume                   Resume interrupted batch job
  --progress                 Show progress bar
  --summary                  Generate summary report

Examples:
  # Run batch job
  promptkit batch --jobs batch_config.yaml --workers 8

  # Process directory of inputs
  promptkit batch --input-dir inputs/ --output-dir outputs/

  # Resume interrupted job
  promptkit batch --jobs batch_config.yaml --resume

Batch Configuration File

# batch_config.yaml
name: "Document Analysis Batch"
description: "Analyze multiple documents"

prompts:
  - name: "analyze_document"
    inputs_dir: "inputs/documents"
    output_dir: "outputs/analysis"
    input_pattern: "*.txt"

  - name: "summarize_document"
    inputs_dir: "inputs/documents"
    output_dir: "outputs/summaries"
    input_pattern: "*.txt"

engine:
  type: "openai"
  model: "gpt-4"
  temperature: 0.3

settings:
  parallel_workers: 4
  retry_attempts: 3
  timeout: 60

Development Commands

dev - Development Tools

Development and debugging utilities.

promptkit dev COMMAND [OPTIONS]

Commands:
  watch                      Watch prompts for changes and auto-validate
  serve                      Start development server with API
  debug PROMPT_NAME          Debug prompt execution
  profile PROMPT_NAME        Profile prompt performance
  export                     Export prompts to different formats

Examples:
  # Watch for changes
  promptkit dev watch --auto-test

  # Start dev server
  promptkit dev serve --port 8000

  # Debug prompt
  promptkit dev debug complex_analysis --verbose

  # Profile performance
  promptkit dev profile batch_process --iterations 100

export - Export Prompts

Export prompts to various formats.

promptkit export [OPTIONS]

Options:
  --format [openai|anthropic|json|yaml]  Export format
  --output PATH              Output file or directory
  --prompts TEXT             Specific prompts to export (comma-separated)
  --include-metadata         Include metadata in export
  --compress                 Compress output

Examples:
  # Export to OpenAI format
  promptkit export --format openai --output openai_prompts.json

  # Export specific prompts
  promptkit export --prompts "prompt1,prompt2" --format yaml

  # Export with compression
  promptkit export --compress --output prompts.tar.gz

Configuration Management

config - Configuration Operations

Manage PromptKit configuration.

promptkit config COMMAND [OPTIONS]

Commands:
  show                       Show current configuration
  set KEY VALUE              Set configuration value
  unset KEY                  Remove configuration value
  reset                      Reset to default configuration
  validate                   Validate configuration file

Examples:
  # Show configuration
  promptkit config show

  # Set default engine
  promptkit config set default_engine anthropic

  # Set API key
  promptkit config set engines.openai.api_key sk-...

  # Validate config
  promptkit config validate

Configuration File Format

# ~/.promptkit/config.yaml
default_engine: openai
prompt_directory: ./prompts
output_format: text

engines:
  openai:
    api_key: ${OPENAI_API_KEY}
    model: gpt-4
    temperature: 0.7
    max_tokens: 1000

  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
    model: claude-2
    max_tokens_to_sample: 1000

  azure_openai:
    api_key: ${AZURE_OPENAI_API_KEY}
    endpoint: ${AZURE_OPENAI_ENDPOINT}
    deployment_name: ${AZURE_OPENAI_DEPLOYMENT}

logging:
  level: INFO
  file: ~/.promptkit/logs/promptkit.log

cache:
  enabled: true
  ttl: 3600
  directory: ~/.promptkit/cache

development:
  auto_validate: true
  auto_reload: true
  debug_mode: false

Shell Integration

Shell Completion

Enable shell completion for better CLI experience:

# Bash
eval "$(_PROMPTKIT_COMPLETE=bash_source promptkit)"

# Zsh
eval "$(_PROMPTKIT_COMPLETE=zsh_source promptkit)"

# Fish
eval (env _PROMPTKIT_COMPLETE=fish_source promptkit)

Aliases and Functions

Useful shell aliases:

# ~/.bashrc or ~/.zshrc
alias pk="promptkit"
alias pkrun="promptkit run"
alias pklist="promptkit list"
alias pktest="promptkit test"

# Function for quick prompt execution
pkexec() {
    promptkit run "$1" --var "${@:2}"
}

# Function for interactive prompt creation
pknew() {
    promptkit create "$1" --interactive
}

Output Formats

JSON Output

promptkit run summarize --input data.json --format json

{
  "prompt_name": "summarize",
  "input_data": {...},
  "response": "Generated summary text...",
  "metadata": {
    "engine": "openai",
    "model": "gpt-4",
    "tokens_used": 150,
    "cost": 0.003,
    "duration": 2.5
  }
}

YAML Output

promptkit list --format yaml

prompts:
  - name: summarize
    description: Summarize text content
    tags: [text, analysis]
    schema:
      type: object
      properties:
        content: {type: string}
        max_length: {type: integer}

Error Handling

Exit Codes

• 0: Success

• 1: General error

• 2: Validation error

• 3: Engine error

• 4: Configuration error

• 5: File not found error

Common Error Messages

# Missing prompt
Error: Prompt 'unknown_prompt' not found in ./prompts

# Invalid input
Error: Input validation failed:
  - name: field required
  - age: must be a positive integer

# Engine error
Error: OpenAI API error (429): Rate limit exceeded

# Configuration error
Error: No API key configured for engine 'openai'

Advanced Usage

Pipeline Integration

# CI/CD pipeline example
#!/bin/bash
set -e

# Validate all prompts
promptkit validate

# Run test suite
promptkit test --coverage

# Generate documentation
promptkit export --format json --output dist/prompts.json

# Deploy prompts
promptkit batch --jobs deployment.yaml

Custom Scripts

#!/bin/bash
# process_documents.sh

INPUT_DIR="$1"
OUTPUT_DIR="$2"

for file in "$INPUT_DIR"/*.txt; do
    filename=$(basename "$file" .txt)
    echo "Processing $filename..."

    promptkit run analyze_document \
        --var content="$(cat "$file")" \
        --output "$OUTPUT_DIR/${filename}_analysis.txt"
done

This comprehensive CLI reference covers all aspects of using PromptKit from the command line, enabling efficient prompt development and deployment workflows.