env-starter

module
v1.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 21, 2026 License: GPL-3.0

README

env-starter

A keyboard-driven terminal launcher that starts your whole dev stack, in the right order, with one keystroke.

Release CI

The problem

Getting a local dev environment running usually means a dozen terminal tabs and a memorized ritual: start the database, wait for it to accept connections, run the migrations, start the auth service, wait again, then start the frontend — and hope you didn't skip a step or start something too early. Do that daily, across several projects, and it's real friction before you've written a line of code.

The solution

env-starter replaces the ritual with a declarative YAML file. Describe your commands once — what they are, what they depend on, and how to tell when they're ready — and start the whole stack with a single keystroke. env-starter starts each command only after its dependencies are healthy, so the ordering and the waiting are no longer your job.

Demo

env-starter starting a dependency-ordered environment

The environment above declares two independent services — docker-web (an nginx container) and local-web (a local python3 HTTP server) — started in parallel, plus a greet task that only runs once both are healthy. All from pressing s once.

Example

env-starter:
  commands:
    - name: database
      type: service
      source:
        github:
          repo: acme/infra
          subdir: scripts/database
      run: docker compose up
      teardown: docker compose down
      readiness:
        tcp: "localhost:5432"
        timeout: 60s

    - name: migrate
      type: task
      source:
        local: /home/user/scripts/migrate
      run: ./migrate.sh up
      teardown: ./migrate.sh down

    - name: auth-gateway
      type: service
      source:
        url: https://releases.example.com/auth-gateway/bin
      run: ./bin
      readiness:
        shell: "curl -sf localhost:8080/health"

  environments:
    - name: my-app-environment
      workflow:
        - command: database
        - command: migrate
          depends-on: [database]
        - command: auth-gateway
          depends-on: [database]

env-starter run my-app-environment && echo "ready"

source accepts a github repo, a url (with an optional checksum), or a local path — see the configuration reference for the full schema. For a version you can actually run yourself — one service in Docker, one without, no repos to clone — see docs/examples/demo.yaml (it's what recorded the demo above). It needs a running Docker daemon, python3, curl, and free ports 8080/9000.

Features

  • Dependency-aware startup — commands start only after their declared dependencies pass a readiness probe.
  • Two command types — long-running services and run-to-completion tasks, each with an optional teardown.
  • Pluggable readiness probes — tcp (port accepts a connection) and shell (command exits 0).
  • Multiple source types — pull scripts or binaries from github, a url (with checksum verification), or a local path.
  • Config overlays — merge personal overrides on top of shared team config.
  • Background daemon — environments keep running after the TUI closes, and stay visible from any number of TUI or CLI instances.
  • Per-command logs — a live view in the TUI, plus a file tee for post-mortem inspection.

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

See Installation for prebuilt binaries, go install, and building from source.

Documentation

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
completion
config
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.