chr15m/runprompt

Run LLM prompts from your shell

What it solves

runprompt allows users to run LLM prompts directly from the shell, treating prompts as first-class, version-controllable artifacts rather than ad-hoc chatbot requests. It eliminates the need to manually copy-paste prompts and data into a web interface by providing a way to execute .prompt files (which bundle the prompt text and metadata like model and schema) via the command line.

How it works

The tool uses .prompt files that contain a YAML frontmatter section for configuration (model, output format, tools) and a template body. It supports:

  • Input Handling: Accepts data via STDIN, command-line arguments, or JSON strings, which are then interpolated into the prompt using Handlebars/Mustache syntax.

  • Dynamic Context: The before: key in frontmatter allows executing shell commands to gather real-time data (e.g., git log) before sending the prompt to the LLM.

  • Structured Output: Uses Picoschema to define output formats, enabling the LLM to return parseable JSON.

  • Extensibility: Supports "tools" defined as Python functions or inline shell scripts that the LLM can call during execution to interact with the system.

  • Execution: Can be run as a standalone script, installed via pip/uv, or used as an executable via a shebang (#!/usr/bin/env runprompt).

Who it’s for

Developers and power users who want to automate AI workflows, build custom CLI harnesses for LLMs, or integrate AI prompts into shell scripts and CI/CD pipelines.

Highlights

  • Prompt Artifacts: Bundle model config, schemas, and prompt text in a single .prompt file.
  • Shell Integration: Native support for piping data between prompts and executing pre-prompt shell commands.
  • Tool Use: Ability to define custom Python tools or simple shell tools for the LLM to call.
  • Interactive Mode: A built-in chat mode with commands to read files or grant the LLM write access to specific files.
  • Multi-Provider Support: Works with Anthropic, OpenAI, Google AI, OpenRouter, and any OpenAI-compatible endpoint (e.g., Ollama).

Related

  • Project
    microsoft/prompty

    A markdown-based file format and runtime for LLM prompts that decouples prompt engineering from application code, supporting Python, TypeScript, and VS Code.

  • Project
    TheR1D/shell_gpt

    A command-line productivity tool that uses LLMs to generate shell commands, code snippets, and documentation directly in the terminal.

  • Project
    microsoft/promptflow

    A suite of development tools for streamlining the end-to-end cycle of LLM-based AI applications, from prototyping and prompt engineering to evaluation and production deployment.

  • Project
    kardolus/chatgpt-cli

    ChatGPT CLI is a cross‑platform command‑line client for many LLM providers. It offers streaming, interactive REPL, prompt‑file support, image/audio handling, MCP tool calls, and an experimental agent mode with safety budgets. Install via Homebrew or pre‑built binaries, configure with environment variables or a YAML file, and start chatting with `chatgpt "your question"`.

  • Project
    simonmysun/ell

    A lightweight Bash-based command-line interface for LLMs that allows users to query models, chat interactively, and provide terminal context via pipes and recording.