README
¶
env-starter
env-starter starts your local dev stack in the right order and tells you when it's actually ready.
Most local stacks come with a startup ritual: start the database, wait until it accepts connections, run the migrations, start the auth service, wait again, then start the app. A handful of terminal tabs, from memory, every morning.
env-starter replaces the ritual with a YAML file. Describe each command once —
what it runs, what it depends on, and how to tell when it's ready — then start
the whole stack with one keystroke. Each command waits for its dependencies to
be healthy, not for a hopeful sleep. The ordering and the waiting stop being
your job.
Demo
A database service (Postgres) starts, and a migrate task runs once it
accepts connections — the exact config below, runnable as-is. One press of
s.
A minimal example
env-starter:
commands:
- name: database
type: service
source:
local: ./docs/examples/database
run: docker compose up
teardown: docker compose down
readiness:
tcp: "localhost:5432"
timeout: 60s
- name: migrate
type: task
source:
local: ./docs/examples/migrate
run: ./migrate.sh up
environments:
- name: my-app
workflow:
- command: database
- command: migrate
depends-on: [database]
env-starter run my-app && echo "ready"
Here migrate runs only once Postgres accepts connections. Commands can also
be pulled from a github repo or a url with checksum verification, and a
shared team config can be overlaid with personal overrides — the
configuration reference has the full schema. This
config is also the one behind the demo above; see
docs/examples/demo.yaml for the runnable version
— it needs Docker running and a free port 5432.
How it works
A background daemon owns the environments and their processes; the TUI and the
CLI are thin clients talking to it over a local unix socket. Close the TUI (or
detach with Ctrl+D) and everything keeps running — reopen it from any
terminal, or from several at once, and you see the same state. Commands come in
two kinds: services stay up and are probed for readiness (tcp for a port
accepting connections, shell for a command exiting 0), tasks run to
completion; both can declare a teardown. Every command's output streams live
in the TUI and is teed to a log file for post-mortem reading.
Nothing runs behind your back: env-starter allow lists every command a config
would execute, with a browsable link to its source, and asks for your approval
before anything starts.
Get started
brew install adericbourg/tap/env-starter
brew trust --tap adericbourg/tap/env-starter
env-starter allow # review and approve your config's commands (first run only)
env-starter
Prebuilt binaries, go install, and building from source are covered in
Installation.
Documentation
- Installation & updating
- Usage — the daemon, CLI commands, and TUI keys
- Configuration reference — every YAML field
- Shell completion
- Releasing
Contributing
See CONTRIBUTING.md for build, test, and Git hooks setup.
License
GPL-3.0 — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
env-starter
command
Command env-starter is a text-based meta-launcher that starts a named environment's commands in dependency order, waiting for each dependency to be healthy before starting its dependents.
|
Command env-starter is a text-based meta-launcher that starts a named environment's commands in dependency order, waiting for each dependency to be healthy before starting its dependents. |
|
internal
|
|
|
daemon
Package daemon — client-side controller over a Unix socket connection to the daemon.
|
Package daemon — client-side controller over a Unix socket connection to the daemon. |
|
engine
Package engine is the orchestration core of env-starter: a foreground supervisor that starts and stops environments made of globally-shared commands, respecting the dependency graph declared in each environment's workflow.
|
Package engine is the orchestration core of env-starter: a foreground supervisor that starts and stops environments made of globally-shared commands, respecting the dependency graph declared in each environment's workflow. |
|
fsutil
Package fsutil provides small filesystem helpers shared by the daemon, the source cache, and the log writer.
|
Package fsutil provides small filesystem helpers shared by the daemon, the source cache, and the log writer. |
|
httpsafe
Package httpsafe provides the shared HTTP transport policy for everything env-starter downloads and later executes (url sources, self-update artifacts): every redirect hop must stay on https — a redirect must never downgrade an https request to plaintext http — and redirect chains are bounded.
|
Package httpsafe provides the shared HTTP transport policy for everything env-starter downloads and later executes (url sources, self-update artifacts): every redirect hop must stay on https — a redirect must never downgrade an https request to plaintext http — and redirect chains are bounded. |
|
linkscan
Package linkscan extracts http/https URLs from log lines, associating each URL with the command that produced it.
|
Package linkscan extracts http/https URLs from log lines, associating each URL with the command that produced it. |
|
logbuf
Package logbuf captures a command's output: it keeps the last N lines in memory for a live TUI view and optionally tees raw bytes to a file.
|
Package logbuf captures a command's output: it keeps the last N lines in memory for a live TUI view and optionally tees raw bytes to a file. |
|
openfile
Package openfile provides a cross-platform helper to open a file using the operating system's default application.
|
Package openfile provides a cross-platform helper to open a file using the operating system's default application. |
|
probe
Package probe provides readiness probes used to decide when a started command is "healthy".
|
Package probe provides readiness probes used to decide when a started command is "healthy". |
|
source
Package source provides implementations of the Source interface that fetch a working directory from a local path, a GitHub repository, or a URL.
|
Package source provides implementations of the Source interface that fetch a working directory from a local path, a GitHub repository, or a URL. |
|
termsafe
Package termsafe neutralizes terminal control sequences in untrusted text.
|
Package termsafe neutralizes terminal control sequences in untrusted text. |
|
trust
Package trust implements a trust-on-first-use (TOFU) approval gate for env-starter config files.
|
Package trust implements a trust-on-first-use (TOFU) approval gate for env-starter config files. |
|
tui
Package tui provides a Bubble Tea terminal UI over the orchestration engine.
|
Package tui provides a Bubble Tea terminal UI over the orchestration engine. |
|
update
Package update checks for and applies new releases of env-starter from GitHub Releases.
|
Package update checks for and applies new releases of env-starter from GitHub Releases. |