### Install runprompt using pip

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Install runprompt using pip, the standard Python package installer.

```bash
# Using pip
pip install "git+https://github.com/chr15m/runprompt.git"
```

--------------------------------

### Runprompt Configuration File Example

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Example of a .runprompt/config.yml file showing how to set model, cache, timeout, tool paths, and API keys.

```yaml
# ./.runprompt/config.yml, ~/.config/runprompt/config.yml, or ~/.runprompt/config.yml
model: openai/gpt-4o
default_model: anthropic/claude-sonnet-4-20250514  # fallback if model not set anywhere
cache: true
safe_yes: true
timeout: 120
tool_path:
  - ./tools
  - /shared/tools
openai_api_key: sk-...
```

--------------------------------

### Install runprompt using uv

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Install runprompt using uv, the recommended package and virtual environment manager.

```bash
# Using uv (recommended)
uv pip install git+https://github.com/chr15m/runprompt
```

--------------------------------

### Install Optional Dependencies with Pip

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Install runprompt with all optional dependencies, including PyYAML for full YAML support and Playwright for web scraping, using pip. This command installs directly from the GitHub repository.

```bash
pip install "runprompt[full] @ git+https://github.com/chr15m/runprompt.git"
```

--------------------------------

### Define a .prompt file

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Example of a .prompt file using YAML front matter for model and schema, followed by the prompt template.

```yaml
---
model: anthropic/claude-sonnet-4-20250514
---
Say hello to {{name}}!
```

--------------------------------

### Run Prompt with Tool Confirmation

Source: https://github.com/chr15m/runprompt/blob/main/README.md

When the LLM decides to call a tool, the CLI prompts for confirmation before execution. This example shows a tool call for getting weather.

```bash
$ ./runprompt weather.prompt

I'll check the weather for you.

Tool call: get_weather
Arguments: {"city": "Tokyo"}

Run this tool? [y/n]: y

The weather in Tokyo is currently 72°F and sunny.
```

--------------------------------

### Run runprompt directly with uvx

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Execute the runprompt script without installation using uvx, specifying the Git repository and the prompt file.

```bash
uvx --from git+https://github.com/chr15m/runprompt runprompt hello.prompt
```

--------------------------------

### Starting Bare Interactive Chat

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Start an interactive chat session without a prompt file. A model must be specified using the --model flag.

```bash
./runprompt --chat --model anthropic/claude-sonnet-4-20250514
```

--------------------------------

### Starting Interactive Chat with a Prompt File

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Initiate an interactive chat session using a prompt file to set the initial context or persona. The conversation history is maintained.

```bash
./runprompt --chat expert.prompt
```

--------------------------------

### Define Tools in Python

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Define tools as Python functions with docstrings. Any function with a docstring is discoverable as a tool. Example includes functions for getting weather and calculating expressions.

```python
# my_tools.py
def get_weather(city: str):
    """Gets the current weather for a city.
    
    Returns the temperature and conditions for the specified location.
    """
    # Your implementation here
    return {"temp": 72, "conditions": "sunny"}

def calculate(expression: str):
    """Evaluates a mathematical expression.
    
    Use this for arithmetic calculations.
    """
    return eval(expression)
```

--------------------------------

### Tool Error Handling Example

Source: https://github.com/chr15m/runprompt/blob/main/README.md

If a tool raises an exception during execution, the error is returned to the LLM, allowing it to handle the situation gracefully, such as asking for alternative input.

```bash
Tool call: read_file
Arguments: {"path": "missing.txt"}

Run this tool? [y/n]: y
FileNotFoundError: [Errno 2] No such file or directory: 'missing.txt'

I couldn't read that file because it doesn't exist. Would you like me to try a different path?
```

--------------------------------

### Download and make runprompt executable

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Download the single-file script using curl and make it executable with chmod.

```bash
curl -O https://raw.githubusercontent.com/chr15m/runprompt/main/runprompt
chmod +x runprompt
```

--------------------------------

### Executing an Executable Prompt File

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Make a prompt file executable using chmod and then run it, passing template variables via standard input.

