Quick Start Guide

📦 Already have editor prompts and rules? Jump to Working with Existing Projects to learn how to import and consolidate them with PrompTrek.

Prerequisites

Installation

Install PrompTrek using pip:

pip install promptrek

Verify the installation:

promptrek --version

Interactive CLI Wizard (New!)

New in v0.4.0: PrompTrek now includes an interactive CLI wizard that guides you through all common workflows!

Launch Interactive Mode

Simply run promptrek without any arguments:

promptrek

You’ll see a beautiful ASCII banner and a menu-driven interface:

 ____                       _____         _
|  _ \ _ __ ___  _ __ ___  |_   _| __ ___| | __
| |_) | '__/ _ \| '_ ` _ \   | || '__/ _ \ |/ /
|  __/| | | (_) | | | | | |  | || | |  __/   <
|_|   |_|  \___/|_| |_| |_|  |_||_|  \___|_|\_\

Universal AI Editor Prompt Management (v0.4.0)

? What would you like to do?
  ❯ 🚀 Initialize new project
    ⚙️  Generate editor configurations
    🔌 Configure plugins (MCP servers, commands, agents)
    🔄 Migrate schema version
    🔍 Validate configuration
    📤 Sync from editor files
    ❓ Help & Documentation
    👋 Exit

The wizard will guide you through:

Benefits:

Traditional CLI Mode

If you prefer traditional commands or are in a CI/CD environment, all commands continue to work:

# Initialize project (traditional way)
promptrek init --setup-hooks --output project.promptrek.yaml

# Generate configurations
promptrek generate --editor cursor

# Force interactive mode
promptrek --interactive

Your First Universal Prompt

1. Initialize a New Project

Create a new universal prompt file using one of our templates:

# Basic initialization with pre-commit hooks (creates schema v3.1 format by default)
promptrek init --setup-hooks --output my-project.promptrek.yaml

# Use a specific template with hooks (schema v3.1 format)
promptrek init --template react --setup-hooks --output my-react-app.promptrek.yaml
promptrek init --template api --setup-hooks --output my-api.promptrek.yaml

# Create schema v1 format (legacy)
promptrek init --v1 --output legacy.promptrek.yaml

# Migrate existing schema v1 or v2.x file to v3.1
promptrek migrate old.promptrek.yaml -o new.promptrek.yaml

💡 Tip: The --setup-hooks flag automatically configures pre-commit hooks to validate your .promptrek.yaml files and prevent accidental commits of generated files. This ensures your team maintains clean version control!

🔐 .gitignore Management: When you run promptrek init, it automatically:

This prevents generated editor files from being committed to version control. You can disable this with ignore_editor_files: false in your config.

Available templates:

Advanced Examples: PrompTrek includes 8 production-ready examples for complex projects:

See examples on GitHub

2. Customize Your Prompt

Edit the generated .promptrek.yaml file to match your project needs.

Using Schema v3.1 Format (Latest Stable - Default):

Note on Versioning: Schema versions (v1.x, v2.x, v3.x) define the configuration file format specified in the schema_version field. These are independent of the PrompTrek application version.

schema_version: "3.1.0"

metadata:
  title: "My Project Assistant"
  description: "AI assistant for my project"
  version: "1.0.0"
  author: "Your Name <your.email@example.com>"
  tags: [web, python, react]

content: |
  # {{{ PROJECT_NAME }}} Assistant

  ## Project Details
  **Project Type:** web_application
  **Technologies:** Python, JavaScript, React

  ## Development Guidelines

  ### General Principles
  - Write clean, readable code for {{{ PROJECT_NAME }}}
  - Follow existing patterns
  - Add comprehensive documentation
  - Contact {{{ AUTHOR_EMAIL }}} for questions

  ### Code Style
  - Use meaningful variable names
  - Add appropriate comments for complex logic
  - Follow language-specific best practices

  ## Code Examples

  ### Function Example
  ```python
  def hello_world():
      """Example function with docstring."""
      return "Hello, World!"
  `` `

variables:
  PROJECT_NAME: "my-project"
  AUTHOR_EMAIL: "your.email@example.com"

Benefits of Schema v3.1:

3. Validate Your Configuration

Before generating prompts, validate your configuration:

promptrek validate my-project.promptrek.yaml

Use --strict to treat warnings as errors:

promptrek validate my-project.promptrek.yaml --strict

💡 Editor Integration: Enable schema validation in your editor for instant feedback while editing .promptrek.yaml files. Add this comment at the top of your file:

# yaml-language-server: $schema=https://promptrek.ai/schema/v3.1.0.json
schema_version: 3.1.0
# ... rest of your configuration

This provides autocompletion, inline documentation, and validation in editors like VS Code, IntelliJ IDEA, and others that support YAML language servers. See the Schema Documentation for more details.

4. Configure .gitignore (Optional)

If you have existing editor files already committed to git, you can clean them up:

# Add patterns to .gitignore and remove committed files from git
promptrek config-ignores --remove-cached

# Preview what would be done
promptrek config-ignores --dry-run

# Use specific config file
promptrek config-ignores --config my-project.promptrek.yaml

What this command does:

You can control this behavior in your .promptrek.yaml:

# Set to false to disable automatic .gitignore management
ignore_editor_files: false

5. (Optional) Use Dynamic Variables

PrompTrek supports powerful dynamic variables to make your prompts adaptive:

Built-in Variables (automatically available, all can be overridden):

💡 Tip: You can override any built-in variable by defining it in your variables file or via CLI.

Command-based Variables (execute shell commands):

# .promptrek/variables.promptrek.yaml (automatically gitignored via .promptrek/ directory)
# Static user variables
AUTHOR_NAME: "Your Name"
AUTHOR_EMAIL: "your.email@example.com"

# Override built-in PROJECT_NAME (optional)
PROJECT_NAME: "MyCustomProjectName"

# Dynamic command-based variables
GIT_BRANCH:
  type: command
  value: git rev-parse --abbrev-ref HEAD
  cache: false

GIT_COMMIT:
  type: command
  value: git rev-parse --short HEAD
  cache: true

CURRENT_USER:
  type: command
  value: whoami
  cache: true

Add allow_commands: true to your .promptrek.yaml to enable command-based variables.

CLI Overrides (highest priority):

# Override variables for specific generations
promptrek generate -e claude -V ENVIRONMENT=staging
promptrek generate --all -V PROJECT_NAME=MyApp -V DEBUG=true

Variable Priority Order:

  1. CLI flags (-V) - highest priority
  2. File-based (.promptrek/variables.promptrek.yaml)
  3. Inline (variables: in your .promptrek.yaml)
  4. Built-in (CURRENT_*, PROJECT_*, GIT_*) - lowest priority

Note: The .promptrek/ directory is automatically added to .gitignore when you run promptrek init, so all files in this directory (including variables.promptrek.yaml) will not be committed to version control.

See Variable Substitution for complete documentation.

6. Preview Generated Output (Optional)

Preview what will be generated without creating files:

# Preview for a specific editor
promptrek preview my-project.promptrek.yaml --editor copilot

# Preview with variable overrides
promptrek preview my-project.promptrek.yaml --editor cursor \
  -V PROJECT_NAME="MyApp" \
  -V AUTHOR="Team Lead"

The preview shows:

7. Generate Editor-Specific Prompts

Now generate prompts for your preferred editors:

# Generate for a specific editor
promptrek generate --editor copilot --input my-project.promptrek.yaml

# Generate for all configured editors
promptrek generate --all --input my-project.promptrek.yaml

# Generate with custom output directory
promptrek generate --all --input my-project.promptrek.yaml --output ./ai-config

Generated Files Overview

PrompTrek generates sophisticated configuration files for each editor:

GitHub Copilot

Cursor

Continue

Kiro

Cline

Claude Code

Windsurf

Amazon Q

JetBrains AI

Example Workflow

Here’s a typical workflow using PrompTrek:

1. Project Setup

# Create a new React project prompt
promptrek init --template react --output react-app.promptrek.yaml

# Customize for your specific needs
# Edit react-app.promptrek.yaml...

# Validate the configuration
promptrek validate react-app.promptrek.yaml --strict

2. Generate Prompts

# Generate for GitHub Copilot
promptrek generate --editor copilot --input react-app.promptrek.yaml

# Team members can generate for their preferred editors
promptrek generate --editor cursor --input react-app.promptrek.yaml
promptrek generate --editor continue --input react-app.promptrek.yaml

3. Use in Your Editor

Working with Existing Projects

Already have editor prompts and rules? PrompTrek makes it easy to consolidate them into a universal format and maintain them across editors.

Scenario 1: Import Existing Editor Configurations

If you already have .github/copilot-instructions.md, .cursor/rules/*.mdc, .claude/CLAUDE.md, or other editor files, you can sync them into PrompTrek format:

# Sync from GitHub Copilot
promptrek sync --editor copilot # By default this creates project.promptrek.yaml

# Sync from Cursor
promptrek sync --editor cursor --output project.promptrek.yaml # Specifying output allows you to save to a custom file name

# Sync from Claude Code
promptrek sync --editor claude 

# Sync from Continue
promptrek sync --editor continue 

# Preview what would be synced (dry run)
promptrek sync --editor copilot --dry-run

Supported editors for sync: GitHub Copilot, Cursor, Continue, Windsurf, Kiro, Cline, Claude Code, Amazon Q, JetBrains AI

This creates a project.promptrek.yaml file from your existing editor configuration. You can then:

  1. Edit this file to refine your prompts
  2. Generate for other editors: promptrek generate --all
  3. Keep everything in sync going forward

Scenario 2: Migrate and Clean Up

If you want to migrate from editor-specific files to PrompTrek as your single source of truth:

# Step 1: Sync your existing configuration
promptrek sync --editor copilot --source-dir . --output project.promptrek.yaml

# Step 2: Validate the imported configuration
promptrek validate project.promptrek.yaml

# Step 3: Generate for all editors (optional - if your team uses multiple editors)
promptrek generate --all --input project.promptrek.yaml

# Step 4: Remove old editor files from git and add to .gitignore
promptrek config-ignores --remove-cached

# Step 5: Commit the PrompTrek configuration
git add project.promptrek.yaml .gitignore
git commit -m "chore: migrate to PrompTrek universal prompt format"

Benefits of this approach:

Scenario 3: Add PrompTrek to Project with Committed Editor Files

If your project already has editor files committed to git, here’s the cleanest migration path:

# Step 1: Initialize PrompTrek configuration
promptrek init --setup-hooks --output project.promptrek.yaml

# Step 2: Import your existing editor configuration
promptrek sync --editor copilot --source-dir . --output imported.promptrek.yaml

# Step 3: Merge the imported content into your project.promptrek.yaml
# (Edit project.promptrek.yaml and copy the content from imported.promptrek.yaml)

# Step 4: Clean up committed editor files and update .gitignore
promptrek config-ignores --remove-cached

# Step 5: Regenerate files from your PrompTrek source
promptrek generate --all --input project.promptrek.yaml

# Step 6: Commit the new setup
git add project.promptrek.yaml .gitignore .pre-commit-config.yaml
git commit -m "chore: migrate to PrompTrek with pre-commit hooks"

What happens:

Scenario 4: Keep Existing Editor Files (No Migration)

If you want to use PrompTrek alongside your existing editor files:

# Step 1: Initialize with --no-gitignore to preserve existing files
promptrek init --output project.promptrek.yaml

# Step 2: Configure to not ignore editor files
# Edit project.promptrek.yaml and add:
# ignore_editor_files: false

# Step 3: Generate without conflicts
promptrek generate --all --input project.promptrek.yaml --output ./promptrek-generated

This keeps your existing workflow intact while experimenting with PrompTrek.

PrompTrek includes pre-commit hooks to ensure code quality and prevent accidental commits of generated files.

Setup Options

Option 1: During Initialization (Easiest)

promptrek init --setup-hooks --output project.promptrek.yaml
# ✅ Creates .promptrek.yaml
# ✅ Configures .pre-commit-config.yaml
# ✅ Activates git hooks automatically

Option 2: For Existing Projects

pip install pre-commit
promptrek install-hooks --activate

Option 3: Manual Setup

promptrek install-hooks        # Configure only
pre-commit install            # Activate manually

What the Hooks Do

  1. Validate PrompTrek files - Automatically validates .promptrek.yaml files before commit
  2. Prevent generated files - Blocks accidental commits of AI editor config files (.cursor/, .claude/, etc.)

See the Pre-commit Integration Guide for detailed documentation.

Common Commands Reference

Initialization

promptrek init --output <filename>                          # Basic init
promptrek init --template <template> --output <file>        # From template
promptrek init --setup-hooks --output <file>                # With pre-commit hooks

Pre-commit Hooks

promptrek install-hooks                    # Configure hooks
promptrek install-hooks --activate         # Configure and activate
promptrek check-generated <files>          # Check if files are generated

Validation

promptrek validate <file>           # Basic validation
promptrek validate <file> --strict  # Strict validation

Generation

promptrek generate --editor <editor> --input <file>     # Single editor
promptrek generate --all --input <file>                 # All editors
promptrek generate --all --input <file> --output <dir>  # Custom output

Synchronization

promptrek sync --editor copilot --source-dir . --output <file>  # Sync editor changes back
promptrek sync --editor continue --source-dir . --dry-run       # Preview sync changes

Information

promptrek list-editors              # Show supported editors
promptrek --help                    # General help
promptrek <command> --help          # Command-specific help

Deprecated Commands

# ⚠️ DEPRECATED: Use 'promptrek generate --all' instead
# promptrek agents                               # Legacy agent generation (schema v3.1.0+)

Note: The agents command is deprecated as of schema v3.1.0 and will be removed in a future version. All functionality is available through promptrek generate --all.

Troubleshooting

Common Issues

  1. Import errors: Make sure you installed with pip install promptrek
  2. Command not found: Check that promptrek is in your PATH
  3. Validation errors: Use promptrek validate --help for validation options

Getting Help

Next Steps

Ready to dive deeper? Check out our comprehensive User Guide!