Usage Guide¶

This guide focuses on how to use PromptKeep in everyday scenarios. For detailed technical information about commands and parameters, see the Reference page.

Getting Started¶

Setting Up Your Vault¶

Before you can use PromptKeep, you need to create a prompt vault to store your prompts:

promptkeep init

This creates a vault in your home directory at ~/PromptVault. You'll see a success message with next steps:

───────────────── Success ──────────────────
✅ Prompt vault created successfully at:
/Users/youruser/PromptVault

Next steps:
1. Add your prompts to the 'Prompts' directory
2. Use 'promptkeep add' to create new prompts
...
─────────────────────────────────────────────

If you want to keep your vault somewhere else, specify the path:

promptkeep init ~/Documents/MyPrompts

Once you do this, PromptKeep will remember that this is your stored prompts directory; you don't need to create another vault unless you want to override an existing vault or store certain prompts in separate vaults.

Creating Your First Prompt¶

Now that you have a vault, let's add your first prompt:

Run the add command:
```
promptkeep add
```

You'll be asked to add a title, description, and tags (the latter two are optional):

Enter a title for your prompt: Code Review Prompt
Enter a description (optional): Detailed code review analysis for pull requests
Enter tags separated by commas (optional): coding, code review, debugging

Your default text editor will open. Add the prompt content below the YAML front matter:

---
title: "Code Review Prompt"
description: "Detailed code review analysis for pull requests"
tags: ["coding", "code review", "debugging"]
---

# Code Review Analysis

Please review the following code and provide a comprehensive analysis:

```[LANGUAGE]
[PASTE CODE HERE]

Focus on these aspects:
1. Code quality and best practices
2. Potential bugs and edge cases
3. Performance considerations
4. Security vulnerabilities
5. Readability and maintainability

For each issue found:
- Explain why it's problematic
- Provide a suggested improvement
- Include code examples where appropriate

End with a summary of the main strengths and areas for improvement.

Save and close the editor. Your prompt is now saved in your vault!

Working with Your Prompts¶

Finding and Using Prompts¶

When you need to use a prompt:

Run the pick command:
```
promptkeep pick
```
A fuzzy finder will appear showing all your prompts.
Start typing to search for a specific prompt. For example, type "email" to find your email templates.
Use arrow keys to navigate and press Enter to select a prompt.
The prompt is now copied to your clipboard! Paste it anywhere you need it.

Organizing with Tags¶

Tags make it easier to organize and find your prompts:

When creating a prompt, add tags:

promptkeep add --title "Meeting Notes" --tag meeting --tag notes

When searching for prompts, filter by tag:
```
promptkeep pick --tag meeting
```

This will only show prompts with the "meeting" tag.

Example Workflows¶

Creating AI Coding Assistants¶

Create specialized coding prompts for different scenarios:

promptkeep add --title "Debugging Helper" --tag coding --tag debugging
promptkeep add --title "Refactoring Guide" --tag coding --tag refactoring

When you encounter a coding issue, find the right prompt:
```
promptkeep pick --tag coding
```
Fill in the details with your specific code and context, then send to your preferred AI assistant.

Building a Knowledge Management System¶

Store prompts designed to help organize and retrieve information:

promptkeep add --title "Concept Explainer" --tag learning --tag explanation
promptkeep add --title "Research Summarizer" --tag research --tag summary

When studying a new topic or processing research papers:
```
promptkeep pick --tag research
```
Combine with your source material and send to your preferred AI assistant to generate organized notes or summaries.

Creating Persona-Based AI Interactions¶

Define different AI personas to offer you different types of feedback:

promptkeep add --title "Technical Expert Persona" --tag persona --tag technical
promptkeep add --title "Writing Coach Persona" --tag persona --tag writing

When you need specialized feedback, select the appropriate persona:
```
promptkeep pick --tag persona
```
Start your AI conversation with the persona prompt, then continue with your specific questions or content.

Maintaining Your Prompt Library¶

Organizing Your Prompts¶

Use tags consistently to create an organized system. Consider a tagging structure like:

Content type: email, code, documentation
Audience: client, team, public
Project: projectA, projectB
Purpose: template, reference, guide

Editing Prompts¶

To edit an existing prompt, use the edit command:

promptkeep edit

This will open a fuzzy finder to select the prompt you want to edit. You can filter prompts by tags using the --tag or -t option:

promptkeep edit --tag python --tag ai  # Edit prompts tagged with both "python" and "ai"
promptkeep edit -t coding             # Edit prompts tagged with "coding"

Once you select a prompt, it will open in your default text editor. Make your changes and save the file to update the prompt.

Troubleshooting¶

"Vault not found"¶

If you see this error, your prompt vault can't be located. Try:

Specifying the vault path explicitly:

promptkeep pick --vault ~/path/to/your/vault

Or setting the environment variable:

export PROMPTKEEP_VAULT=~/path/to/your/vault
promptkeep pick

"Editor exited with non-zero code"¶

This means there was a problem with your text editor:

Check that your EDITOR environment variable is set correctly:
```
echo $EDITOR
```

If not, try setting it explicitly:

export EDITOR=nano  # or vim, code, etc.

Tips and Tricks¶

Template Placeholders: Use consistent placeholder text like [Client Name] in your prompts to quickly identify what needs to be replaced.
Keyboard Navigation: In the fuzzy finder, use Ctrl+P/Ctrl+N (or up/down arrows) to navigate without using the mouse.
Quick Filtering: Add a dedicated tag like favorite or frequent to prompts you use often, then use promptkeep pick --tag favorite for quick access.
Multi-tag Filtering: Combine tags to narrow down your search: promptkeep pick --tag email --tag client.