```bash
chmod +x hello.prompt
echo '{"name": "World"}' | ./hello.prompt
```

--------------------------------

### Executable Prompt File with Shebang

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Make a .prompt file directly executable by adding a shebang line pointing to 'runprompt'. Ensure 'runprompt' is in your PATH or provide a relative/absolute path.

```handlebars
#!/usr/bin/env runprompt
---
model: anthropic/claude-sonnet-4-20250514
---
Hello, I'm {{name}}!
```

--------------------------------

### Specify Tool Import Paths

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Use the --tool-path flag to specify additional directories where runprompt should search for tool modules. Multiple paths can be provided.

```bash
./runprompt --tool-path ./my_tools --tool-path /shared/tools prompt.prompt
```

--------------------------------

### Use Builtin Fetch Tool

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Utilize a built-in tool like 'fetch_clean' directly in the prompt. This tool fetches a URL and returns a lightweight version of the page.

```yaml
---
model: anthropic/claude-sonnet-4-20250514
tools:
  - builtin.fetch_clean
---
Please summarize this page: {{ARGS}}
```

--------------------------------

### Running a Basic Prompt from Bash

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Execute a prompt file using standard input piped from a file.

```bash
cat article.txt | ./runprompt summarize.prompt
```

--------------------------------

### Executing a Prompt with Command Line Arguments

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Run a prompt file and pass arguments directly on the command line.

```bash
./runprompt process.prompt Hello world, please summarize this text.
```

--------------------------------

### Run .prompt file with arguments

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Execute the runprompt script with a .prompt file and pass data as a JSON string argument. Ensure your ANTHROPIC_API_KEY is exported.

```bash
export ANTHROPIC_API_KEY="your-key"
./runprompt hello.prompt '{"name": "World"}'
```

--------------------------------

### Define Shell Tools with Options

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Configure shell tools with additional options like 'safe' for auto-approval and a 'description' for LLM clarity. The 'cmd' field is required.

```yaml
shell_tools:
  git_log:
    cmd: git log --oneline
    safe: true
    description: Show recent git commits
  search_code:
    cmd: grep -r
    safe: true
    description: Search for text in files
```

--------------------------------

### Basic Prompt with STDIN

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Use the {{STDIN}} variable to pass raw standard input to the prompt. This is useful for summarizing text files.

```yaml
---
model: anthropic/claude-sonnet-4-20250514
---
Summarize this text: {{STDIN}}
```

--------------------------------

### Run .prompt file with STDIN

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Alternatively, pass data to the runprompt script via standard input (STDIN) as a JSON string.

```bash
echo '{"name": "World"}' | ./runprompt hello.prompt
```

--------------------------------

### Inline Prompt Execution

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Run a prompt template directly from the command line using the -p flag without creating a .prompt file. Requires specifying the model and providing template variables as a JSON string.

```bash
./runprompt -p "Say hello to {{name}}" --model openai/gpt-4o '{"name": "World"}'
```

--------------------------------

### LLM Passing Arguments to Shell Tools

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Illustrates how an LLM can pass arguments and environment variables to defined shell tools. The 'args' parameter is appended to the command.

```text
git_log(args="--author=alice -n 5")
search_code(args="TODO", PATH="/src")
```

--------------------------------

### Parameterized Builtin Tool for Writing to File

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Create a specialized tool using a parameterized builtin like 'write_file' to securely write content to a specific file. The LLM provides content but not the path.

```yaml
---
model: anthropic/claude-sonnet-4-20250514
tools:
  - builtin.write_file('output.txt')
---
Write a haiku about coding to the file.
```

--------------------------------

### Attach Files via CLI

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Use the --read or --file flags to attach local files to the prompt context. Supports glob patterns.

```bash
./runprompt --read README.md --read "src/**/*.py" review.prompt
```

```bash
./runprompt --file README.md review.prompt
```

--------------------------------

### Prompt with Command Line Arguments

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Utilize the {{ARGS}} variable to access command-line arguments passed after the prompt file. These arguments are joined by spaces.

