$ curl -fsSL https://bun.com/install | bash
On the other hand, an equivalent install.md file might read something like this:
Install bun for me.
Detect my OS and CPU architecture, then download the appropriate bun binary zip from GitHub releases (oven-sh/bun). Use the baseline build if my CPU doesn't support AVX2. For Linux, use the musl build if I'm on Alpine. If I'm on an Intel Mac running under Rosetta, get the ARM version instead.
Extract the zip to ~/.bun/bin, make the binary executable, and clean up the temp files.
Update my shell config (.zshrc, .bashrc, .bash_profile, or fish http://config.fish depending on my shell) to export BUN_INSTALL=~/.bun and add the bin directory to my PATH. Use the correct syntax for my shell.
Try to install shell completions. Tell me what to run to reload my shell config.
It's much shorter and written in english and as a user I know at a glance what the author is trying to do. In contrast with install.sh, install.md makes it easy for the user to audit the intentions of the programmer.
The obvious rebuttal to this is that if you don't trust the programmer, you shouldn't be installing their software in the first place. That is, of course, true, but I think it misses the point: that coding agents can act as a sort of runtime for prose and as a user the loss in determinism and efficiency that this implies is more than made up for by the gain in transparency.
Shell scripts can be audited. The average user may not do it due to laziness and/or ignorance, but it is perfectly doable.
On the other hand, how do you make sure your LLM, a non-deterministic black box, will not misinterpret the instructions in some freak accident?
Instead of asking the agent to execute it for you, you ask the agent to write an install.sh based on the install.md?
Then you can both audit whatever you want before running or not.
Good idea. That seems sensible.
Bonus: LLM is only used once, not every time anyone wants to install some software. With some risks of having to regenerate, because the output was nonsensical.
I think the point was that install.md is a good way to generate an install.sh.
> validate that, and put it into the repo
The problem being discussed is that the user of the script needs to validate it. It's great if it's validated by the author, but that's already the situation we're in.
The user is free to use a LLM to 'validate' the `install.sh` file. Just asking it if the script does anything 'bad'. That should be similarly successful as the LLM generating the script based on a description. Maybe even more successful.
It's already made a bunch of tasks that used to be time-consuming to automate much easier for me. I'm still learning where it does and doesn't work well. But it's early days.
You can tell something is a genuinely interesting new idea when someone posts about it on X and then:
1. There are multiple launches on HN based on the idea within a week, including this one.
2. It inspires a lot of discussion on X, here and elsewhere - including many polarized and negative takes.
Hats off for starting a (small but pretty interesting) movement.
Any script can be shortened by hiding commands in other commands.
LLMs run parameters in the billions.
Lines of code, as usual, is an incredibly poor metric to go by here.
That is why we have programming languages, they, coupled with a specific interpreter/compiler, are pretty clear on what they do. If someone misunderstands some specific code segment, they can just test their assumptions easily.
You cannot do that with just written prose, you would need to ask the writer of that prose to clarify.
And with programming languages, the context is contained, and clearly stated, otherwise it couldn't be executed. Even undefined behavior is part of that, if you use the same interpreter/compiler.
Also humans often just read something wrong, or skip important parts. That is why we have computers.
Now, I wouldn't trust a LLM to execute prose any better then I trust a random human of reading some how-to guide and doing that.
The whole idea that we now add more documentation to our source code projects, so that dumb AI can make sense of it, is interesting... Maybe generally useful for humans as well... But I would instead target humans, not LLMs. If the LLMs finds it useful as well, great. But I wouldn't try to 'optimize' my instructions so that every LLM doesn't just fall flat on its face. That seems like a futile effort.
I've never actually (knowingly) run Bun before, but decided to give it a try - below is my terminal session to get it running (on macOS):
$ nix-shell -p bun
[nix-shell:~]$ bun
Bun is a fast JavaScript runtime, package manager, bundler, and test
runner. (1.3.5+1e86cebd7)
Usage: bun <command> [...flags] [...args]
Commands:
run ./my-script.ts Execute a file with Bun
lint Run a package.json script
... (rest of output trimmed)...
- What the agent is told to do in prose
- How the agent interprets those instructions with the particular weights/contexts/temperature at the moment.
I’m all for the prose idea, but wouldn’t want to trade determinism for it. Shell scripts can be statically analyzed. And also reviewed. Wouldn’t a better interaction be to use an LLM to audit the shell script, then hash the content?
I hear you, and I can see the pragmatism of your approach. I’m just not convinced that it’s better.
Neither of those things is actually true
People that got their home dir removed by AI agent did not ask for their home dir being removed by AI
(I have my own answer to this but I'd like to hear yours first!)
Install scripts are a simple example that current generation LLMs are more than capable of executing correctly with a reasonably descriptive prompt.
More generally, though, there's something fascinating about the idea that the way you describe a program can _be_ the program that tbh I haven't fully wrapped my head around, but it's not crazy to think that in time more and more software will be exchanged by passing prompts around rather than compiled code.
One follow-up thought I had was... It may actually be... more difficult(?) to go from a program to a great description
https://hn.algolia.com/?dateRange=all&page=0&prefix=true&que...
https://hn.algolia.com/?dateRange=all&page=0&prefix=true&que...
What Naur meant by "theory" was the mental model of the original programmers who understood why they wrote it that way. He argued the real program was is theory, not the code. The translation of the theory into code is lossy: you can't reconstruct the former from the latter. Naur said that this explains why software teams don't do as well when they lose access to the original programmers, because they were the only ones with the theory.
If we take "a great description" to mean a writeup of the thinking behind the program, i.e. the theory, then your comment is in keeping with Naur: you can go one way (theory to code) but not the other (code to theory).
The big question is whether/how LLMs might change this equation.
And natural languages are open to interpretation and a lot of context will remain unmentioned. While programming languages, together with their tested environment, contain the whole context.
Instrumenting LLMs will also mean, doing a lot of prompt engineering, which on one hand might make the instructions clearer (for the human reader as well), but on the other will likely not transfer as much theory behind why each decision was made. Instead, it will likely focus on copy&pasta guides, that don't require much understanding on why something is done.
LLMs don't have a "mental model" of anything.
(Note the words "if" and "by Naur's theory".)
It is much easier to use LLMs to generate code, validate that code as a developer, fix it, if necessary, and check it into the repo, then if every user has to send prompts to LLMs in order to get the code they can actually execute.
While hoping it doesn't break their system and does what they wanted from it.
Also... that just doesn't scale. How much power would we need, if everyday computing starts with a BIOS sending prompts to LLMs in order to generate a operating system it can use.
Even if it is just about installing stuff... We have CI runners, that constantly install software often on every build. How would they scale if they need LLMs to generate install instructions every time?
The install.sh is auditable, yes you need to know bash to be able to audit it, but the same is true for an LLM, it could hallucinate random commands that delete files or override other applications/configs.
I used minimax M2 (context it's very unreliable) for installation and it didn't work and my document folder is missing, help
how do you even debug this? imagine you some path or behaviour is changed in new os release and model thinks it knows better? if anything goes wrong who is responsible?
Pretty brilliant in a way.
The post mentioned Pete Koomen's install.md idea as an example use case. So now with this launch you can try it with a real intstallation script!
I think it's a really interesting idea worth experimentation and exploration. So it's a positive thing to see Mintlify launch this, and that it's already on Firecrawl.dev's docs!
We can all learn from it.
Show HN discussion of executable markdown here:
https://news.ycombinator.com/item?id=46549444
The claude-run tool lets you execute files like this autonomously if you want to experiment with it.
curl -fsSL https://docs.firecrawl.dev/install.md | claude-run --permission-mode bypassPermissions
https://github.com/andisearch/claude-switcher
This is still a very early-stage idea, but I'm really stoked to see this today. For anyone interested in experimenting with it, it's a good idea to try in a sandboxed environment.
I like the notion of having install.md be the thing that is referenced in Prompt to Install on the web.
Edit: forgot my link https://dontoisme.github.io/ai/developer-tools/ux/2025/12/27...
I’m not sure this solution is needed with frontier models.
Instead, have your LLMs write inputs to those tools. It's an easier task for them anyway and they only have to do it once, then you just run it
1. IaC gives you Idempotent solutions- which is advantageous over an agent. What if the agent crashes half way through deployment procedures? How will you reliably resume an interrupted install?
2. IaC gives you reproducible builds
3. IaC gives you ability to install tools in a way that can be tested for compliance with any deployment standards you have
W/r/t frontier models:
Just tell them to go install stuff. They already have so much in their training corpus that you literally do not need to create this.
7b-14b parameter self hosted models may get some benefit from your approach. I find self hosted is less reliable for tasteful approaches. Micromanagement yields better results.
Once you accept that installation will be automated, standardized formats make a lot of sense. Big q is will this particular format, which seems solid, get adopted - probably mostly a timing question
Writing a truly comprehensive install.sh script is comparatively inane, for starters, you immediately take out windows compatibility.
As expected, engineers (inc me.) will be reluctant to add non determinism to a solution that doesn't need it. Having deeper thinking traces/ logit debugging could help alleviate the concern.
Sorry but what the heck?
We should NOT standardize irresponsible behavior, in particular for repeatable tasks. This is particularly maddening when solutions like dependency resolution, containers, distribution of self-contained and binaries DO exist.
I understand that the hype machine must feed on yet another idea to keep its momentum but this is just ridiculous.
That way we can have entire projects with nothing but Markdown files. And we can run apps with just `claude run app.md`. Who needs silly code anyway?
Wouldn't that be nice?
If you like install.md, you might love Rundown!
I've made a Rundown version of an install here: https://rundown.cool/explore/install/
Jokes aside, this seems like a really wierd thing to leave to agents; I'm sure its definitely useful but how exactly is this more secure, a bad actor could just prompt inject claude (an issue I'm not sure can ever be fixed with our current model of LLMs).
And surely this is significantly slower than a script, claude can take 10-20 seconds to check the node version; if not longer with human approval for each command, a script could do that in miliseconds.
Sure it could help it work on more environments, but stuff is pretty well standardised and we have containers.
I think this part in the FAQ wraps it up neatly:
""" What about security? Isn't this just curl | bash with extra steps? This is a fair concern. A few things make install.md different:
Human-readable by design. Users can review the instructions before execution. Unlike obfuscated scripts, the intent is clear.
Step-by-step approval. LLMs in agentic contexts can be configured to request approval before running commands. Users see each action and can reject it.
No hidden behavior. install.md describes outcomes in natural language. Malicious intent is harder to hide than in a shell script.
So it is just curl with extra steps; scripts aren't obfuscated, you can read them; if they are obfuscated then they aren't going to use a Install.md and you (the user) should really think thrice before installing.
Step by step approval also sorta betrays the inital bit about leaving installing stuff to ai and wasting time reading instructions.
Malicious intent is harder to hide, but really if you have any doubt in your mind about an authors potential malefeasance you shouldn't be running it, wrapping claude around this doesn't make it any safer really when possible exploits and malware are likely baked into the software you are trying to install, not the install.
tldr; why not just have @grok is this script safe?
Ten more glorious years to installer.sh
I personally think that prose is significantly easier to read than complex bash and there are at least some benefits to it. They may not outweigh the cons, but it's interesting to at least consider.
That said, this is a proposal and something we plan to iterate on. Generating install.sh scripts instead of markdown is something we're at least thinking about.
But I DON'T think the standard should start by piping the prompt directly into claude/model cli. I say this as someone who has seen, first hand, an exfiltration attack locally and almost fell for it after 20 years as a developer.
Even if initially the install.md is safe, install prompt scripts and the things they download aren't packaged and static. They're all surfaces to exploit. The sub-components can be changed between any install, this is true unless we image versions and cache the "safe" imaged version and approve it.
What would be safer to me is a hub that you give a single install script that creates "images", .e.g. DMG for a Mac, .exe for Windows, etc., for platforms. That may actually be an installer app that the User or Agent opens then finishes locally for configuration. Then you point your Agent to that hub.
Nevertheless, then I would just recall XKCD and say, why not just package it with NPM, PyPi, brew, etc.
llms.txt makes sense as a standard but this is unnecessary.
Since the article has been changed to tone down its provocative opener, which clearly had a kicking-the-anthill effect, I'm moving those original reactions to this subthread.
This is such an insane statement. Is this satire?
I think the subtext here is actually revealing a deeper issue. Installing software sucks. It’s error prone and every project does it a slightly different way. What we need is standardization, and I can see why prose could be an attractive middle ground. Easier to understand but less precise may result in marginally better outcomes.
I’m concerned that this approach serves to fix the obvious problems while simultaneously introducing subtler problems.
Tangentially, I’ve been thinking about this a lot lately. There are projects like nix that are excellent at fixing a lot of problems in the software packaging and installation space that are great from a security perspective but are famously difficult to use. I’d personally like to see more work leveraging AI to increase the accessibility of these paradigms and not throw the bathwater out with the baby, so to speak.
What?? How do I get off of this train? I used to come to hacker news for a reason...what the fuck am I reading
> How does install.md work with my existing CLI or scripts?
> install.md doesn't replace your existing tools—it works with them. Your install.md can instruct the LLM to run your CLI, execute your scripts, or follow your existing setup process. Think of it as a layer that guides the LLM to use whatever tools you've already built.
(It doesn't X — it Ys. Think of it as a Z that Ws. this is LLM speak! I don't know why they lean on these constructions to the exclusion of all else, but they demonstrably do. The repo README was also committed by Claude Code. As much as I like some of the code that Claude produces, its Readmes suck)
Any other feedback you have about the general idea?
If the installer was going to succeed in a particular environment anyway, you definitely want to use that instead of an LLM that might sporadically fail for no good reason in that same environment.
If the installer fails then you have a "knowledge base" to help debug it, usable by humans or LLMs, and if it fails, well, the regular installer failed too, so hopefully you're not worse off. If the user runs the helper LLM in yolo mode then the consequences are on them.
I think I agree with you on it needing to assist in event of failure instead of jumping straight to install though. Will think more about that.
> Installing software is a task which should be left to AI.
Absolutely I don't think so. This is a very bad idea.
$ curl | bash was bad enough. But $ curl -fsSL | claude looks even worse.
What could possibly go wrong?
I wouldn't use it for anything serious, but that being said, I think it's in better shape than when I was running it.
Most of the largest trends in "how to deploy software" revolve around making things predictable and consistent. The idea of abandoning this in favor of making a LLM do the work seems absurd. At least the bash script can be replicated exactly across machines and will do the same thing in the same situation.
That is such a wild thing to say. Unless this whole thing is satire...
Does that make any sense or am I just off my rocker?
An LLM will run the probabilistically likely command each time. This is like using Excel’s ridiculous feature to have a cell be populated by copilot rather than having the AI generate a deterministic formula.
How we've all been blue-pilled. Sigh..
(If LLMs can follow it, so be it, but at least humans remain the target audience.)
This is a "solution" looking for a problem.
What pushed me over the edge was actually feeding bash install scripts into agents and seeing them not perform well. It does work, but a lot worse than this install.md thing.
In the docs for the proposal I wrote the following:
>install.md files are direct commands, not just documentation. The format is structured to trigger immediate autonomous execution.[1]
"Please don't post shallow dismissals, especially of other people's work. A good critical comment teaches us something."
"Don't be curmudgeonly. Thoughtful criticism is fine, but please don't be rigidly or generically negative."
So, after teaching people to outsource their reasoning to an LLM, LLMs are now actively coaching folks to use LLMs for tasks for which it makes no sense at all.