Create, Lock & Version

Fundamental workflow of creating a prompt, securing it, and then iterating on it safely.

This is the core loop of using Prompt Lockbox. This guide will walk you through the entire lifecycle of a single prompt: from its initial creation as a draft, to securing it, and finally to creating a new version for safe iteration.

Steps

1. Create the Prompt

   We’ll start by creating a new prompt for a “Joke Generator”. The create command builds a new, compliant .yml file for you.

   CLI

   # Interactive prompt creation
   plb create
   

   Python

   from prompt_lockbox.api import Project
   
   project = Project()
   # create_prompt() builds the file and returns a Prompt object
   joke_prompt = project.create_prompt(
       name="joke-generator",
       description="Creates a dad joke on a given topic.",
       tags=["humor", "dad-joke"]
   )
   print(f"Created: {joke_prompt.path}")
   
2. Edit and Finalize

   Now, open the newly created prompts/joke-generator.v1.0.0.yml file and add your template content. This is the only manual step in the process.

   template: |
     Tell me a dad joke about ${topic}.
   
3. Lock for Production

   Once you’re happy with v1.0.0, lock it. This marks the prompt as “production-ready,” records its secure hash, and protects it from accidental changes.

   CLI

   plb lock joke-generator
   

   Python

   from prompt_lockbox.api import Project
   
   project = Project()
   prompt_to_lock = project.get_prompt("joke-generator")
   
   prompt_to_lock.lock()
   print(f"Locked: {prompt_to_lock.name}")
   

   You can verify the prompt’s new status by running plb status. You’ll see joke-generator is now marked as ✔ Locked.

4. Create a New Version

   Let’s say you want to improve the joke prompt. Instead of editing the locked file, you create a new version. This preserves the original v1.0.0 and gives you a safe, unlocked copy to work on.

   CLI

   plb version joke-generator --minor
   

   Python

   from prompt_lockbox.api import Project
   
   project = Project()
   source_prompt = project.get_prompt("joke-generator")
   if source_prompt:
       new_version_prompt = source_prompt.new_version(
           bump_type="minor"
       )
       print(f"Created new version: {new_version_prompt.path}")
   

   This creates a new file, prompts/joke-generator.v1.1.0.yml. You are now free to edit this new version without affecting the locked original.

Next Steps

You have now learned how to create, secure, and safely iterate on the prompt. This workflow is fundamental to maintaining a reliable and organized prompt library.

List, Tree and Search

Explore list rendering, tree, and search techniques.