```yaml
---
model: anthropic/claude-sonnet-4-20250514
---
Process this: {{ARGS}}
```

--------------------------------

### Run Prompt with Safe Tools Auto-Approved

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Use the --safe-yes flag (or equivalent environment variable/config) to automatically approve safe tools. Tools not marked as safe will still require confirmation.

```bash
./runprompt --safe-yes weather.prompt
```

--------------------------------

### Pre-prompt Shell Commands for Dynamic Context

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Execute shell commands defined in the 'before' section of the frontmatter to gather dynamic context before the main prompt is processed. Outputs are available as individual variables and a combined {{BEFORE}} variable.

```yaml
---
model: anthropic/claude-sonnet-4-20250514
before:
  latest_commit: git log -1 --oneline
  current_date: date
  file_count: find . -name "*.py" | wc -l
---
Latest commit: {{latest_commit}}
Current date: {{current_date}}
Python files: {{file_count}}
```

--------------------------------

### Reference Tools in Frontmatter

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Reference tools in the prompt's frontmatter using Python import syntax. Supports importing all functions from a module or specific functions.

```yaml
---
model: anthropic/claude-sonnet-4-20250514
tools:
  - my_tools.*
---
What's the weather in Tokyo and what's 15% of 847?
```

--------------------------------

### Setting Custom Endpoint via Legacy Environment Variables

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Runprompt also supports legacy environment variables for setting the base URL, including OLLAMA_BASE_URL, OPENAI_BASE_URL, OPENAI_API_BASE, and BASE_URL.

```bash
export OLLAMA_BASE_URL="http://localhost:11434/v1"
export OPENAI_BASE_URL="http://localhost:11434/v1"
export OPENAI_API_BASE="http://localhost:11434/v1"  # OpenAI SDK v0.x style
export BASE_URL="http://localhost:11434/v1"
```

--------------------------------

### Attach Files via Frontmatter

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Specify local files or globs in the frontmatter 'files:' section to include them in the prompt context. Supports template variables for dynamic file paths.

```yaml
---
model: anthropic/claude-sonnet-4-20250514
files:
  - README.md
  - src/**/*.py
---
Review these files and suggest improvements.
```

```yaml
---
model: anthropic/claude-sonnet-4-20250514
before:
  changed_files: git diff --name-only HEAD~1
files:
  - "{{changed_files}}"
---
Review the recently changed files.
```

--------------------------------

### Setting Custom Endpoint via Environment Variable

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Configure Runprompt to use a custom OpenAI-compatible endpoint, such as Ollama, by setting the RUNPROMPT_BASE_URL environment variable.

```bash
export RUNPROMPT_BASE_URL="http://localhost:11434/v1"
```

--------------------------------

### Executing Prompt for Structured Data Extraction

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Run a prompt designed to extract structured data, piping input text to it.

```bash
echo "John is a 30 year old teacher" | ./runprompt extract.prompt
```

--------------------------------

### Setting Custom Endpoint via CLI Flag

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Use the --base-url CLI flag to specify a custom OpenAI-compatible endpoint for Runprompt.

```bash
./runprompt --base-url http://localhost:11434/v1 hello.prompt
```

--------------------------------

### Enable Caching with Environment Variable

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Enable caching across a pipeline of commands by setting the RUNPROMPT_CACHE environment variable to 1. This is useful for sequential prompt processing.

```bash
export RUNPROMPT_CACHE=1; echo "..." | ./runprompt a.prompt | ./runprompt b.prompt
```

--------------------------------

### Passing Template Variables as JSON Argument

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Provide template variables for a prompt by passing a JSON string as a direct argument after the prompt file.

```bash
./runprompt hello.prompt '{"name": "Alice"}'
```

--------------------------------

### Chaining Prompts for Data Processing

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Pipe the JSON output of one prompt as input to another prompt. This allows for multi-step data processing and generation workflows.

```bash
echo "John is 30" | ./runprompt extract.prompt | ./runprompt generate-bio.prompt
```

--------------------------------

### Define Simple Shell Tools Inline

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Define simple shell script tools directly within your prompt configuration. This is useful for quick, single-line commands.

