A local-first prompt toolkit for your terminal. Find, compose, and reuse prompts with fewer keystrokes.
ph keeps your prompts and notes in Markdown files. Find one, add context, and copy it or pipe the text to another tool. Prompthive does not run models or require an account.
Meet Byt (pronounced byte).
Install the latest published release from crates.io with Cargo:
cargo install prompthive --locked
ph --versionTo build from a GitHub source release, extract it and run cargo install --path . --locked in its directory. Existing installations do not update automatically.
ph update attempts to update a crates.io installation in your Cargo home. It first rebuilds the installed version in a temporary directory and checks its bytes; a different toolchain or build environment may prevent a match. When an update is available, it asks you to confirm that the displayed installation is yours to update. Close other installers first: the check cannot prevent another program from changing the same file at the same time. If it cannot verify the installation, use the original installer instead. The command uses your existing Cargo executable and configuration, requires network access, and preserves the recorded target and feature choices. Windows and Cargo roots outside your home require a manual update.
If ph update fails on an older Cargo installation, use cargo install prompthive --locked to install the latest published version. The fix is included in 0.6.1 once it is published; 0.6.0 still has the issue. For a custom installation, supply the same --root, --target, and feature options used originally. If you installed Prompthive through another package manager, use that installer instead.
The default build includes the terminal picker. For a smaller build without it, add --no-default-features; exact-name commands and pipelines remain available.
On Linux, clipboard copying needs wl-copy on Wayland, or xclip or xsel on X11, plus a working desktop session. Prompthive starts no clipboard daemon of its own. Use a pipe or -q without a clipboard. An explicit copy request fails clearly when copying is unavailable.
If an update fails after installation starts, stop other installers and keep the recovery directory shown by ph. It contains the previous executable and Cargo tracking files. Compare the current files with those copies before deciding how to recover. Do not blindly overwrite the executable or Cargo tracking files: the current files may contain changes from other installations. Use your original installer or seek help if you are unsure how to reconcile them.
Start with ph in a terminal. Type to search, inspect the full name and preview, press Enter to use, or Escape to cancel. Press Tab to select an action, then use left and right to choose use, show the original text, or edit the saved prompt. Tab returns to search; left and right move the search cursor there. If a chosen template needs declared values, fill only the missing fields, inspect the final preview, and press Enter to finish. Prompts with all values already available keep the single Enter-to-use path. No selection is copied before you accept it. With no saved prompts, the picker offers a creation example.
| Action | Short | Long | Example |
|---|---|---|---|
| Use a prompt | u |
use |
ph u review |
| Find prompts | f |
find |
ph f review |
| Save new text | n |
new |
ph n review 'Review this: {input}' |
| Edit saved text | e |
edit |
ph e review |
| Compose prompts | c |
compose |
git diff | ph c work/rules,review |
Create the names in these examples first. ph also includes local starter prompts when creating a fresh store. An existing empty store stays empty.
ph n review 'Review this code. Explain concrete defects: {input}'
git diff | ph u review | less
printf '%s\n' 'Notes from the design meeting' | ph n notes/meeting
ph e notes/meeting
ph e # Search for a saved prompt to edit
ph n notes/today # In a terminal, open your editor for a new noteNames are case-sensitive. A case-insensitive filesystem cannot store case-only variants side by side; Prompthive rejects a differently cased selector and refuses to overwrite the existing file. work/review and personal/review are different prompts. Use exact, complete names in scripts. A prefix or fuzzy query requires a visible preview and confirmation; in a pipe it fails with candidate names on stderr. Adding another prompt never silently changes the meaning of an exact name. Retained short codes require a verified compatibility map; they are optional, and a real canonical name always wins.
ph e without a name opens a picker labeled for editing when both stdin and stdout are terminals; it never copies the selected prompt. ph e NAME still requires an exact name. ph n NAME without text opens $EDITOR only when both streams are terminals. Leaving that new document empty, cancelling, or failing the editor creates no note. Use an explicit empty argument (ph n NAME '') to create an empty note deliberately. Piped text and noninteractive commands retain their existing behavior.
Other actions are s/show, l/ls, r/rename, d/delete, t/tui, and x/clean. Run ph --help or ph ACTION --help for options. The action s shows original text; the flag -s NAME saves output:
ph s review # Original text, including {input}
ph s review -s notes/review-template # Save the original body under a new name
git diff | ph u review -s notes/run # Save rendered text under a new nameGenerate shell completions with ph completion bash, ph completion zsh, or ph completion fish, and load the output through your shell's completion setup. Saved-name suggestions read the current library, so new prompts need no script regeneration.
In a terminal, use renders the selected prompt and attempts to copy it. If automatic copying is unavailable, it shows the text and explains the clipboard problem. -q prints only raw text and disables automatic copying.
In a pipeline, stdout contains only the exact payload, with no status banners or invented trailing newline. Errors go to stderr and return a nonzero exit code. Bare ph with piped context and terminal output can use the controlling terminal for selection. With both streams piped, choose a name explicitly. Bare ph with empty input and nonterminal output prints compact help.
Choose at most one explicit destination. It overrides automatic pipe output and leaves stdout empty. On n, an explicit destination replaces the default save, so a failed file or copy operation cannot leave an extra prompt behind:
git diff | ph u review -f review.txt # New file; existing paths need --force
git diff | ph u review -s notes/run # New saved prompt; refuses an existing name
git diff | ph u review -a notes/run # Append with two newlines; keep target metadata
git diff | ph u review -c # Explicit clipboard copy
git diff | ph c work/rules,review --clipboard-c means copy on use/show/new/clean and the retained list/find destinations. Compose uses --clipboard; diff keeps -c for context and -f for format. -q never suppresses errors. Exit codes distinguish validation or lookup errors (2), an editor conflict (3), explicit clipboard failure (4), and cancellation (130).
{input}, {INPUT}, {content}, and {CONTENT} insert context from stdin or one positional input. Supplying both is an error. Input whitespace is preserved, and inserted text is literal: braces, environment placeholders, and shell-looking text inside a value are never executed or expanded again.
Declare named variables in optional YAML frontmatter. For example, save this as banks/work/explain.md inside your store:
---
id: work/explain
description: Explain a change
vars: {lang: null, tone: brief}
---
Explain this {lang} change in a {tone} tone: {input}git diff | ph u work/explain -v lang=Rust -v tone=directnull requires a supplied value; a string supplies a default. The interactive picker asks only for missing required values. Tab and Shift-Tab move between fields; Enter commits a value (including an explicit empty value), then shows the final preview. The rendered buffer is used unchanged after confirmation; an explicit --edit adds your requested editor review before output. Escape or Ctrl-C cancels without changing files or clipboard. Paste keeps Unicode, whitespace, and newlines; inserted values are never saved as defaults. Exact-name and noninteractive calls still use -v NAME=value and never ask questions. Unknown, repeated, or missing values fail before output. Undeclared braces remain ordinary text, and {{lang}} produces literal {lang}. Explicit {env:NAME} reads that environment variable or fails if it is absent. Prompthive does not load .env files. Date/time context is captured once per invocation: time and datetime use local time; date and iso_date use UTC, and timestamp is Unix seconds.
Composition is a left-to-right template chain. If a contains A {input} and b contains B {input}, ph c a,b context produces B A context. A stage without an input slot appends incoming text after two newlines. Every stage and required variable is checked before any destination changes. Explicit -v values apply to every stage declaring that name; other defaults remain local to each stage.
Composition files start with ./, ../, /, or ~, such as ph c ./rules.md,review context. A dotted name such as review.v1 is still a saved prompt name. Sources are local files, never URLs.
The default store is ~/.prompthive. Set PROMPTHIVE_BASE_DIR to choose a different store. Ordinary prompts live in prompts/, bank-qualified names in banks/, and retained team-path notes in teams/. There is no hidden project-store merge. Use ph e NAME with your chosen $EDITOR, or edit these Markdown files directly; the next invocation reads the change. Unknown frontmatter is retained during supported edits.
Mutations keep local preimages in .versions/ and do not prune them automatically. Writes use a process lock and atomic replacement. A failed required snapshot aborts the change. Editors work on a staged copy; if the source changed meanwhile, Prompthive reports a conflict and keeps recovery material. External editors do not share Prompthive's lock, so keep your own backups too. Power-loss durability depends on the operating system and filesystem; atomic replacement alone is not a universal guarantee.
ph version notes/meeting before-edit -m 'Before the rewrite'
ph versions notes/meeting -v
ph rollback notes/meeting before-edit
ph export ./prompt-backup
ph import ./prompt-backup --dry-run
ph import ./prompt-backupExport creates a new directory with raw Markdown, a checksummed manifest, and verified compatibility bindings. It excludes credentials, runtime configuration, and history. Import skips existing-file conflicts by default. --force backs up and replaces a conflicting prompt; --version keeps both under different names. A deleted name with recovery history remains reserved: use --force to restore it, --version for a new name, or --skip to leave it alone. A skipped or renamed prompt cannot activate an imported binding against unrelated existing content. A portable export is useful for transferring prompts; back up the full store separately to retain recovery history.
Reads, input, edited documents, and rendered output have a 32 MiB text budget. YAML frontmatter and editor configuration have a 1 MiB budget. Import/export batches, composition preparation, and library indexes have a 128 MiB aggregate budget; compiled templates and diff line indexes are limited to 65,536 segments or lines. Expanded YAML metadata is checked before building its value tree, including alias expansion. Oversized content is rejected before a destination changes. Nothing is truncated, migrated, or automatically deleted. Keep an external backup, including large notes you may need to edit outside these limits.
These limits do not resolve the retained YAML parser's maintenance advisory or make Prompthive a sandbox for hostile inputs. Real Wayland, macOS, and Windows desktop clipboard behavior still needs separate native acceptance; use text output when copying is unavailable.
Existing prompt and note files remain readable. Legacy credentials, cloud metadata, remote objects, and unknown retained files are left untouched. Old custom-variable configuration paths are not searched or guessed; add template vars declarations manually. The local CLI no longer offers accounts, sync, remote registries, publishing, teams administration, subscriptions, or telemetry. Placeholder dashboard commands are removed too. Rendering does not contact a service or rewrite your library.
Unverified generated shorthand no longer silently selects the highest-scoring match. Use an exact name or the picker. There is no bare ph NAME fallback: use ph u NAME. Version flags remain ph -v, ph -V, and ph --version; template variables use -v NAME=value after use or compose.
See CONTRIBUTING.md for development and regression checks. Prompthive is MIT licensed.