CLI
staghorn and stag are the same command once @coralogix/staghorn is installed. Without it installed, run npx @coralogix/staghorn, never npx staghorn or npx stag.
staghorn -- <command> run a dev server behind its own hostname
staghorn list [--json] show the dev servers that are live
staghorn url [--json] print this checkout's hostname
staghorn status [--json] show the shared daemon
staghorn stop stop the shared daemon
staghorn prune drop routes whose process is gone
staghorn doctor diagnose this machine
staghorn config --print show the resolved config and where each value came from
--service <name> which dev server in this checkout (app, storybook, ...)
--allocate choose the port instead of discovering it
--quiet no banner
--help, --versionstaghorn -- <command>
Runs your command unchanged, learns its port, registers the route, prints the banner and holds a lease for as long as it lives.
Everything after -- is your command, verbatim. Staghorn does not parse it, rewrite it, or inject flags into it.
staghorn -- npm run dev
staghorn --service storybook -- npm run storybook
staghorn --allocate -- node server.jsThe exit code is your command's exit code. If Staghorn itself cannot do its job it degrades a rung and warns; it does not change the outcome of what it wrapped.
staghorn list
The live dev servers, by host, port and branch. Routes whose process is gone are filtered out at read time rather than shown as stale.
staghorn url
This checkout's hostname, without starting anything. No daemon, no route registered, no lease taken - it is a query, not a claim, so it is safe from a script that is still deciding what to do.
staghorn status
The shared daemon: its pid, port, protocol version, and how many routes and leases it currently holds. The lease count is the interesting one, because it is what decides when the daemon exits.
staghorn stop
Asks the daemon to shut down. Only a daemon that answers Staghorn's own control path is ever addressed; anything else on that port is left alone.
You rarely need this - the daemon exits on its own about five seconds after the last dev server. It exists for the deliberate "free that port now" case.
staghorn prune
Drops route files whose process is gone. Reads already filter on liveness, so this is housekeeping rather than a fix.
staghorn doctor
Diagnoses this machine: platform, node version, state directory, which rungs of the fallback ladder are available, and known environment problems such as a corporate proxy that would intercept *.localhost.
This is the first thing to run when something is wrong, and the first thing to paste into an issue.
staghorn config --print
The resolved configuration and the layer each value came from. Usually faster than reasoning about precedence by hand.
--json
Works on list, url, status and config, for scripting.