```yaml
---
model: anthropic/claude-sonnet-4-20250514
shell_tools:
  git_status: git status --short
  count_py_files: find . -name "*.py" | wc -l
---
What's the current git status and how many Python files are there?
```

--------------------------------

### Structured JSON Output Extraction

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Define an output schema in the prompt frontmatter to extract structured data (JSON) from the LLM's response. The input schema can also be defined to parse stdin.

```yaml
---
model: anthropic/claude-sonnet-4-20250514
input:
  schema:
    text: string
output:
  format: json
  schema:
    name?: string, the person's name
    age?: number, the person's age
    occupation?: string, the person's job
---
Extract info from: {{text}}
```

--------------------------------

### Enable Caching with CLI Flag

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Enable response caching for a specific command by using the --cache flag. Subsequent runs with identical inputs will utilize the cached response.

```bash
./runprompt --cache hello.prompt

# Second run with same input uses cached response
./runprompt --cache hello.prompt
```

--------------------------------

### Enabling Verbose Mode via CLI Flag

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Enable verbose mode in Runprompt using the -v flag to view request and response details during execution.

```bash
./runprompt -v hello.prompt
```

--------------------------------

### Passing Template Variables via STDIN

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Provide template variables for a prompt by piping a JSON string to standard input.

```bash
echo '{"name": "Alice"}' | ./runprompt hello.prompt
```

--------------------------------

### Overriding Model from CLI

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Override the model specified in the prompt's frontmatter by providing the --model flag on the command line.

```bash
./runprompt --model anthropic/claude-haiku-4-20250514 hello.prompt
```

--------------------------------

### Exclude Helper Functions from Tool Imports

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Use an underscore prefix for helper functions in Python files to exclude them from wildcard imports, ensuring they are not exposed as LLM tools.

```python
# _helpers.py - this entire file is excluded from wildcard imports
# my_tools.py
def _private_helper():  # excluded from wildcard imports
    """Internal helper function."""
    pass

def public_tool():  # included in wildcard imports
    """A tool available to the LLM."""
    pass
```

--------------------------------

### Referencing Template Variables in Shell Commands

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Use template variables defined in the frontmatter as environment variables within the 'before' shell commands. This allows dynamic command execution based on prompt context.

```yaml
---
model: anthropic/claude-sonnet-4-20250514
before:
  model_info: echo "Using model: ${model}"
---
{{model_info}}
```

--------------------------------

### Save Raw API Responses

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Use the --save-response flag to save the entire raw API envelope, including token usage and model details, to a specified file.

```bash
./runprompt --save-response api_out.json hello.prompt
```

--------------------------------

### Tool Parameter Type Hint Mapping

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Type hints in Python tool functions map to JSON Schema types for parameter validation. Un-typed parameters default to 'string'.

```markdown
| Python | JSON Schema |
|--------|-------------|
| `str`  | `string`    |
| `int`  | `integer`   |
| `float`| `number`    |
| `bool` | `boolean`   |
| `list` | `array`     |
| `dict` | `object`    |
```

--------------------------------

### Mark Tools as Safe

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Mark Python tool functions as 'safe' by setting a `safe = True` attribute. Safe tools can run without confirmation when using specific CLI flags or environment variables.

```python
# my_tools.py
def get_weather(city: str):
    """Gets the current weather for a city (read-only operation)."""
    return {"temp": 72, "conditions": "sunny"}

get_weather.safe = True  # Mark as safe

def delete_file(path: str):
    """Deletes a file from the filesystem."""
    os.remove(path)
    return "deleted"

# Not marked as safe - will always prompt for confirmation
```

--------------------------------

### Overriding Output Format from CLI

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Override nested frontmatter values, such as the output format, using dot notation on the command line.

```bash
./runprompt --output.format json extract.prompt
```

--------------------------------

### Clear the Cache Directory

Source: https://github.com/chr15m/runprompt/blob/main/README.md

Remove all cached responses by executing the --clear-cache command. This is useful for freeing up disk space or ensuring fresh responses.

```bash
./runprompt --clear-cache
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.