Intro

What crust is

Crust is effectively an inline JavaScript global-scope script runner in Bun, shell-flavoured. Every line you type runs in a Bun context where Pipeline, range, GET/POST, parallel, $ (Bun.$), and anything you registered in ~/.config/crust/init.ts are globals.

Shell commands and TypeScript lambdas are equal citizens. Both are stages on the same pipeline. You don’t pick one or the other — you mix them as needed.

The same pipeline can be expressed either at the shell line or as a .ts script run with bun — every feature in crust has a TypeScript-API equivalent. Use whichever surface fits the moment:

# 1. Load-test a health endpoint
range(0, 10000) | parallel 100 | GET :3000/health | expect 200 | stats

# 2. Smoke-test against fixtures on disk — read yields file CONTENTS
read fixtures/*.json | POST :3000/users | expect 201

# 3. Pure POSIX shell still works
ls -la | grep .ts | wc -l

# 4. SQL rows as a streaming source — assert fails on falsy OR empty
sql "select email from users limit 5" | assert (r => r.email.includes("@"))

# 5. A whole HTTP fixture on one line: JSON body, header, status assert
{"name": "Court"} | POST $BASE/api/buildings -H "authorization: Bearer $TOKEN" | expect 201

// The same pipelines as a .ts script — bun script.ts
// (or pasted into `bun repl`; crust's globals are auto-loaded
//  when the script imports from "crust").

// 1.
await range(0, 10000)
  .pipe(parallel(100, () => fetch("http://localhost:3000/health")))
  .pipe(expectStage(200))
  .to(stats());

// 2.
await readAll("fixtures/*.json")
  .pipe(POST("http://localhost:3000/users"))
  .pipe(expectStage(201))
  .collect();

// 3.
const errors = await glob("**/*.log")
  .pipe(async (p) => Bun.file(p).text())
  .pipe((t: string) => t.split("\n"))
  .filter((l: string) => l.includes("ERROR"))
  .collect();
console.log(errors.length);

// 4.
await Pipeline.of([])
  .pipe(() => Bun.sql`select email from users limit 5`)
  .pipe((r) => {
    if (!r.email.includes("@")) throw new Error("bad email");
    return r;
  })
  .collect();

// 5.
await Pipeline.of([{ name: "Court" }])
  .pipe(POST(`${process.env.BASE}/api/buildings`, {
    headers: { authorization: `Bearer ${process.env.TOKEN}` },
  }))
  .pipe(expectStage(201))
  .collect();

That first pipeline is a range source, then a parallel operator, then GET (HTTP verb), then expect and stats (sinks) — none of which are real binaries on your PATH, but all of which compose under | as if they were. The third line is pure POSIX shell. The fourth mixes a SQL row source with an assert predicate. The fifth is a complete HTTP fixture on one line — a JSON-literal body, an env-expanded auth header, a status assertion — the shorthand fixture grammar that test-pipes runs from .pipes files. Each form has the same observable behavior — pick the surface that fits where you’re working.

The mental model

Three roles, one stream type — Pipeline<T>:

The shell parser classifies each |-separated stage by looking at its first token:

Single-stage pure-shell lines (ls -la, git status) short-circuit: crust execs sh -c with inherited stdio so colors, paging, and TUIs work normally. Mixed pipelines stream items through TS land.

Why bash and TypeScript

Both languages are tools. Bash wins for launching processes and piping bytes. TypeScript wins for shaping data, awaiting promises, and asserting structure. Crust stops forcing you to pick:

• Use grep when you want grep. Don’t reinvent it.
• Use filter (l => …) when the predicate is awkward in awk — it drops non-matching items, with full TS in the predicate.
• Use a lambda when you need to parse JSON, await a fetch, or reshape items (a lambda maps; it never drops).
• Use HTTP verbs as first-class stages — no need to script curl invocations or shell out for assertions.

Install

Then run it whichever way fits the moment. Crust is not a login shell and doesn’t want to be one — your shell stays your shell; crust is the tool you reach for when the line involves streams, HTTP, fixtures, or load:

# 1. Interactive REPL — line editing, history, completions
crust

# 2. One-liner caller from bash/zsh/fish — for the lines where
#    pipeline syntax wins. -c loads your init.ts and exits with
#    the line's status. Multi-line strings split on \n.
crust -c 'range(0,99) | parallel 20 | GET :3000/health | expect 200 | stats'
crust -c 'ls *.json | (s => JSON.parse(await Bun.file(s).text())) | (j => j.id)'

# 3. Script files — same parser as the REPL, fail-fast, honest
#    exit codes. A #!/usr/bin/env crust shebang works, and so
#    does piping lines in on stdin.
crust deploy-checks.crust
echo 'range(1,3) | filter (n => n > 1)' | crust

# 4. crust globals available to any .ts file you run with bun
bun script.ts

// script.ts — runs under plain `bun script.ts`.
// The Pipeline / range / parallel / GET / POST / expectStage / stats
// / $ globals come from `crust` — explicit import keeps tooling happy.
import { Pipeline, range, parallel, GET, expectStage } from "crust";
import { stats } from "crust/sinks";

await range(0, 99)
  .pipe(parallel(20, () => fetch("http://localhost:3000/health")))
  .pipe(expectStage(200))
  .to(stats());

// Or with no imports inside the crust REPL — every name above
// is already on globalThis.

The TypeScript surface is identical between the REPL and a script — the difference is just where you’re typing. There is no feature that exists in the shell line but not in TS, or vice versa.

Next

• Quickstart — every command crust ships, shell-line + TS-API side by side.
• npm packages — globally-installed packages become pipeline stages automatically.
• DB drivers — pointing sql at Postgres, MySQL, SQLite.