runprompt CLI
Single-file Python script that runs .prompt files from the shell: templates, JSON output, tools, chat and prompt-to-prompt pipelines
- 445 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The before: block and the shell and shell_tools tools run shell commands on your machine
- The write_file tool and Python functions can change files, and confirmation is turned off by the --safe-yes flag
- Provider keys sit in the environment or config.yml, and prompt and file text goes to the chosen provider
Install
Manual install
uvx --from git+https://github.com/chr15m/runprompt runprompt hello.promptRuns without installing. A provider key must be in the environment.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The before: block and the shell and shell_tools tools run shell commands on your machine
- The write_file tool and Python functions can change files, and confirmation is turned off by the --safe-yes flag
- Provider keys sit in the environment or config.yml, and prompt and file text goes to the chosen provider
This is third-party code. Review the repository files before installing.
What it does
runprompt runs dotprompt .prompt files straight from the terminal. One file holds YAML metadata (model, schemas, settings) and the prompt text with Handlebars-style templates. It is a single script with no dependencies: download it with curl, run it through uvx, or install it from GitHub with pip or uv. Input comes as arguments, JSON or stdin, with variables available as {{STDIN}}, {{ARGS}} and {{INPUT}}. Output can be described with a Picoschema and returned as clean JSON, and one prompt's output can be piped into another. Before the request goes out, a before: block runs shell commands (for example git log -1 --oneline) and substitutes the result, while files: and --read attach files by glob plus URLs. An interactive --chat mode offers /read, /edit and /drop commands. Any prompt can get tools: Python functions with docstrings, short shell_tools, or built-ins (calculator, fetch_clean, datetime, shell, write_file('path')). Each tool call asks for confirmation by default, and the --safe-yes flag skips only tools marked safe. Providers are Anthropic, OpenAI, Google AI, OpenRouter and any OpenAI-compatible endpoint such as Ollama.
Who it is for. For developers and sysadmins who keep prompts in a repository as files and run them from scripts, cron and shell pipelines.
Good fit when
- You want to run the same prompt over files and get structured JSON: cat article.txt | ./runprompt summarize.prompt
- The first prompt's result has to become the second one's input, as in extract.prompt | generate-bio.prompt
- A prompt should take context from git log, git diff or a file list added by a before: block
- You want to run a .prompt as an executable with a #!/usr/bin/env runprompt shebang
- You need one runner for different providers and local Ollama without separate SDKs
Not a fit when
- You need a full coding agent that edits a project: runprompt executes the prompt you give it and does not run a development loop
- You want an MCP server or a skill for an agent: runprompt is launched as a separate command
- The machine has no Python 3.8 or newer and cannot install uv or pip
- You need a graphical interface: runprompt works from the command line only
Example request
Write a summarize.prompt that turns text from stdin into five takeaways as JSON and run it on README.mdLimitations
Needs Python 3.8 or newer. The extra packages pyyaml and playwright are optional: they improve YAML parsing and web page loading (pip install runprompt[full]).
- A provider key is needed: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY or OPENROUTER_API_KEY. A local Ollama needs no key.
- The built-in shell and write_file tools and any functions of your own require confirmation; --safe-yes lifts it only for tools marked safe.
- Keys can sit in config.yml in plain text, so restrict the file's permissions.
How to disable. Delete the runprompt file or run pip uninstall runprompt. Settings live in ~/.runprompt/config.yml, ~/.config/runprompt/config.yml and ./.runprompt/config.yml, and the response cache in the directory from RUNPROMPT_CACHE_DIR.
FAQ
How do I run runprompt without installing it?
Use uvx --from git+https://github.com/chr15m/runprompt runprompt hello.prompt. You can also download the single runprompt file and make it executable.
How do I get JSON instead of text?
Declare output.format: json and an output.schema in Picoschema. Fields ending with a question mark are optional, and the answer prints as clean JSON ready for the next prompt in a pipeline.
How do I use local Ollama?
Set the model ollama/llama3, or pass the address with --base-url http://localhost:11434/v1 or the RUNPROMPT_BASE_URL variable. A key is optional here.
Is it safe to give a prompt tools?
Every tool call asks for confirmation by default. --safe-yes skips only functions marked fn.safe = True, and write_file('output.txt') limits writing to a single file.
How do I keep responses while debugging a prompt?
Turn the cache on with --cache: a repeat run with the same input reads the answer from the cache and skips the API.
Discussion
No questions or reviews yet.
Related
CLI tools29 ready-made prompts in Chinese: a five-step dev flow, code review, Draw.io diagrams, reports, WeChat articles and thesis chapters
Promptr sends a plain-language task to an OpenAI model and writes the proposed changes straight into your project files from the terminal
A Rust CLI that packs a codebase into one prompt with a file tree, templates and token estimates
A console chat with ChatGPT, Claude, Gemini and Cohere: custom assistants in YAML, one-shot prompts from scripts and shell commands you edit before running
cc-1c-init: 1C project init prompt
cc-1c-init
A Claude Code prompt that sets up a 1C project structure with coding standards, role agents, skills and MCP
Two Rust commands for the terminal: qq answers a quick command-line question, and qa performs a single step with files and commands
Comparison with similar tools
Entries that share the main search query, and how they differ.
README in short
The page shows how to install and run the script, then walks through features with examples: stdin and argument input, inline prompts, schema-based JSON, pipelines, before: commands, executable prompts, chat and file attachment. It then describes tools (Python functions, shell_tools, built-ins), template syntax, configuration layers, provider keys, custom API endpoints, caching and dotprompt spec compliance. The license is MIT.