Prompt Vault (pv) – CLI Prompt Management Tool

Prompt Vault is a command-line tool built with Go, designed specifically for managing AI prompts. Whether you’re a developer, content creator, or anyone who regularly uses AI prompts, this tool helps you organize, share, and access your prompts efficiently—all from your terminal.

Key Features

Prompt Vault leverages GitHub Gist for managing, sharing, and importing prompts, while also providing a local cache to ensure you can work with your prompts even when offline. This combination of cloud storage and local access gives you the best of both worlds: seamless synchronization across devices and reliable offline functionality.

Installation

Building from Source

If you prefer to build the tool yourself from the source code, follow these simple steps:

git clone https://github.com/grigri/pv.git
cd pv
go build -o pv
# Or use the Makefile for easier building
make build

This will create an executable file named pv in your current directory, which you can then move to a location in your system’s PATH for easy access from any terminal window.

Quick Start Guide

Getting started with Prompt Vault is straightforward. Follow these steps to begin managing your prompts in minutes.

1. Authentication

The first time you use Prompt Vault, you’ll need to log in with your GitHub account. This requires creating a Personal Access Token with the gist permission. Here’s how to do it:

  1. Visit https://github.com/settings/tokens
  2. Click “Generate new token”
  3. Select the gist permission (this allows Prompt Vault to manage your Gists)
  4. Generate the token and copy it to your clipboard

Once you have your token, run this command in your terminal:

pv auth login

Follow the on-screen prompts to enter your token, and you’ll be authenticated.

2. Adding Prompts

Prompt Vault makes it easy to add new prompts in two different ways: from a local YAML file or directly from a public Gist URL.

Adding from a YAML File

First, create a YAML file with your prompt details. Here’s an example of what this file looks like:

# my-prompt.yaml
name: "Code Review Assistant"
author: "grigri"
description: "Helps with code reviews, identifying potential issues and improvement suggestions"
tags:
  - "code review"
  - "development tools"
version: "1.0"
---
You are a professional code review assistant. Please carefully examine the following code and provide detailed review feedback.

Please provide feedback in the following format:
- Code quality issues
- Potential bugs or security vulnerabilities
- Improvement suggestions

The YAML file has two parts: the metadata (above the --- line) and the actual prompt content (below the --- line). Once you’ve created your file, add it to Prompt Vault with:

pv add my-prompt.yaml

Adding from a Public Gist URL

If you find a useful prompt shared as a public GitHub Gist, you can add it directly using its URL:

pv add https://gist.github.com/username/abc123def456

This imports the prompt into your collection instantly.

3. Browsing Your Prompts

To see all the prompts you’ve added, use the list command:

# Use local cache (faster)
pv list

# Force fetch the latest data from GitHub
pv list --remote

The default pv list uses your local cache for quick results, while the --remote flag ensures you see the most up-to-date information from your GitHub Gists.

4. Retrieving Prompt Content

Once you have prompts in your collection, you can easily get their content and copy it to your clipboard with the get command:

# Interactively select a prompt and copy to clipboard
pv get

# Filter prompts by keyword and copy the selected one
pv get "code review"

# Get a prompt directly using its Gist URL
pv get https://gist.github.com/username/abc123

This makes it easy to quickly access the prompts you need, whether you remember their name, keywords, or exact URL.

5. Syncing Your Prompt Cache

Prompt Vault maintains a local cache of your prompts for offline use. To keep this cache up to date with your remote GitHub Gists, use the sync command:

# Sync all prompts to local cache
pv sync

# Show detailed sync progress
pv sync --verbose

The verbose mode shows you exactly what’s happening during synchronization, including which prompts are being downloaded and any errors that might occur.

6. Sharing Prompts

Want to share a private prompt with others? Prompt Vault lets you convert private GitHub Gists to public ones with the share command:

# Interactively select a private prompt to share
pv share

# Filter private prompts by keyword and share the selected one
pv share "my prompt"

# Share a specific private prompt using its URL
pv share https://gist.github.com/username/private_gist_id

Sharing makes it easy to collaborate with teammates or contribute useful prompts to the community.

7. Deleting Prompts

If you no longer need a prompt, you can delete it using the delete command (or its alias del). All delete operations include a confirmation step to prevent accidental removal:

# Interactively select a prompt to delete
pv delete

# Filter prompts by keyword and delete the selected one
pv delete "code review"

# Delete a specific prompt using its URL
pv delete https://gist.github.com/username/abc123

# Use the short alias
pv del

Command Reference

Here’s a complete list of all Prompt Vault commands, their aliases, descriptions, and examples to help you become a power user:

Command Alias Description Example
pv – Displays welcome information pv
pv list [--remote] – Lists all prompts pv list -r
pv add <file|url> – Adds a new prompt pv add prompt.yaml
pv get [keyword|url] – Retrieves a prompt and copies it to clipboard pv get "golang"
pv sync [--verbose] – Syncs remote data to local cache pv sync -v
pv share [keyword|url] – Shares a private prompt (makes it public) pv share "password"
pv delete [keyword|url] pv del Deletes a prompt pv delete "golang"
pv auth login – Logs in to your GitHub account pv auth login
pv auth logout – Logs out of your current account pv auth logout
pv auth status – Shows your current authentication status pv auth status

