proplate 0.3.0

A CLI tool for managing and using prompt templates with placeholder injection.

Proplate

A CLI tool for managing and using prompt templates with placeholder injection. Perfect for storing reusable prompt templates and quickly filling them with context-specific information.

Features

• 🎯 Interactive template selection with fuzzy search
• ⚡ Direct template access with tab autocomplete
• 📋 Auto-copy to clipboard for seamless pasting
• 🔧 Placeholder support with single-line and multi-line input
• ✨ Default values for placeholders with {{name:default}} syntax
• 📝 YAML frontmatter for template metadata
• 🎨 Rich CLI output with beautiful formatting

Installation

pip install proplate

Quick Start

1. Create a template

Easy way:

proplate new code-review

This opens your editor with starter content:

---
title: Code Review
description: Add a description here
---

# {{placeholder}}

Your template content goes here.
Use {{placeholder}} syntax for variables.

Or manually create ~/.proplate/templates/code-review.md:

---
title: Code Review Guide
description: Template for thorough code reviews
---

# Code Review: {{file_path}}

## Context
{{context}}

## Review Areas
{{focus_areas}}

## Security Considerations
{{security_notes}}

Pro tip: Make placeholders self-documenting!

{{Your feature request here. Be specific about WHAT and WHY.}}

This way, the placeholder itself tells users what to enter.

2. Use your template

Interactive mode (with fuzzy search):

proplate

Direct selection (with tab autocomplete):

proplate code-review

The tool will:

1. Prompt you for each {{placeholder}}
2. Support multi-line input when needed
3. Automatically copy the filled template to your clipboard
4. You can then paste directly into Cursor, ChatGPT, or any other tool

Usage

Main Commands

# Interactive template selector
proplate

# Use a specific template (supports tab completion)
proplate <template-name>

# Create a new template (opens in $EDITOR with starter content)
proplate new <template-name>

# List all available templates
proplate list

# Show template contents with beautiful formatting
proplate show <template-name>

# Edit an existing template in $EDITOR
proplate edit <template-name>

# Delete a template (with confirmation)
proplate delete <template-name>

# Delete a template without confirmation
proplate delete <template-name> --force

# Show templates directory path
proplate path

# Initialize templates directory (optional - auto-created on first use)
proplate init

Managing Templates

Create a new template:

proplate new my-template

Creates a template with starter content and opens it in your $EDITOR.

View template contents:

proplate show my-template

Display template with beautiful formatting including:

• Template metadata (title, description)
• List of placeholders with default values
• Rendered markdown content
• Template file path

Edit existing template:

proplate edit my-template

Delete a template:

proplate delete my-template        # With confirmation prompt
proplate delete my-template --force # Skip confirmation

Manual way: Create/edit .md files directly in ~/.proplate/templates/ (auto-created on first use)

Shell Autocomplete

Enable tab completion for template names:

# For bash
proplate --install-completion bash

# For zsh
proplate --install-completion zsh

# For fish
proplate --install-completion fish

Then restart your shell or source your config file.

Template Format

Templates are Markdown files with optional YAML frontmatter and {{placeholder}} syntax.

Basic Template

# Hello {{name}}!

This is a simple template.

Template with Frontmatter

---
title: Bug Analysis
description: Structured template for bug investigation
---

# Bug Report: {{bug_id}}

## Description
{{description}}

## Steps to Reproduce
{{steps}}

## Expected vs Actual
**Expected:** {{expected}}
**Actual:** {{actual}}

Placeholder Guidelines

• Use {{placeholder}} syntax
• Default values: Use {{placeholder:default value}} to provide fallback values
• Escape colons: Use \: to include literal colons in names or defaults (e.g., {{url:https\://example.com}})
• Multi-line editor: Type - to open $EDITOR for multi-line input (works with or without defaults)
• Placeholders can be descriptive instructions (e.g., {{Your request here. Be specific!}})
• Support spaces, punctuation, and special characters
• Duplicate placeholders are prompted once and replaced everywhere
• Whitespace variations ({{name}}, {{ name }}) are normalized
• Leave input empty to:
  • Use default value (if defined)
  • Open multi-line editor ($EDITOR) (if no default)

Examples

Example 1: Code Review Template

~/.proplate/templates/code-review.md:

---
title: Code Review
description: Comprehensive code review template
---

# Code Review: {{file_path}}

## Context
{{context}}

## Changes Summary
{{changes}}

## Review Checklist
- [ ] Code quality and readability
- [ ] Error handling
- [ ] Security considerations
- [ ] Performance implications
- [ ] Test coverage

## Specific Feedback
{{feedback}}

Example 2: Feature Request (with Default Values)

~/.proplate/templates/feature-request.md:

---
title: Feature Request
description: Template for proposing new features with sensible defaults
---

# Feature Request: {{feature_name}}

## Priority
{{priority:Medium}}

## Requested By
{{requester:Product Team}}

## Description
{{description}}

## Expected Benefits
{{benefits}}

## Implementation Complexity
{{complexity:To be assessed}}

## Target Release
{{release:Next Quarter}}

Usage: When filling this template, press Enter on prompts with defaults to use them, or type to override.

Example 3: Refactoring Plan

~/.proplate/templates/refactor.md:

---
title: Refactoring Plan
description: Template for planning refactoring work
---

# Refactoring: {{component_name}}

## Current State
{{current_state}}

## Problems
{{problems}}

## Proposed Solution
{{solution}}

## Migration Strategy
{{migration}}

## Risks
{{risks}}

Tips

1. Default Values: Use {{placeholder:default}} to provide sensible defaults that users can accept with Enter
2. Multi-line Editor Access:
   • Type - to open $EDITOR for multi-line input (works even with defaults)
   • Or press Enter on placeholders without defaults
3. Escaping Colons: Use \: when you need literal colons in placeholder names or defaults:
   • URLs: {{api_url:https\://api.example.com}}
   • Times: {{meeting_time:14\:30\:00}}
   • Labels: {{Note\: Important:Remember this}}
4. Template Organization: Use descriptive filenames (they become the template name)
5. Metadata: Add title and description in frontmatter for better organization
6. Separators: Use --- freely in your template body (only the first block is frontmatter)

Development

# Clone repository
git clone <repo-url>
cd proplate

# Install with uv
uv sync

# Run locally
uv run proplate

# Run tests
uv run pytest

# Run specific test
uv run pytest tests/test_template.py -v

Requirements

• Python >= 3.12
• Dependencies:
  • typer - CLI framework
  • questionary - Interactive prompts
  • pyperclip - Clipboard operations
  • pyyaml - YAML parsing
  • rich - Terminal formatting

License

MIT

Contributing

Contributions welcome! Please ensure:

1. Tests pass: pytest
2. Code follows project style (modern Python 3.12+ syntax)
3. Add tests for new features