Command-Line Interface (CLI)

The promptbranch CLI (@promptbranch/cli) exposes the agent-safe library workflow plus human sharing commands to shell scripts and terminal workflows.

It requires Node.js 22 or later.

Run a command without installing anything globally:

npx -y @promptbranch/cli@latest db-path

Or install the package globally so the examples below work with the shorter command:

npm install --global @promptbranch/cli@latest

---

Global Options & Output Formats

Plain Text vs. Machine-Readable JSON (--json)

• Standard Output (Default): Optimized for Unix piping and terminal readability. For example, promptbranch get outputs only the raw prompt content to stdout, making it directly pipeable into LLM CLI utilities or files.
• --json Flag: Emits structured JSON outputs suitable for parsing with jq, Python, or automation scripts.

# Pipe prompt content directly into an LLM command
promptbranch get "pr-review" | llm -m claude-3-5-sonnet

# Parse prompt metadata with jq
promptbranch get "pr-review" --json | jq '.versionLabel'

promptbranch db-path --json returns a { "path": "..." } object. Both the plain and JSON forms only resolve the path; they do not create or migrate a database.

---

Command Reference

1. promptbranch list

Lists all active prompts in the library.

promptbranch list [--tag <tag_name>] [--collection <collection_name>] [--json]

Example

promptbranch list --tag security
# Output:
# sql-injection-audit   v2   2026-08-27T18:00:00.000Z   1202e635-...
# auth-flow-check       v1   2026-08-25T12:30:00.000Z   d6eb38dc-...

---

2. promptbranch get

Retrieves a prompt's text content. Defaults to the current designated production version.

promptbranch get <name-or-id> \
  [--version-id <id> | --version <n> [--branch <branch_name>]] \
  [--json]

Examples

# Output raw prompt template to stdout
promptbranch get "sql-injection-audit"

# Fetch specific version and redirect to a file
promptbranch get "sql-injection-audit" --version 1 > /tmp/prompt_v1.md

# Reliably fetch the exact same content in automation
promptbranch get "sql-injection-audit" \
  --version-id "8b3a7d7e-..." > /tmp/pinned_prompt.md

# Fetch prompt on an experimental branch
promptbranch get "sql-injection-audit" --branch "experiment/concise"

JSON output includes versionId. Use that stable id when a script or agent must retrieve the same version record later. A desktop user can amend its content, so fetch it again before use when freshness matters and create a new version when content must remain a historical snapshot. Version numbers are useful display labels scoped to a variation. They remain unchanged when another version is deleted, so history can contain gaps. A number can still be reconciled if paired devices independently create the same number; it is not a durable automation pin.

---

3. promptbranch search

Searches prompt titles, descriptions, tags, notes, and version content.

promptbranch search <query> [--limit <n>] [--json]

Example

promptbranch search "sanitize inputs" --limit 5

---

4. promptbranch report-run

Logs an execution run against a prompt version, recording the tool, model, outcome rating (1–5), and summary.

promptbranch report-run --prompt <name-or-id> \
  [--version-id <id> | --version <n>] \
  [--tool <tool_name>] \
  [--model <model_name>] \
  [--outcome <1-5>] \
  [--summary "..."] \
  [--json]

--tool is optional and defaults to cli.

Example

promptbranch report-run --prompt "sql-injection-audit" \
  --tool "local-eval" \
  --model "claude-3-5-sonnet" \
  --outcome 5 \
  --summary "Identified 3 vulnerabilities in sample codebase"

---

5. promptbranch add-note

Attaches a context note to a prompt or specific version.

promptbranch add-note --prompt <name-or-id> --body "..." [--version-id <id>] [--json]

---

6. promptbranch suggest

Submits caller-provided rewritten content as a variation of a prompt. It does not generate text: write the complete revision yourself or have an agent create it first. The suggestion is created as pending awaiting human approval in the desktop app.

Supply exactly one content source: --file or --content. For a multi-line revision, use --file.

promptbranch suggest --prompt <name-or-id> \
  (--file <path> | --content "...") \
  [--rationale "..."] \
  [--base-version-id <id> | --base-version <n>] \
  [--json]

Example

promptbranch suggest --prompt "sql-injection-audit" \
  --file ./sql-injection-audit-revision.md \
  --rationale "Refined instructions to reduce false positives"

---

7. promptbranch suggestions

Lists all pending variations currently waiting in the human review queue.

promptbranch suggestions [--json]

---

8. promptbranch publish

Scans for secrets and publishes an immutable snapshot to the sharing portal.

promptbranch publish <name-or-id> \
  [--full-history] \
  [--description "..."] \
  [--portal <portal_url>] \
  [--preview | --yes] \
  [--json]

Run --preview first to print the exact payload and secret-scan findings. It does not publish, make a portal request, create a shared-snapshot record, or save a delete token.

In a terminal, publish displays the review and asks Publish this snapshot? [y/N]. Only y or yes publishes; every other response cancels. For a non-interactive command, use --yes only after the caller has reviewed the payload and findings. It records deliberate non-interactive caller intent; it does not make an unrestricted shell agent safe. --json changes output formatting only and never authorizes publishing by itself.

High-severity findings always block publishing. Medium-severity findings are shown and require the terminal decision or a deliberate --yes decision.

Examples

promptbranch publish "security-audit" --preview
promptbranch publish "security-audit" --full-history
promptbranch publish "security-audit" --full-history --yes --json

Use the desktop Share dialog for the fully visual human workflow. MCP intentionally has no publish tool, so it remains the safer surface for agents that must not publish.

---

9. promptbranch import

Imports a shared snapshot from a portal URL or snapshot ID into your local library.

promptbranch import <url-or-id> [--portal <portal_url>] [--json]

Portal publish and import requests time out after 30 seconds and return a non-zero exit with an actionable error rather than waiting indefinitely.

---

10. promptbranch db-path

Prints the absolute filesystem path of the resolved SQLite database file.

promptbranch db-path
# /Users/username/Library/Application Support/PromptBranch/library.db

promptbranch db-path --json
# { "path": "/Users/username/Library/Application Support/PromptBranch/library.db" }

---

promptbranch help

Running promptbranch, promptbranch help, --help, or -h prints the full command list and exits.