Skip to content
blogus uvx blogus

Quickstart

From inline string to locked prompt

Five commands, about two minutes. Everything runs locally; only the optional exec / analyze / test commands ever call a model.

$ uv add blogus

No install? Prefix any command with uvx. Local web UI ships behind blogus[web]; the TUI behind blogus[tui].

  1. 01

    Scan an existing repo

    Run blogus in any repository that already calls an LLM. It lists every OpenAI and Anthropic call it can find in Python and JavaScript, with file and line, and flags the unversioned ones.

    $ uvx blogus scan
Found 3 LLM API calls:
  src/chat.py:15         OpenAI      unversioned
  src/summarize.py:42    OpenAI      unversioned
  lib/translate.js:28    Anthropic   unversioned
  2. 02

    Create the prompts directory

    blogus init scaffolds prompts/. Promote each inline string into a .prompt file — YAML frontmatter for name, model, temperature, and variables, then the template body.

    $ blogus init
Created prompts/
Move inline strings into prompts/<name>.prompt
  3. 03

    Lock the content hashes

    blogus lock writes prompts.lock: one entry per prompt with a sha256 over the template content and the git commit it came from. Commit this file like any other lockfile.

    $ blogus lock
Wrote prompts.lock (3 prompts, sha256 pinned)
  4. 04

    Sync your call sites

    blogus fix rewrites the original code to call load_prompt() and inserts a sha256 marker comment above it. Your runtime now reads the versioned file instead of an inline literal.

    $ blogus fix
Rewrote src/summarize.py -> load_prompt("summarize")
Inserted marker  # @blogus:summarize sha256:a1b2c3d4
  5. 05

    Gate CI on verify

    blogus verify recomputes hashes on disk and exits non-zero if the code markers, .prompt files, and prompts.lock disagree. Add it to pre-commit or your build and stop merging unreviewed prompt edits.

    $ blogus verify || exit 1
ok — lockfile matches

That’s the loop

Read the full docs, browse the command reference, or see how teams use it.