One-Line Installer Patterns

When this pattern is the right tool

A curl … | bash install script is the right answer in a narrow set of cases. Outside that set, simpler distribution mechanisms exist and should be used.

Use this pattern when:

• The project is multi-language (Python + Node + Docker) and uv tool install cannot do the job alone
• The project requires system prerequisites that must be detected and clearly directed (Docker, Node via fnm/volta, jq, etc.)
• The intended audience is non-technical and cannot be expected to run more than one command
• The "real" install is docker compose up, but the user needs a clean way to land the compose file, generate an .env, and start the stack

Don't use this pattern when:

• The project is a Python CLI → use uv tool install git+... and see cli-packaging-patterns
• The project is a Node CLI → publish to npm, document npx <tool> or pnpm dlx <tool>
• The project produces a single static binary → ship via GitHub releases, document curl -L .../tool -o ~/.local/bin/tool && chmod +x ~/.local/bin/tool. This is the modern Go/Rust default.
• The project is a pure containerized app → ship a docker-compose.yml. The "install command" is docker compose up -d. Plausible, n8n, and Outline all do this.

A curl | bash script is a thin wrapper around one of the four real distribution mechanisms above. It is not its own distribution mechanism.

The security trade-off, stated honestly

Piping a remote script to a shell executes whatever the server returns at the moment of invocation. The user has no opportunity to inspect what runs. The trust model is roughly equivalent to running any other unverified binary from the internet — not worse, but not better.

There is also a documented attack class: a malicious server can detect a curl | bash invocation by stalling the response and serve different content than it would to a curl > install.sh && less install.sh inspection. See https://www.idontplaydarts.com/2016/04/detecting-curl-pipe-bash-server-side/ — this is real and demonstrated, not theoretical.

Required mitigations:

• Serve over HTTPS only. Reject http://.
• Host the script in the same git repo as the code it installs, so the script is reviewable in version control.
• Document the review-first variant alongside the one-liner. Treat the one-liner as the lazy path, not the only path.
• Pin a version (git tag or release ref) in the URL when possible, instead of chasing main.
• For sensitive deployments, ship signed releases (cosign or GPG) and have the script verify signatures before extracting any artifact.

What this pattern cannot give you:

• Strong supply-chain guarantees. If the host is compromised, every install is compromised. There is no offline review.
• Reproducibility across time. The script the user sees today may not be the script they see tomorrow. Version-pin or accept the drift.

The community convention for the one-liner

curl -fsSL https://example.com/install.sh | bash

This shape is used by rustup, bun, deno, fly, ollama, pnpm, supabase, and most others. Conform to it.

• curl -fsSL: fail on HTTP error (-f), silent progress (-s), show errors (-S), follow redirects (-L)
• | bash — not | sh. Almost no production installer is strict POSIX sh. Bash 3.2 (the macOS default) is the realistic floor. Documenting | bash is honest about what the script actually requires.

For arguments, use the rustup convention:

curl -fsSL https://.../install.sh | bash -s -- --version 1.2.3 --no-modify-path

The bash -s -- form is broadly understood and supported.

For the review-first variant, document this prominently in the README — not as a footnote:

curl -fsSL https://.../install.sh -o install.sh
less install.sh
bash install.sh

What the installer should do, in order

1. set -euo pipefail; trap cleanup EXIT
2. Detect: OS, arch, libc (glibc vs musl), shell, existing install

…