So we've been using PromptLayer for a few months, mostly for the audit logging. The versioning feature for prompts, though, felt like it was just sitting there—powerful, but a bit raw if you're managing more than a handful of templates.
We ended up building a lightweight internal library on top of it. The core idea: treat versioned prompts like npm packages with semantic versioning, and use a CLI to manage the lifecycle.
Here's the rough architecture:
* A central registry (just a JSON file) maps `template_name` to a specific PromptLayer `prompt_id` and `version`.
* A CLI tool lets us `publish` new versions (which creates a new version in PromptLayer and updates the registry), `rollback`, and `deploy` (pulls the correct prompt into our app config).
* We enforce a simple schema for template variables to avoid the "guessing game" with placeholders.
A typical workflow looks like this:
```bash
# Update the template locally, then...
./prompt-cli publish feature-auth-error-message --minor
# This triggers the PromptLayer API call, tags the version, updates our registry.
```
The CLI wrapper handles the PromptLayer API calls. The key part is locking down the version in our application runtime:
```javascript
import { getPrompt } from './our-prompt-layer-client';
// This fetches the EXACT version from our registry, not just 'latest'
const promptTemplate = await getPrompt('feature-auth-error-message');
```
**What we gained:**
* **Reproducibility:** No more "why did the output change?" mysteries. Our staging environment uses locked versions, production uses a stable major.
* **Rollbacks:** A true one-command operation to revert a bad prompt update across all services.
* **Discovery:** New team members can browse the registry to see what prompts exist and their intended variables, instead of digging through Slack history.
**The friction points:**
* PromptLayer's API is solid, but their UI isn't great for comparing diff between minor versions. We had to build that diff view ourselves.
* The versioning is per-prompt, not per-project. We had to add our own tagging system (`project:onboarding`) to avoid a monolithic list.
Overall, it turned PromptLayer from a simple audit log into a proper dev dependency. The versioning system is the backbone; you just need to add a bit of process around it.
YMMV