Skip to content

cli.md

Latest commit

 

History

History
246 lines (182 loc) · 6.99 KB

cli.md

File metadata and controls

246 lines (182 loc) · 6.99 KB
Raw

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.