Feature Details

Let’s take a closer look at how each core feature works to help you manage your prompts effectively.

Adding Prompts

Prompt Vault offers two flexible ways to add new prompts to your collection:

  1. From a YAML file: Create a local YAML file with your prompt’s metadata and content (see the “Prompt File Format” section below for details) and import it using pv add [filename]. This is great for creating new prompts from scratch.

  2. From a public Gist URL: Import prompts shared by others by providing their public Gist URL. This lets you quickly add community-created prompts to your collection without retyping them.

Retrieving Prompts

The get command is designed to make accessing your prompts quick and intuitive, with three different modes:

  1. Interactive retrieval: When you run pv get without any arguments, you’ll see a list of all your prompts. Simply select the one you want, and its content will be copied to your clipboard automatically.

  2. Keyword filtering: If you remember a word or phrase from a prompt’s name, description, or tags, use pv get "keyword" to filter the list and find the prompt you need faster.

  3. Direct URL retrieval: If you have the exact Gist URL of a prompt, use pv get [url] to immediately retrieve its content, skipping the selection process.

All retrieved prompts are automatically copied to your clipboard, so you can paste them directly into your AI tool of choice.

Syncing Your Collection

The synchronization feature ensures your local cache stays up to date with your remote GitHub Gists. Here’s how the sync process works:

  • First, it fetches the latest list of your remote prompts (from GitHub Gists)
  • Then, it downloads the content of each prompt to your local cache, one by one
  • During the process, it shows a progress indicator (e.g., “Downloading 3/10”)
  • If a prompt fails to download, it skips it and continues with the others
  • When finished, it shows a summary of how many prompts were successfully synced and how many failed

This robust syncing ensures you always have access to your latest prompts, even if your internet connection drops later.

Sharing Prompts

Sharing prompts is simple with Prompt Vault, which converts your private Gists to public ones. This feature offers three sharing modes:

  1. Interactive sharing: Run pv share to see a list of your private prompts. Select the one you want to share, and it will be made public.

  2. Keyword-filtered sharing: Use pv share "keyword" to filter your private prompts by keyword, then select the one to share from the filtered list.

  3. Direct URL sharing: Share a specific private prompt by providing its URL with pv share [url].

Once shared, anyone with the Gist URL can view and import your prompt using pv add [url].

Deleting Prompts

To keep your collection organized, Prompt Vault makes it easy to remove unwanted prompts. All delete operations include a confirmation step to prevent mistakes, and there are three deletion modes:

  1. Interactive deletion: Run pv delete to see a list of all your prompts. Select the one to delete and confirm your choice.

  2. Keyword-filtered deletion: Use pv delete "keyword" to filter your prompts, then select and confirm the one to remove.

  3. Direct URL deletion: Delete a specific prompt by providing its URL with pv delete [url].

Remember that deleting a prompt removes it both from your local cache and your GitHub Gists, so be sure you no longer need it before confirming.

Prompt File Format

Prompt Vault uses YAML files to store prompts, with a simple structure that includes both metadata and the actual prompt content. Here’s a breakdown of the format:

name: "Prompt Name"           # Required: The name of your prompt
author: "Author Name"         # Required: Who created the prompt
description: "Brief description"  # Optional: Explains what the prompt is used for
tags:                         # Optional: Categories to help organize your prompts
  - "tag1"
  - "tag2"
version: "1.0"                # Optional: Version number for tracking updates
---
This is the full content of your prompt.
It can include multiple lines of text.
You can add any formatting or instructions needed for your AI tool.

The file is divided into two parts by the --- line:

  • Metadata (above ---): Contains information about the prompt, like its name, author, and tags. This helps with organization and searching.
  • Content (below ---): The actual text of the prompt that you’ll send to your AI tool.

This structure makes it easy to manage and organize your prompts while keeping all relevant information in one place.

Configuration

Prompt Vault stores its configuration in a file located at ~/.config/pv/config.yaml. This file contains:

  • Your GitHub Personal Access Token (stored securely in encrypted form)
  • Your user preferences (like default behaviors for certain commands)
  • A local index cache that helps speed up listing and searching for prompts

You don’t need to edit this file manually—Prompt Vault manages it automatically. However, knowing its location can be helpful for troubleshooting (see the “Troubleshooting” section below).

Cache Mechanism

One of Prompt Vault’s most useful features is its local caching system, which provides several benefits:

  • Fast access: The pv list command uses the local cache by default, so you can see your prompts instantly without waiting for a network request.
  • Offline use: Once prompts are cached, you can access them even when you don’t have an internet connection.
  • Network optimization: By using cached data, Prompt Vault reduces the number of calls to the GitHub API, helping you avoid hitting rate limits.
  • Manual control: You decide when to update your cache with pv sync, and you can always check the latest remote data with pv list --remote.

