prompt-lineage 0.1.0

Git-like version control for LLM prompts

Lineage

Git-like version control for LLM prompts.

Lineage tracks every version of your LLM prompts — commit, diff, test, and roll back from the terminal. Built for developers who treat prompts like code.

The problem

Prompts are code, but most teams treat them like scratch notes — no history, no diffs, no rollback. Lineage gives you git-style version control purpose-built for .prompt files so you can track what changed, when, and why.

Install

pip install prompt-lineage

Or install from source:

git clone https://github.com/Shr1tan/lineage.git
cd lineage
pip install -e .

Commands

promptctl init

Creates a .promptctl/ directory with a SQLite store and a prompts/ folder.

$ promptctl init
╭── promptctl init ──╮
│ Initialized promptctl in .promptctl/ │
│ Prompt files go in prompts/          │
╰────────────────────╯

promptctl commit <name> -m "message"

Reads prompts/<name>.prompt, snapshots its content, and auto-increments the version.

$ promptctl commit email-subject-line -m "initial version"
╭── promptctl commit ──╮
│ Committed email-subject-line@v1 │
│ Message: initial version        │
╰──────────────────────╯

promptctl log <name>

Shows version history as a table, most recent first.

$ promptctl log email-subject-line
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Version ┃ Message                 ┃ Author ┃ Date                ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│   v2    │ added recipient context │ you    │ 2026-03-18 18:26:32 │
│   v1    │ initial version         │ you    │ 2026-03-18 18:26:20 │
└─────────┴─────────────────────────┴────────┴─────────────────────┘

promptctl diff <name>@v1 <name>@v2

Colored unified diff between any two versions.

$ promptctl diff email-subject-line@v1 email-subject-line@v2
-variables: [recipient_name, company, role]
+variables: [recipient_name, company, role, tone]

-You are a sales email assistant. Write a subject line
+You are a sales email assistant. Write a compelling subject line

promptctl checkout <name>@v<n>

Restores a specific version back to prompts/<name>.prompt.

$ promptctl checkout email-subject-line@v1
╭── promptctl checkout ──╮
│ Checked out email-subject-line@v1 → prompts/email-subject-line.prompt │
╰────────────────────────╯

promptctl status

Shows which prompts are clean, modified, or untracked.

$ promptctl status
┌─────────────────────┬─────────┬──────────────────────┬───────────┬───────────┐
│ Prompt              │ Version │ Last message         │ Committed │ Status    │
├─────────────────────┼─────────┼──────────────────────┼───────────┼───────────┤
│ email-subject-line  │ v3      │ added urgency framing│ 2h ago    │ clean     │
│ code-review         │ v1      │ initial version      │ 3d ago    │ modified  │
│ onboarding-email    │ —       │ —                    │ —         │ untracked │
└─────────────────────┴─────────┴──────────────────────┴───────────┴───────────┘

promptctl test <name>

Runs a prompt against an LLM with test cases from a .prompttest file.

$ promptctl test email-subject-line
Testing email-subject-line@v2

─── Case: basic-cold-outreach ───
Output: "Quick follow-up on API reliability at Stripe"

─── Case: enterprise-outreach ───
Output: "Exploring OpenAI API impact on your roadmap"

2 cases run.

Prompt file format

---
name: email-subject-line
description: Generates subject lines for cold outreach
variables: [recipient_name, company, role]
---

You are a sales email assistant. Write a subject line
for the following cold outreach email.

Recipient: {{recipient_name}}, {{role}} at {{company}}
Email body: {{email_body}}

Subject line only. No explanation.

YAML frontmatter defines metadata. The body below --- is the prompt template. Use {{variable}} for interpolation.

Roadmap

• Web UI — browser-based dashboard for browsing prompt history, comparing versions, and running evals
• Assertions — add pass/fail criteria to .prompttest files for automated scoring
• GitHub Actions integration — CI pipeline to eval prompts on every PR and block merges on regression