Devlog — Part 4
PromptLedger v0.4 is mostly about making prompt versioning easier to use repeatedly: faster logging, clearer organization, and small release signals for versions worth remembering.
In the earlier parts of this series, PromptLedger started as a deliberately small local-first prompt version control tool. Then it gained labels, status semantics, better diffs, review workflows, semantic summaries, warnings, and Markdown export.
Those additions made the history more useful after prompts had already been logged.
Some of the direction for v0.4 also came from feedback and from watching where the workflow still felt a bit too manual. So before going into the details: thank you to everyone who tried the earlier versions, shared thoughts, pointed out rough edges, or simply asked practical questions about how the tool should behave during real prompt iteration.
v0.4 focuses more on the moment before review: the actual day-to-day act of adding, organizing, and revisiting prompt versions.
Because in practice, a prompt version control tool only works if logging a prompt is cheap enough that you actually keep doing it.
Why this part was needed
PromptLedger has always been intentionally limited in scope.
It is SQLite-backed. It is terminal-first. It does not need a hosted backend. It does not try to execute prompts for you. It does not try to become an evaluation platform.
The core job is still simple:
- store prompt versions
- compare them
- review changes
- organize prompt history
- make the history inspectable later
But once I started using it more like a real prompt library, a small problem became obvious.
Adding a prompt version was technically easy, but repetitive.
During actual prompt iteration, the prompt text changes often, while the surrounding metadata usually stays the same. The same author. The same environment. The same tags. The same library grouping. The same role.
Having to retype that metadata every time creates friction.
And friction matters. If logging is annoying, the history becomes incomplete. If the history is incomplete, review becomes less useful. And if review becomes less useful, the tool stops doing its main job.
So v0.4 is not a big architectural release.
It is a workflow release.
It makes repeated prompt logging faster, adds better organization primitives, and introduces lightweight markers for important versions.
Quick add: less typing during real iteration
The main usability change in v0.4 is the new add --quick workflow.
A normal add can still be explicit:
promptledger add --id onboarding --text "..." --collection support --role system
That is useful when creating a new prompt or when metadata should be stated clearly.
But once a prompt already exists, most iterations do not need all metadata to be typed again. With --quick, PromptLedger can reuse safe metadata defaults from the latest version of the same prompt id.
promptledger add --id onboarding --text "..." --quick
If the latest onboarding version already had metadata like author, tags, env, collection, and role, those values can be reused unless explicitly overridden.
That means the common workflow becomes much smaller:
- edit the prompt
- add the new version
- keep moving
This is not a flashy feature, but it changes the feel of the tool.
Prompt logging becomes closer to a habit than a chore.
That matters because PromptLedger is not useful because one perfect prompt was saved once. It is useful because a sequence of changes becomes reviewable later.
Quick add is there to protect that sequence.
Collection and role are now first-class metadata
v0.4 also adds two first-class metadata fields on prompt versions:
collectionrole
The reason is simple: once a prompt library grows, ids and tags are not always enough.
A collection gives prompts a lightweight grouping. It can represent a product area, a project, a use case, a customer support flow, an internal tool, or just a personal folder-like grouping.
For example:
promptledger add --id onboarding --text "..." --collection support --role system
This makes it easier to ask questions like:
- Which prompts belong to the support collection?
- Which prompts are part of an onboarding workflow?
- Which versions were written for a specific environment or use case?
The second field, role, is about what kind of prompt artifact this version represents.
Built-in roles are:
systemusertemplatemodelfileeval
This matters because prompt libraries usually contain different kinds of artifacts.
A system instruction is not the same thing as a reusable template. An evaluation prompt is not the same thing as a user-facing message. A model file prompt is not the same thing as an onboarding assistant instruction.
Before v0.4, these differences could be represented with tags, but tags are free-form and tend to become messy over time.
Making role first-class gives PromptLedger a small amount of structure without turning it into a large framework.
That is the balance I wanted here: enough organization to be useful, but not so much that the tool starts dictating how every prompt library must be designed.
Markers: small signals for important versions
v0.4 introduces a new marker system for prompt versions.
The core commands are:
promptledger marker set --id onboarding --version 8 --name stable
promptledger marker remove --id onboarding --version 8 --name stable
promptledger marker list --id onboarding
promptledger marker show --id onboarding --version 8
There are also convenience commands for the built-in markers:
promptledger stable --id onboarding
promptledger milestone --id onboarding
The built-in markers are:
stablemilestone
Markers are intentionally lighter than labels.
That distinction is important.
Labels in PromptLedger are useful when you want release-like semantics or named pointers. They can represent states such as a current production prompt, a reviewed version, or a version used in a specific workflow.
Markers are smaller than that.
A marker says: this version is worth noticing.
Maybe it was the first version that worked well. Maybe it was a milestone during a rewrite. Maybe it was stable enough to revisit later. Maybe it is just a checkpoint that should not get lost in the version list.
Not every important prompt version needs full label semantics.
Sometimes you only need a small flag attached directly to a version.
That is what markers are for.
They are deliberately simple. They do not try to encode deployment state, environment ownership, evaluation results, or production routing. They are just lightweight release signals inside the local history.
Search, list, and show became more useful
Organization only helps if the tools expose it.
So v0.4 updates list, show, and search to surface and use collection, role, and marker information.
For example, searching by metadata becomes more natural:
promptledger search --collection support --role system
Search can also work with an empty --contains, which means metadata-only filtering is now possible.
That sounds small, but it changes how PromptLedger can be used.
Before, search was mostly about finding prompt text. Now it can also be used to navigate the prompt library itself.
For example:
- show all system prompts in a collection
- find evaluation prompts across a project
- inspect versions marked as stable
- separate templates from user prompts
- review one slice of the library without relying on text search
This moves PromptLedger a little further from “prompt version storage” toward “prompt library workflow”.
Still local. Still small. Still inspectable.
But more practical once the number of prompt artifacts grows.
The Streamlit UI is still read-only
PromptLedger also has a small Streamlit UI for inspecting prompt history.
In v0.4, the UI now surfaces collection, role, and markers in timeline, detail, and comparison views.
That makes the UI more useful when browsing a prompt library. You can see not only how a prompt changed, but also what kind of prompt it is, which collection it belongs to, and whether a version was marked as stable or as a milestone.
The important part: the UI is still read-only.
That is intentional.
For now, PromptLedger keeps editing and logging in the CLI, while the UI remains focused on inspection. This keeps the implementation smaller and avoids turning the viewer into a second source of write behavior.
The terminal is where versions are created.
The UI is where history can be reviewed more comfortably.
That split still feels right for the project.
Database changes stayed local and simple
v0.4 moves the schema version from 3 to 5.
The main database changes are straightforward:
- a new
markerstable - new
collectionandrolecolumns onprompt_versions
- migrations for the local SQLite database
There is no remote migration service. No hosted registry. No account state. No backend coordination.
The migration story stayed aligned with the rest of the project: local, inspectable, and boring in a good way.
That matters because PromptLedger should remain easy to understand. A small SQLite-backed tool should not require infrastructure thinking just to store prompt history.
Tests expanded around the new workflows
v0.4 also expands the test coverage substantially around the areas that changed most:
- add workflows
- quick add behavior
- marker commands
- search and metadata filtering
- related list/show behavior
This is not the kind of testing expansion that makes for a dramatic release note, but it is important for this project.
PromptLedger deals with history. If history is stored incorrectly, the tool loses trust quickly.
So the goal is practical correctness:
- metadata should be reused only when expected
- explicit overrides should still win
- markers should attach to the right versions
- search should return the intended slice of the prompt library
- existing workflows should not become harder to use
For a local-first developer tool, confidence matters more than feature count.
Design tradeoffs
The main tradeoff in v0.4 was deciding how much structure to add.
PromptLedger could have gone further.
It could have introduced nested collections, custom role registries, marker categories, richer release channels, or project configuration files.
I avoided that for now.
The project works best when the concepts stay small:
- ids identify prompt histories
- versions preserve changes over time
- labels provide stronger named semantics
- markers provide lightweight version signals
- collection groups prompt versions
- role explains what kind of prompt artifact a version is
That is enough structure to make a growing prompt library easier to navigate, without making the tool feel like a platform.
This is also why markers are not labels with another name.
Labels are useful when you want something closer to a maintained pointer or status. Markers are useful when you want to annotate a version as notable.
Both can exist because they answer different workflow questions.
A label asks:
What does this version represent in a larger workflow?
A marker asks:
Is this version worth noticing later?
That difference is small, but it keeps the model clean.
What did not change
v0.4 does not change the basic philosophy of PromptLedger.
It is still a small, local-first prompt version control tool.
It still does not add:
- hosted registry
- prompt execution APIs
- agent tooling
- telemetry pipelines
- cloud sync
- automatic scoring
- evaluation harnesses
Those are not bad ideas in general. They are just outside the current scope of this project.
PromptLedger is not trying to run prompts, score prompts, deploy prompts, or orchestrate agents.
It is trying to make prompt changes easier to store, compare, review, and organize.
That boundary is useful.
Small scope is not a missing feature here. It is part of the design.
Closing thoughts
PromptLedger v0.4 is a usability and organization release.
It does not radically change what the tool is. Instead, it makes the existing workflow smoother.
Quick add reduces friction during iteration. Collection and role make prompt libraries easier to navigate. Markers create a lightweight way to remember important versions. Search, list, show, and the read-only UI now expose more of that structure.
The result is still intentionally modest.
A local SQLite database. A CLI. A read-only inspection UI. Deterministic exports and reviewable history where possible.
But the day-to-day workflow feels better now.
And for a tool like this, that matters.
Because prompt version control only becomes useful when it is easy enough to use consistently.
Links
PyPI: PyPI
GitHub: GitHub
LinkedIn: LinkedIn
Website: Website
SOCIAL SHARE CARD GENERATOR