I think you mentioned elsewhere that you dont want to have a lot of dependencies, but as the format evolves using the reference impl will allow you to work on real features.
This is really clever. Dotprompt as a thin, pipe-friendly layer around LLMs feels way more ergonomic than spinning up a whole agent stack. The single-file + stdlib approach is a nice touch too. How robust is the JSON schema enforcement when chaining multiple steps?
If the LLM returns invalid schema the next link in the chain will send that through since it defaults to string input if the JSON doesn't parse. Maybe I should make it error out in that situation.
Is including a json schema validator and running the output through the validator against the input prompt, such that you can detect when the output doesn't match the schema, and optionally retry until it does match (possibly with a max number of attempts before it throws an error) too complex of an idea for the target implementation concept you were envisioning?
It certainly doesn't intuitively sound like it matches the "Do one thing" part of the Unix philosophy, but it does seem to match the "and do it well" part.
That said, I can totally understand a counterargument which proposes that schema validation and processing logic should be something else that someone desiring reliability pipes the output into.
This is pretty cool. I like using snippets to run little scripts I have in the terminal (I use Alfred a lot on macOS). And right now I just manually do LLM requests in the scripts if needed, but I'd actually rather have a small library of prompts and then be able to pipe inputs and outputs between different scripts. This seems pretty perfect for that.
I wasn't aware of the whole ".prompt" format, but it makes a lot of sense.
Very neat. These are the kinds of tools I love to see. Functional and useful, not trying to be "the next big thing".
Can the base URL be overridden so I can point it at eg Ollama or any other OpenAI compatible endpoint? I’d love to use this with local LLMs, for the speed and privacy boost.
I've implemented this now. You can set it with BASE_URL or OPENAI_BASE_URL which seems to vaguely be the standard. I also plan to use this with local LLMs. Thanks for the suggestion!
I don't want to introduce a dependency. Simon's tool is great but I don't like the way it stores template state. I want my state in a file in my working folder.
llm stores data (prompts, responses, chats, fragments, aliases, attachment metadta) in a central sqlite database outside the working directory, and you have to use the tool to view and manipulate that data. I prefer a tool like this to default to storing things in a file or files in the project directory I'm working in, in a way that is legible e.g. plain text files. Contrast with e.g. git where everything goes into .git.
Functions require you to specify them on the command line every time they're invoked. I would prefer a tool like this to default to reading the functions from a hierarchy where it reads e.g. .llm-functions in the current folder, then ~/.config/llm-functions or something like that.
In general I found myself baffled when trying to figure out where and how to configure things. That's probably me being impatient but I have found other tools to have more straightforward setup and less indirection.
Basically I like things to be less centralized, magic, and less controlled by the tool.
Another thing, which is not the fault of llm at all, is I find Python based tools annoying to install. I have to remember the env where I set them up. Contrast with a golang application which is generally a single file I can put in ~/bin. That's the reason I don't want to introduce a dep to runprompt if I can avoid it.
The final thing that I found frustrating was the name 'llm' which makes it difficult to conduct searches as it is the generic name for what the thing is.
It is an amazing piece of engineering and I am a huge fan of simonw's work, but I don't use llm much for these reasons.
Interesting! Seems there is a very similar format by Microsoft called `.prompty`. Maybe I'll work on a PR to support either `.prompt` or `.prompty` files.
I've been using mlflow to store my prompts, but wanted something lightweight on the cli to version and manage prompts. I setup pmp so you can have different storage backends (file, sqlite, mlflow etc.).
I wasn't aware of dotprompt, I might build that in too.
Just like Linus being content with other people working on solutions to common problems, I’m so happy that you made this! I’ve had this idea for a long time but haven’t had the time to work on it.
It would be cool if there were some cache (invalidated by hand, potentially distributed across many users) so we could get consistent results while iterating on the later stages of the pipeline.
Yeah, if it's a novel prompt, by all means send it to the model, but if its the same prompt as 30s ago, just immediately give me the same response I got 30s ago.
That's typically how we expect bash pipelines to work, right?
Bash pipelines don't do any caching and will execute fresh each time, but I understand your idea and why a cache is useful when iterating on the command line. I'll implement it. Thanks!
Yeah sure but it breaks the flow that makes bash pipelines so fun:
- arrow up
- append a stage to the pipeline
- repeat until output is as desired
If you're gonna write to some named location and later read from it you're drifting towards a different mode of usage where you might as well write a python script.
Less typing. More control over chaining prompts together. Reproducibility. Running different prompts on different providers and models. Easy to install and runs everywhere. Inserts into scripting workflows simply. 12 factor env config.
Claude.md is an input to claude code which requires a monthly plan subscription north of 15€ / month. Same applies to Gemini.md, unless you are ok that they use your prompts for training Gemini. The python script works with a pay per use api key.
Looks like Google has packaged dotprompt into a Python library, might allow you to make the codebase leaner: https://github.com/google/dotprompt/tree/main/python/dotprom...
I think you mentioned elsewhere that you dont want to have a lot of dependencies, but as the format evolves using the reference impl will allow you to work on real features.
Will have a look at this. That could be the way to go. Thanks.
This is really clever. Dotprompt as a thin, pipe-friendly layer around LLMs feels way more ergonomic than spinning up a whole agent stack. The single-file + stdlib approach is a nice touch too. How robust is the JSON schema enforcement when chaining multiple steps?
If the LLM returns invalid schema the next link in the chain will send that through since it defaults to string input if the JSON doesn't parse. Maybe I should make it error out in that situation.
Is including a json schema validator and running the output through the validator against the input prompt, such that you can detect when the output doesn't match the schema, and optionally retry until it does match (possibly with a max number of attempts before it throws an error) too complex of an idea for the target implementation concept you were envisioning?
It certainly doesn't intuitively sound like it matches the "Do one thing" part of the Unix philosophy, but it does seem to match the "and do it well" part.
That said, I can totally understand a counterargument which proposes that schema validation and processing logic should be something else that someone desiring reliability pipes the output into.
I'm not sure. I think I need to use it more to see what the LLMs do with bad data. The design you're suggesting might be the answer though.
This is pretty cool. I like using snippets to run little scripts I have in the terminal (I use Alfred a lot on macOS). And right now I just manually do LLM requests in the scripts if needed, but I'd actually rather have a small library of prompts and then be able to pipe inputs and outputs between different scripts. This seems pretty perfect for that.
I wasn't aware of the whole ".prompt" format, but it makes a lot of sense.
Very neat. These are the kinds of tools I love to see. Functional and useful, not trying to be "the next big thing".
added some examples using runprompt in blog post:
"Chain Prompts Like Unix Tools with Dotprompt"
https://pythonic.ninja/blog/2025-11-27-dotprompt-unix-pipes/
Great article, thanks.
"One-liner code review from staged changes" - love this example.
Can the base URL be overridden so I can point it at eg Ollama or any other OpenAI compatible endpoint? I’d love to use this with local LLMs, for the speed and privacy boost.
I've implemented this now. You can set it with BASE_URL or OPENAI_BASE_URL which seems to vaguely be the standard. I also plan to use this with local LLMs. Thanks for the suggestion!
https://github.com/chr15m/runprompt/blob/main/runprompt#L9
seems like it would be, just swap the openai url here or add a new one
Good idea. Will figure out a way to do this.
simple solution: honor OPENAI_API_BASE env var
Perhaps instead of writing an llm abstraction layer, you could use a lightweight one, such as @simonw's llm.
I don't want to introduce a dependency. Simon's tool is great but I don't like the way it stores template state. I want my state in a file in my working folder.
Can you explain this decision a bit more? I’m using ‘llm’ and I find your project interesting.
llm stores data (prompts, responses, chats, fragments, aliases, attachment metadta) in a central sqlite database outside the working directory, and you have to use the tool to view and manipulate that data. I prefer a tool like this to default to storing things in a file or files in the project directory I'm working in, in a way that is legible e.g. plain text files. Contrast with e.g. git where everything goes into .git.
Functions require you to specify them on the command line every time they're invoked. I would prefer a tool like this to default to reading the functions from a hierarchy where it reads e.g. .llm-functions in the current folder, then ~/.config/llm-functions or something like that.
In general I found myself baffled when trying to figure out where and how to configure things. That's probably me being impatient but I have found other tools to have more straightforward setup and less indirection.
Basically I like things to be less centralized, magic, and less controlled by the tool.
Another thing, which is not the fault of llm at all, is I find Python based tools annoying to install. I have to remember the env where I set them up. Contrast with a golang application which is generally a single file I can put in ~/bin. That's the reason I don't want to introduce a dep to runprompt if I can avoid it.
The final thing that I found frustrating was the name 'llm' which makes it difficult to conduct searches as it is the generic name for what the thing is.
It is an amazing piece of engineering and I am a huge fan of simonw's work, but I don't use llm much for these reasons.
Everything seems to be about agents. Glad to see a post about enabling simple workflows!
Interesting! Seems there is a very similar format by Microsoft called `.prompty`. Maybe I'll work on a PR to support either `.prompt` or `.prompty` files.
https://microsoft.github.io/promptflow/how-to-guides/develop...
Oh interesting. Will investigate, thanks!
This is really cool and interesting timing, as I created something similar recently - https://github.com/julio-mcdulio/pmp
I've been using mlflow to store my prompts, but wanted something lightweight on the cli to version and manage prompts. I setup pmp so you can have different storage backends (file, sqlite, mlflow etc.).
I wasn't aware of dotprompt, I might build that in too.
Just like Linus being content with other people working on solutions to common problems, I’m so happy that you made this! I’ve had this idea for a long time but haven’t had the time to work on it.
It would be cool if there were some cache (invalidated by hand, potentially distributed across many users) so we could get consistent results while iterating on the later stages of the pipeline.
That’s a great idea. Store inputs/outputs in XDG_CACHE_DIR/runprompt.sqlite
Do you mean you want responses cached to e.g. a file based on the inputs?
Yeah, if it's a novel prompt, by all means send it to the model, but if its the same prompt as 30s ago, just immediately give me the same response I got 30s ago.
That's typically how we expect bash pipelines to work, right?
Bash pipelines don't do any caching and will execute fresh each time, but I understand your idea and why a cache is useful when iterating on the command line. I'll implement it. Thanks!
“tee” where you want to intercept and cat that file into later stages?
Yeah sure but it breaks the flow that makes bash pipelines so fun:
- arrow up
- append a stage to the pipeline
- repeat until output is as desired
If you're gonna write to some named location and later read from it you're drifting towards a different mode of usage where you might as well write a python script.
Can it be made to be directly executable with a shebang line?
/usr/local/bin/promptrun
hello.promptI added this and you can now make .prompt files with a runprompt shebang.
#/usr/bin/env runprompt
it already has one - https://github.com/chr15m/runprompt/blob/main/runprompt#L1
If you curl/wget a script, you still need to chmod +x it. Git doesn't have this issue as it retains the file metadata.
I'm assuming the intent was to as if the *.prompt files could have a shebang line.
Would be a lot nicer, as then you can just +x the prompt file itself.That's on my TODO list for tomorrow, thanks!
Seeing lots of good ideas in this thread. I am taking the liberty of adding them as GH issues
Fun! I love the idea of throwing LLM calls in a bash pipe
i literally vibe coded a tool like this. it supports image in, audio out, and archiving.
Cool, I'm going to add file modalities too. Thanks for the validation!
Ooof, I guess vibecoding is only as good as the vibecoder.
Why this over md files I already make and can be read by any agent CLI ( Claude, Gemini, codex, etc)?
Less typing. More control over chaining prompts together. Reproducibility. Running different prompts on different providers and models. Easy to install and runs everywhere. Inserts into scripting workflows simply. 12 factor env config.
Claude.md is an input to claude code which requires a monthly plan subscription north of 15€ / month. Same applies to Gemini.md, unless you are ok that they use your prompts for training Gemini. The python script works with a pay per use api key.
Do your markdown files have frontmatter configuration?
Thats pretty good, now lets see simonw's one...