Configuration

PUPT uses a flexible configuration system that allows you to customize its behavior at multiple levels. Configuration files are searched and merged in a specific order, giving you fine-grained control over your setup.

Configuration File Formats

PUPT supports multiple configuration file formats:

• .pt-config.json - JSON format
• .pt-config.yaml - YAML format
• .pt-config.js - JavaScript module (CommonJS or ESM)

Configuration Discovery

PUPT searches for configuration files in the following order (later files override earlier ones):

1. System directories (platform-specific)

   • Linux: /etc/pt/
   • macOS: /Library/Preferences/pt/
   • Windows: %ProgramData%\pt\

2. User home directory

   • ~/.pt-config.{json,yaml,js}

3. Parent directories (from root to current)

   • Searches each parent directory up to the current working directory

4. Current directory

   • ./.pt-config.{json,yaml,js}

Configuration Structure

Here's a complete configuration example with all available options:

{
  "promptDirs": ["./.prompts", "~/my-prompts"],
  "historyDir": "~/.pt/history",
  "annotationDir": "~/.pt/history",
  "defaultCmd": "claude",
  "defaultCmdArgs": ["--model", "claude-3-opus"],
  "defaultCmdOptions": {
    "Continue with context?": "--continue",
    "Use verbose output?": "--verbose"
  },
  "autoRun": false,
  "autoReview": false,
  "gitPromptDir": "~/.pt/git-prompts",
  "outputCapture": {
    "enabled": false,
    "directory": "~/.pt/outputs",
    "maxSizeMB": 10,
    "retentionDays": 30
  },
  "autoAnnotate": {
    "enabled": false,
    "analysisPrompt": "Analyze this execution and provide insights...",
    "fallbackRules": [
      {
        "pattern": "error|fail|exception",
        "status": "failure"
      }
    ]
  },
  "handlebarsExtensions": [],
  "helpers": {
    "header": {
      "type": "inline",
      "value": "Generated by {{username}} on {{date}}"
    },
    "footer": {
      "type": "file",
      "path": "~/.pt/partials/footer.md"
    }
  },
  "logLevel": "info",
  "version": "3.0.0"
}

Configuration Options

Core Settings

promptDirs

• Type: string[]
• Default: ["./.prompts"]
• Description: Directories to search for prompt files
• Example: ["./.prompts", "~/global-prompts", "./team-prompts"]

Prompt directories are searched recursively for .md files. Paths support:

• Relative paths (resolved from config file location)
• Home directory expansion (~)
• Environment variables ($HOME, %USERPROFILE%)

historyDir

• Type: string (optional)
• Default: undefined (history disabled)
• Description: Directory to save prompt execution history
• Example: "~/.pt/history"

When enabled, PUPT saves:

• Generated prompt content
• Execution metadata (timestamp, tool, arguments)
• Masked sensitive values (passwords, API keys)

annotationDir

• Type: string (optional)
• Default: undefined (annotations disabled)
• Description: Directory for storing annotations
• Example: "~/.pt/history"

Annotations include:

• Success/failure status
• Custom notes and observations
• Tags for categorization

Tool Integration

defaultCmd

• Type: string
• Default: "claude"
• Description: Default command for pt run
• Example: "claude", "gpt", "code -"

defaultCmdArgs

• Type: string[]
• Default: []
• Description: Arguments always passed to the default command
• Example: ["--model", "claude-3-opus", "--temperature", "0.7"]

defaultCmdOptions

• Type: object
• Default: { "Continue with last context?": "--continue" }
• Description: Interactive options presented before execution
• Example:

  {
    "Continue with context?": "--continue",
    "Use verbose output?": "--verbose",
    "Enable streaming?": "--stream"
  }

Automation Features

autoRun

• Type: boolean
• Default: false
• Description: Automatically execute prompts after generation
• Note: Requires defaultCmd to be configured

autoReview

• Type: boolean
• Default: false
• Description: Automatically review files selected with {{reviewFile}}
• Note: Useful for analyzing generated outputs

outputCapture

• Type: object
• Description: Configure command output capture
• Properties:
  • enabled: Enable output capture
  • directory: Where to save outputs
  • maxSizeMB: Maximum file size limit
  • retentionDays: How long to keep outputs

autoAnnotate

• Type: object
• Description: Automatic annotation based on output patterns
• Properties:
  • enabled: Enable auto-annotation
  • triggers: (Optional) Array of prompt names that trigger annotation. If omitted or empty, all prompts will trigger auto-annotation when enabled
  • analysisPrompt: Prompt for AI analysis
  • fallbackRules: Pattern-based rules for status detection

Template Extensions

handlebarsExtensions

• Type: string[]
• Default: []
• Description: Paths to custom Handlebars helpers
• Example: ["./helpers/custom.js", "~/.pt/helpers/"]

helpers

• Type: object
• Description: Define reusable template snippets
• Structure:

  {
    "helperName": {
      "type": "inline|file",
      "value": "content" // for inline
      "path": "path/to/file" // for file
    }
  }

Other Settings

gitPromptDir

• Type: string
• Default: "~/.pt/git-prompts"
• Description: Directory for prompts installed from Git repositories

logLevel

• Type: string
• Default: "info"
• Options: "debug", "info", "warn", "error"
• Description: Logging verbosity level

version

• Type: string
• Description: Configuration schema version

Environment Variables

PUPT also respects these environment variables:

• PT_CONFIG_PATH: Override config file search path
• PT_LOG_LEVEL: Override log level
• EDITOR / VISUAL: Default editor for prompt creation
• NO_COLOR: Disable colored output

Configuration Examples

Minimal Configuration

{
  "promptDirs": ["./prompts"]
}

Team Configuration

promptDirs:
  - ./team-prompts
  - ~/.pt/personal-prompts
  
defaultCmd: claude
defaultCmdArgs:
  - --model
  - claude-3-opus
  - --project
  - team-project

historyDir: ~/.pt/team-history
annotationDir: ~/.pt/team-history

Advanced Configuration with Custom Helpers

module.exports = {
  promptDirs: ['./prompts'],
  
  helpers: {
    signature: {
      type: 'inline',
      value: '---\nGenerated by {{username}} at {{datetime}}'
    },
    disclaimer: {
      type: 'file',
      path: './templates/disclaimer.md'
    }
  },
  
  handlebarsExtensions: ['./helpers/math.js', './helpers/format.js'],
  
  autoAnnotate: {
    enabled: true,
    triggers: ['claude', 'fix-errors'],
    analysisPrompt: 'analyze-execution'
  }
}

Configuration Best Practices

1. Use project-specific configs: Place .pt-config.json in project roots
2. Share team settings: Version control your team's configuration
3. Keep secrets secure: Never commit API keys or passwords
4. Use relative paths: Make configurations portable across machines
5. Document custom helpers: Include comments explaining custom functionality

For more details on specific commands and options, see the Commands Reference.