diff --git a/README.md b/README.md
index 666ab78..ffe83eb 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,18 @@ transfers.
 - A CLI (`groups`, `balances <group>`, `export <group>`) alongside the web
   page and API.
 
+## Run it
+
+```sh
+bun install
+bun run dev                      # serves http://localhost:3200 (set PORT to change it)
+bun run src/cli.ts groups        # list groups
+bun run src/cli.ts balances goa-trip
+```
+
+Both seed demo data into `splitbill.sqlite` on first run; set
+`SPLITBILL_DB` to use a different database file.
+
 ## Stack
 
 Bun, TypeScript, Hono, `bun:sqlite`. No build step for the web page
diff --git a/tests/readme.test.ts b/tests/readme.test.ts
new file mode 100644
index 0000000..72c4f05
--- /dev/null
+++ b/tests/readme.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const root = join(import.meta.dir, "..");
+
+function runItSection(): string {
+  const readme = readFileSync(join(root, "README.md"), "utf8");
+  const start = readme.indexOf("## Run it");
+  expect(start).toBeGreaterThanOrEqual(0);
+  const next = readme.indexOf("\n## ", start + 1);
+  return next === -1 ? readme.slice(start) : readme.slice(start, next);
+}
+
+describe("README Run it section", () => {
+  test("Run it section lists bun install", () => {
+    expect(runItSection()).toContain("bun install");
+  });
+
+  test("Run it section lists bun run dev and http://localhost:3200", () => {
+    const section = runItSection();
+    expect(section).toContain("bun run dev");
+    expect(section).toContain("http://localhost:3200");
+  });
+
+  test("Run it section has a CLI example", () => {
+    expect(runItSection()).toContain("bun run src/cli.ts groups");
+  });
+
+  test("README CLI example runs", () => {
+    const proc = Bun.spawnSync(["bun", "run", "src/cli.ts", "groups"], {
+      cwd: root,
+      env: { ...process.env, SPLITBILL_DB: ":memory:" },
+    });
+    expect(proc.exitCode).toBe(0);
+    expect(proc.stdout.toString()).toContain("goa-trip");
+  });
+});