The cache is automatically maintained, but you can force a refresh anytime with the sync command.

Troubleshooting

If you run into issues while using Prompt Vault, here are some common problems and how to solve them.

Authentication Issues

If you’re having trouble with login or permissions, try these steps:

# Check your current authentication status
pv auth status

# If you're having problems, log out and log back in
pv auth logout
pv auth login

Make sure you’re using a valid GitHub Personal Access Token with the gist permission. If your token has expired or been revoked, you’ll need to generate a new one and log in again.

Network Connection Problems

Prompt Vault needs to connect to GitHub’s API to sync and manage Gists. If you’re having network issues:

Check if you can access the GitHub API manually:

curl -I https://api.github.com

If this command fails, your network might be blocking access to GitHub. Check your firewall settings or try a different network.

Permission Issues

If you get errors about insufficient permissions, ensure your GitHub token has the gist scope enabled. Tokens without this permission can’t create or manage Gists, which is essential for Prompt Vault to work.

To fix this, generate a new token with the gist permission (following the steps in the “Authentication” section) and log in with the new token.

Cache Issues

If your local cache seems out of sync with your remote prompts:

# Force a full sync with remote data
pv sync

# Or view the latest remote data directly
pv list --remote

This will either update your cache or show you the most recent remote information, helping you resolve any discrepancies.

Development

If you’re interested in contributing to Prompt Vault or modifying it for your needs, here’s what you need to know.

Environment Requirements

  • Go 1.24.5 or newer
  • CGO support (required for race detection in tests)

Building the Project

You can build Prompt Vault using either Go commands directly or the included Makefile (recommended for simplicity):

# Using Go commands
go build -o pv

# Using the Makefile
make build

# Building release versions for multiple platforms
make release

The make release command builds executable files for different operating systems and architectures, making it easy to distribute.

Running Tests

Prompt Vault includes a comprehensive test suite to ensure reliability. Here are the commands to run tests:

# Run all tests
make test

# Quick test (without race detection)
make test-quick

# Test specific features
make test-delete
make test-tui
make test-integration

# Full test suite (generates a combined coverage report)
make test-all

These tests check everything from individual functions to full user workflows, helping ensure the tool works as expected.

Generating Dependency Injection Code

Prompt Vault uses Wire for dependency injection. To generate the necessary code:

go generate ./internal/di
# Or using the Makefile
make generate

This command should be run whenever you make changes to the dependency injection setup.

Development Tools

The project includes several tools to help with development:

# Install development dependencies
make dev-deps

# Format code to meet style standards
make fmt

# Check code for style and syntax issues
make lint

# Run security scans
make security

# Run performance benchmarks
make bench

These tools help maintain code quality and ensure the project follows best practices.

Project Initialization

If you’re setting up the project for the first time, run:

make init

This command sets up any necessary directories and dependencies to get you started with development.

Tech Stack

Prompt Vault is built using modern, reliable technologies:

  • Go 1.24.5: The primary programming language, chosen for its performance, simplicity, and excellent support for command-line tools.
  • Cobra: A popular framework for building CLI applications in Go, providing features like command parsing and help text generation.
  • Bubbletea: A library for building terminal user interfaces (TUIs), used for interactive features like prompt selection.
  • Lipgloss: Works with Bubbletea to style and layout terminal interfaces, making them more user-friendly.
  • Wire: A dependency injection tool that helps manage the project’s internal dependencies cleanly.
  • GitHub API: Used to interact with Gists for cloud storage of prompts.
  • OAuth2: The authentication protocol used to securely log in with GitHub.

Testing Dependencies

  • go-expect: Helps test terminal interactions, ensuring commands behave as expected when users input text.
  • vt10x: Provides a virtual terminal for testing, making it possible to simulate user interactions in tests.

Architecture

Prompt Vault is organized into a clear, layered architecture that makes the codebase easy to understand and modify:

  • Command layer (cmd/): Contains the implementation of all CLI commands (like add, list, and sync). This is where user input is processed and responses are generated.

  • Service layer (internal/service/): Handles the core business logic, coordinating between different parts of the application to fulfill user requests.

  • Infrastructure layer (internal/infra/): Manages data storage, including interactions with GitHub Gists and the local cache.

  • Domain layer (internal/model/): Defines the core data models, like what a “prompt” is and what information it contains.

  • TUI layer (internal/tui/): Contains components for the terminal user interface, like interactive lists and confirmation prompts.

  • Authentication layer (internal/auth/): Handles GitHub OAuth2 integration, managing login, logout, and token storage securely.

This separation of concerns makes it easy to modify one part of the application without affecting others, and helps keep the codebase maintainable as it grows.

Whether you’re a casual user looking to organize your AI prompts or a developer interested in contributing to the project, Prompt Vault offers a flexible, reliable solution for managing your AI prompts—all from the convenience of your terminal.