Getting started

blink is built to need nothing on the first run and a small committed file once you want the setup to stick. This guide walks the path from a bare directory to a supervised blink.yml.

Zero-config run

Run blink in a project with no config file present.

blink            # same as `blink run`

blink scans the directory, detects what it can run (go, air, docker, node, python, rust, Procfile), and shows a checkbox of the services it found. Tick the ones you want and they run ephemerally. Nothing is written to disk, so this is a safe way to try a stack before committing to it.

Detection also makes a best-effort guess at the ports each service binds, reading .env files it finds, so the ephemeral run already reclaims stale ports where it can.

Write a config

Once the stack is worth keeping, write a config.

blink init                 # interactive picker, writes blink.yml
blink init -c blink.toml   # write TOML instead
blink init -f              # overwrite an existing file

init opens the same picker as a zero-config run, then saves your selection. The file extension you give -c picks the format, so .yml/.yaml, .toml, and .json all work and round-trip symmetrically. With no -c, init writes blink.yml.

In the picker, space selects a service, → edits one, a adds a service, f adds services from a sibling directory such as ../ui, p probes a service to discover the ports it actually binds, and enter saves.

Supervise the stack

With a config in place, run supervises every service in it.

blink run                  # supervise blink.yml with live reload
blink run -s web,api       # only start a subset of services
blink run -u plain         # line-prefixed stdout instead of the TUI
blink run -u headless      # no UI at all (alias: -u none)

run walks up from the current directory to find the config, so you can start the stack from any subdirectory. See Live reload for how file changes drive restarts, and Runtimes for what each runtime contributes.

Edit an existing config

edit reopens the picker over the services already in the config.

blink edit                 # edit the discovered config in place

Deselecting a service sets disabled: true rather than deleting it, so its configuration survives and re-selecting it brings it back. edit writes back in whatever format it loaded.

Reset blink's state

blink keeps per-project state (logs, build output) under a .blink/ directory, and user-scoped state under ~/.blink. nuke clears it.

blink nuke                 # remove project state (.blink dir + logs), confirms first
blink nuke -y              # skip the confirmation
blink nuke -g              # also remove user-scoped ~/.blink (shared across projects)

By default nuke touches only project-scoped state under the current directory and prints what it kept. See Paths and environment for where each directory lives and how to relocate it.