CLI Guide

Copy Markdown View Source

Prompt Runner exposes the same CLI through three entry points:

  • mix prompt_runner ...
  • mix run run_prompts.exs -- ...
  • ./prompt_runner ... after mix escript.build

All commands operate on a packet directory. If you omit the directory, Prompt Runner uses the current working directory.

Setup Commands

Initialize the global profile store:

mix prompt_runner init
mix prompt_runner template list

Create and inspect profiles:

mix prompt_runner profile new codex-fast --provider codex --model gpt-5.4 --reasoning high
mix prompt_runner profile list

Packet Authoring Commands

Create a packet:

mix prompt_runner packet new demo \
  --profile simulated-default \
  --provider simulated \
  --model simulated-demo \
  --repo app=/path/to/repo \
  --default-repo app \
  --prompt-template from-adr

mix prompt_runner prompt new 01 \
  --packet demo \
  --phase 1 \
  --name "Capture runtime boundaries" \
  --targets app \
  --commit "docs: add runtime boundaries summary"

mix prompt_runner checklist sync demo

Packet-local templates can override the home-scoped templates created by init. List visible templates for a packet with:

mix prompt_runner template list demo

Use the packet manifest's recovery: block for the full policy surface. The CLI flags are convenience shorthands for common resume/retry/repair defaults.

Inspect packet metadata and runtime readiness:

mix prompt_runner packet explain demo
mix prompt_runner packet preflight demo
mix prompt_runner packet doctor demo

packet preflight is the runtime gate used before provider execution. It prints JSON, exits non-zero when packet repos or git state are not ready, and is called automatically by run unless --skip-preflight is explicit.

Execution Commands

List and plan:

mix prompt_runner list demo
mix prompt_runner plan demo

Run everything:

mix prompt_runner run demo
mix prompt_runner run demo --skip-preflight

Run specific prompts:

mix prompt_runner run demo 01 02
mix prompt_runner run demo --phase 2

Repair a failed prompt from stored verifier state:

mix prompt_runner repair --packet demo 02

Print runtime status JSON:

mix prompt_runner status demo

Useful Execution Flags

run accepts:

  • --provider
  • --model
  • --log-mode
  • --log-meta
  • --events-mode
  • --tool-output
  • --cli-confirmation
  • --runtime-store
  • --committer
  • --no-commit

packet new accepts:

  • --repo NAME=PATH (repeatable)
  • --default-repo
  • --prompt-template
  • --profile
  • --provider
  • --model
  • --reasoning
  • --permission
  • --resume-attempts
  • --retry-attempts
  • --retry-base-delay-ms
  • --retry-max-delay-ms
  • --retry-jitter
  • --auto-repair
  • --repair-attempts
  • --cli-confirmation

prompt new accepts:

  • --packet
  • --phase
  • --name
  • --targets
  • --commit
  • --template

Example:

mix prompt_runner run demo \
  --provider codex \
  --model gpt-5.4 \
  --log-mode compact \
  --cli-confirmation require

Escript

Build once:

mix escript.build

Then use the same commands:

./prompt_runner run demo
./prompt_runner status demo