Skip to main content

Branch, pin, and roll back a prompt

This guide takes one prompt through a full change cycle on the server: branch, publish to the branch, pin, merge, and roll back. Agents that read the served HEAD (main) see nothing until you merge, and a rollback puts the old version back for every agent at once.

The versioning concept page explains commits, branches, and the served HEAD.

Prerequisites​

Before you begin, make sure you have:

  • A running Priompt server on localhost:8443. See the Quickstart.
  • An rw token, if the server has authentication on. See Secure a server.
  • A client for the tab you pick:
    • Python: pip install priompt-sdk.
    • Node: npm install @priompt/client.
    • grpcurl: grpcurl and a copy of prompt.proto. The server doesn't enable gRPC reflection.
SDK coverage

PromptClient in both SDKs wraps GetPrompt, including pinned reads, but not the branch RPCs. The examples call History, CreateBranch, PublishPrompt on a branch, MergeBranch, and SetBranch through the generated stubs that ship with each SDK.

1. Connect​

Create a shared setup file. Each later step imports it.

common.py
import grpc
from priompt_sdk import PromptClient
from priompt_sdk.v1 import prompt_pb2 as pb, prompt_pb2_grpc as rpc

HOST = "localhost:8443"
URI = "priompt://acme/support/agent"
md = None  # [("authorization", "Bearer <token>")] when auth is on

client = PromptClient(host=HOST)  # token="<token>" when auth is on
stub = rpc.PromptServiceStub(grpc.insecure_channel(HOST))

<token> is an rw token for the acme org.

2. Publish two versions​

Give the prompt some history on main:

printf 'You are a support agent for {org}. Be concise and kind.' > v1.txt
printf 'You are a support agent for {org}. Be concise and kind. Offer a refund when reasonable.' > v2.txt
priompt publish -uri priompt://acme/support/agent -file v1.txt -slot org
priompt publish -uri priompt://acme/support/agent -file v2.txt -slot org
Output
published priompt://acme/support/agent (1024719f5bbe) — subscribers notified
published priompt://acme/support/agent (b436dfe49b72) — subscribers notified

3. Find a commit​

History lists the commits on a branch, newest first.

history.py
from common import *

commits = stub.History(pb.HistoryRequest(uri=URI, branch="main"), metadata=md).commits
for c in commits:
    print(c.hash[:12], c.message or "(no message)")
Output
c74e161b5a01 (no message)
3514468e2381 (no message)

Commit hashes don't include a timestamp. On a fresh server without authentication, you get the same hashes as this guide.

4. Create a branch​

CreateBranch starts a branch at the tip of another branch.

branch.py
from common import *

r = stub.CreateBranch(pb.CreateBranchRequest(uri=URI, name="feat", **{"from": "main"}), metadata=md)
print("feat starts at", r.commit_hash[:12])

from is a Python keyword, so pass it with **{"from": "main"}.

Output
feat starts at c74e161b5a01

5. Publish to the branch​

A publish with branch set records a commit on that branch. It doesn't change what agents are served, and it doesn't notify subscribers.

publish_branch.py
from common import *

r = stub.PublishPrompt(pb.PublishPromptRequest(
    uri=URI, branch="feat", slots=["org"], message="ask for the order number",
    template="You are a support agent for {org}. Ask for the order number first."),
    metadata=md)
print("feat version", r.version_hash[:12])
print("main serves:", client.get(URI).template)
Output
feat version 4137353438f2
main serves: You are a support agent for {org}. Be concise and kind. Offer a refund when reasonable.

6. Pin a version​

Pass a ref to read a branch tip or a commit instead of the served HEAD. A pinned read returns the commit_hash, which you can store and pin to later. Pinned reads skip the cache.

pin.py
from common import *

p = client.get(URI, ref="feat")
print(p.template)
print("commit", p.commit_hash)
Output
You are a support agent for {org}. Ask for the order number first.
commit c43d538ff5189f9864cbf7f2301270568ad46e37981f2d70d3431cff1d40ad83

A ref must be a branch name or a full 64-character commit hash. A shortened hash returns NOT_FOUND.

7. Merge into main​

MergeBranch records a merge commit on main with the source branch's content. The served HEAD changes and the server cache is cleared.

merge.py
from common import *

r = stub.MergeBranch(pb.MergeBranchRequest(
    uri=URI, into="main", message="ship the order-number rule", **{"from": "feat"}),
    metadata=md)
print("merge commit", r.commit_hash[:12])
print("main serves:", client.get(URI).template)
Output
merge commit 0cd1e53a2a7a
main serves: You are a support agent for {org}. Ask for the order number first.
note

A merge into main sends a change event, like a publish or a rollback on main. In v0.7.2 and earlier it didn't, and agents picked up the merged version on their next fetch after their cache expired.

8. Roll back​

SetBranch points main at an earlier commit. Every agent gets that version on its next read, and subscribers receive a change event with a verdict. Nothing is deleted: the merge commit still exists and you can still pin it by hash.

rollback.py
from common import *

GOOD = "c74e161b5a01"  # the commit to go back to, from History
commits = stub.History(pb.HistoryRequest(uri=URI), metadata=md).commits
full = next(c.hash for c in commits if c.hash.startswith(GOOD))
r = stub.SetBranch(pb.SetBranchRequest(uri=URI, branch="main", commit_hash=full), metadata=md)
print("main serves version", r.version_hash[:12])
print(client.get(URI).template)
Output
main serves version b436dfe49b72
You are a support agent for {org}. Be concise and kind. Offer a refund when reasonable.

SetBranch needs the full commit hash, so the Python and Node examples look it up from History by prefix. After the rollback, History on main walks back from the new tip, so it lists c74e161b5a01 and 3514468e2381 again.

Next steps​