Get started
Supported systems
What bassclef runs on today. macOS is verified. Linux runs in CI under Docker on Debian 12. Direct Linux hosts, arm64, other distros, and WSL 2 are untested. Windows PowerShell native is not supported — use WSL 2.
Bassclef is a bash framework. Node 20+ and npm 10+ are required on every system.
| System | process.platform | Status | What that means |
|---|---|---|---|
| macOS 13 or later | darwin | 🟢 verified | Primary dev platform. Each release is smoke-tested locally on a fresh macOS profile. Not in CI. |
| Linux via Docker (Debian 12 slim, amd64) | linux | 🟢 tested in CI | Every PR touching src/, harness/, or scripts/smoke-* runs a full npm install -g @thebassclef/lite + bassclef init cycle in a fresh container. See every run's pass/fail status: docker-smoke runs. |
| Linux direct host install (no Docker) | linux | 🟡 untested | Should work. No smoke has run outside Docker. First adopter: open an issue. |
| Linux arm64 native | linux | 🟡 untested | The Docker image pins linux/amd64. Arm64 hosts run under Rosetta. No native arm64 smoke. |
| Other Linux distros (Alpine, RHEL, Fedora, Arch) | linux | 🟡 untested | Debian 12 glibc is the pinned smoke target. Other distros are unverified. |
| Windows via WSL 2 | linux | 🟡 unverified | No CI. No operator report. First WSL adopter: open an issue. |
| Windows PowerShell native | win32 | 🔴 not supported | Framework hooks are bash scripts. Use WSL 2 instead. |
The @thebassclef/lite npm package pins "os": ["darwin", "linux"] starting with 1.2.0. Windows PowerShell installs fail at npm install with EBADPLATFORM, which is the intended signal.
Known limitations
Cross-system coverage is Phase 1 of sunj-labs/bassclef-cli#151. Still open:
- Audit framework bash for BSD vs GNU coreutils portability (tracked internally as a follow-on)
- Extend CI smoke beyond Debian 12 amd64 — arm64, Alpine (musl), RHEL family (Phase 3 of #151)
- Consider Windows PowerShell coverage based on adopter signal (Phase 4 of #151)
Found a system-specific bug?
Open an issue on sunj-labs/bassclef-cli. Name the OS, Node version, and command that failed.