DEV Community

Cover image for PromptLedger v0.2 — Labels, Status, and Better Diffs
Ertugrul
Ertugrul

Posted on

PromptLedger v0.2 — Labels, Status, and Better Diffs

#promptengineering #python #opensource #showdev

Devlog — Part 2

What changed after the first release, and why those changes matter in practice.

In the first part, I introduced PromptLedger as a deliberately small, local-first tool for treating prompts like code.

Since then, the project has moved from a minimal prompt history tracker to something closer to a prompt release ledger — without adding servers, agents, or execution layers.

This post covers what changed in v0.2, why those changes exist, and how they affect real prompt workflows.

Why a second part?

After publishing Part 1, the most common follow-up questions were:

  • Which prompt is actually in production right now?
  • How do I compare prod vs staging without remembering version numbers?
  • Can I see when a release pointer changed?

Answering these questions required release semantics, not more prompt editing features.

That is the focus of v0.2.

Label history: prompts need an audit trail

In v0.1, labels existed as movable pointers, similar to git tags. However, once a label moved, its previous state was lost.

In v0.2, every label update is recorded in an append-only history log.

This means you can now answer questions like:

  • What prompt was in production yesterday?
  • When did prod move from version 7 to version 9? 
promptledger label history --id onboarding
Enter fullscreen mode Exit fullscreen mode

Under the hood, label history is implemented as a separate label_events table. Label pointers remain mutable, but the history is immutable.

This keeps the system simple while adding real auditability.

Label-based diff: stop thinking in version numbers

Version numbers are great for storage, but humans think in environments.

v0.2 allows diffs to be expressed in terms of labels:

promptledger diff --id onboarding --from prod --to staging
Enter fullscreen mode Exit fullscreen mode

This resolves labels to their underlying versions and performs a normal diff.

The important detail is that nothing new is stored. Labels are only references; diffs always operate on immutable prompt versions.

Status command: a one-line overview

Another recurring problem was simply understanding the current state of prompts.

The new status command provides a concise, git-style overview:

promptledger status
Enter fullscreen mode Exit fullscreen mode

For each prompt, it shows:

  • The latest version number
  • The timestamp of that version
  • Active labels and the versions they point to

This is intentionally read-only and summary-focused. If you need details, you still drill down using list, show, or diff.

Better diff modes

Prompt changes are not always best reviewed line-by-line.

v0.2 introduces multiple diff modes built on top of Python’s difflib:

  • unified — the default, git-style view
  • context — useful for wider structural changes
  • ndiff — character-level insight for small edits
  • metadata — diff only metadata (reason, tags, env, metrics) 
promptledger diff --id onboarding --from 1 --to 2 --mode metadata
Enter fullscreen mode Exit fullscreen mode

Metadata diffs are always rendered in unified format to keep them readable and deterministic.

UI update: history without write access

The Streamlit UI remains strictly read-only, but v0.2 adds label history visibility.

You can now:

  • Inspect prompt timelines
  • See which labels point where
  • Review label movements over time

All mutations still go through the CLI or Python API.

This constraint is intentional: the UI is for inspection, not experimentation.

What did not change

Several things were deliberately left out:

  • No prompt execution or playground
  • No agent framework
  • No cloud sync or backend service
  • No automatic evaluation or scoring

PromptLedger is still a ledger, not an environment.

Migration and compatibility

v0.2 introduces a database schema migration, but it is fully backwards compatible.

Existing databases are upgraded in place, with no data loss.

The new tables add information, but do not change existing semantics.

Closing

v0.2 did not make PromptLedger bigger — it made it clearer.

By adding release semantics, auditability, and better inspection tools, prompts can now be reviewed and promoted with the same discipline as code.

No servers. No dashboards. No magic.

Just history, diffs, and intent — stored locally.

Links

Pypi : Pypi
Github : Github
My Linkedin : Linkedin
My Website : Website

Top comments (0)