blackhole-cli

An animated black hole in your terminal, powered by vgpu. Each ▄ displays two vertical pixels with independent foreground/background colors. The effect fills the terminal. Arrow keys orbit the camera; any other key quits.

npx blackhole-cli

Requirements

• Node.js 22.15 or newer.
• macOS with Metal, or a recent glibc-based Linux distribution, on arm64/x64.
• An ANSI terminal and a font containing ▄. Truecolor and xterm-256 are supported.
• Linux needs the Vulkan loader and DRM runtime libraries. On Debian/Ubuntu: sudo apt-get install libvulkan1 libdrm2. The CLI does not run system package managers.

The Linux release test uses Debian 13. Older distributions may have a glibc version incompatible with the native WebGPU binding; Alpine/musl is unsupported. CPU-only rendering is supported on Linux; macOS requires a usable Metal GPU.

GPU and CPU rendering

Startup first tries vgpu/node with automatic adapter selection. A working GPU or installed software renderer is used immediately. If Linux has no usable adapter, the CLI announces a one-time download of vgpu's portable Mesa CPU renderer, verifies it using vgpu's pinned checksums, and retries on the CPU. The download requires network access and is cached for later runs. No sudo is needed for this download; it does not install system libraries.

The cache lives under VGPU_CACHE_DIR, XDG_CACHE_HOME, or ~/.cache, in that order. You can disable the automatic software download or require a GPU:

npx blackhole-cli --no-software-download
npx blackhole-cli --adapter hardware
npx blackhole-cli --adapter software

The download opt-out applies to the CPU renderer. npm and vgpu may still fetch native Node bindings during initial installation/startup. Once dependencies and native bindings are provisioned, the effect needs no network connection.

For diagnostics or manual setup:

npx [email protected] doctor
npx [email protected] install-software-renderer

Options

npx blackhole-cli --help
npx blackhole-cli --samples 4 --fps 20  # Reduce CPU/GPU cost
npx blackhole-cli --samples 64         # More edge antialiasing
npx blackhole-cli --colors truecolor
npx blackhole-cli --colors 256
npx blackhole-cli --cell-aspect 0.4    # For cells such as 8×20 pixels
npx blackhole-cli --layout hero       # Original off-center composition
npx blackhole-cli --headless --frames 60 --output output/capture

The default centers the black hole with a 50° vertical field of view while preserving its tilt. The disk renders on a black background, without stars or bloom. Arrow keys orbit in 3° steps and regenerate the ray bake when needed. The default is 16 samples per pixel and a 30 FPS cap. Terminal dimensions and font metrics determine resolution and aspect ratio. Resize to change the viewport; smaller fonts provide more pixels. The bottom-left hint reads Use arrows to rotate, with Made with vgpu.sh aligned to the bottom-right. Both use white letters on black and replace only their own cells. In narrow terminals the hint moves up one row to avoid overlap.

Headless captures include settings/timings, ANSI, SVG, text, and raw GPU PNGs. The PNGs contain the image; ANSI, SVG and text also include the attribution.

Development and releases

From the repository root:

pnpm --filter blackhole-cli... install --frozen-lockfile
pnpm black-hole
pnpm --filter blackhole-cli... check
pnpm --filter blackhole-cli pack:release
pnpm --filter blackhole-cli test:package

Packing copies the shared terminal writer into dist/; no unpublished workspace package is needed at runtime. Native bindings remain platform-resolved npm dependencies. Only runtime code, WGSL shaders, source attribution, README and licenses are shipped.

Rendering notes · Release checks

The shader is adapted from vgpu's MIT-licensed Optimized Black Hole example. Its source provenance and license are included in the package.