klinex

klinex is a Bun-powered OpenTUI command surface for local developer services.

It brings your localhost stack into one warm, focused terminal view: discover what is listening, open browserable services, inspect the process behind a port, and stop what you no longer need without leaving the keyboard.

It scans local TCP listeners, ranks developer-relevant services first, probes browserable services over HTTP/HTTPS and infra services over TCP, and gives you safe stop controls directly from the terminal.

Features

• macOS and Linux support
• curated developer-services view with a toggle for all local TCP listeners
• detection for local web apps, APIs, databases, caches, emulators, queues, mail tools, search, and observability services
• fuzzy search across host, port, process, command, service type, and framework
• lightweight HTTP/HTTPS and TCP probing with title/status hints
• browser open for services with an HTTP UI
• stop actions for PID-only and process-tree modes
• permission-aware behavior with clear sudo guidance
• cyber-styled OpenTUI interface built on @opentui/core

Requirements

• Bun >= 1.3.3
• macOS or Linux

klinex is published through npm as @klinex/klinex, but the installed CLI command is still klinex.

Zero-Bun-install releases are also published as standalone binaries and through Homebrew.

Install

One-off usage:

bunx @klinex/klinex

With npm, if Bun is already installed:

npm i -g @klinex/klinex
klinex

Global install:

bun add -g @klinex/klinex

Run it with:

klinex

In other words: scoped package name, unscoped CLI command.

Zero-Bun-install options:

brew install klinex/tap/klinex
klinex

Direct binaries are also attached to GitHub Releases for macOS arm64 and Linux x64.

If you prefer a single line:

bun add -g @klinex/klinex
klinex

Local Development

bun install
bun run dev

Keybindings

• Enter: open the selected service in the default browser when it has an HTTP UI
• /: focus fuzzy filter
• Tab: switch focus between list and filter
• r: refresh now
• a: toggle curated developer services vs all listeners
• s: cycle sort mode
• x: open stop dialog
• q: quit

Stop dialog actions:

• TERM PID: graceful stop for only the selected PID
• KILL PID: force stop for only the selected PID
• TERM TREE: graceful stop for the PID and its children
• KILL TREE: force stop for the PID and its children

Permissions

When the current user cannot inspect or signal a process, klinex shows the listener but marks ownership as hidden.

If you need deeper inspection or stop controls for those listeners, relaunch the app with sudo.

Scripts

bun run check
bun run test
bun run build
bun run ci
bun run package:dry-run

bun run package:dry-run validates the package tarball without writing it to disk.

If you later want to validate the actual registry publish flow, run npm publish --dry-run --access public after authenticating with npm.

Standalone release binaries are built on native GitHub runners and smoke-tested with klinex --version before release assets are published.

Release

klinex is published to npm as the public package @klinex/klinex, and the executable it installs is klinex.

Tagged releases also publish:

• standalone binaries on GitHub Releases
• a Homebrew formula to klinex/homebrew-tap

Brand assets for repo and release surfaces live in assets/, including assets/social-card.svg for GitHub social preview and release artwork.

Manual Publish

1. Ensure you are logged into npm:

   npm whoami

2. Bump the version in package.json.
3. Run release checks:

   bun install
   bun run ci
   bun run package:dry-run
   npm publish --dry-run --access public

4. Publish:

   npm publish --access public

CI Publish

The recommended release path is GitHub Actions publishing from a semver tag.

1. Bump package.json to the intended release version.
2. Merge to main.
3. Create and push a matching tag:

   git tag v0.1.1
   git push origin v0.1.1

4. The release workflow validates the version, runs CI, publishes npm, builds native binaries, creates a GitHub Release, and updates the Homebrew tap.

Binary And Homebrew Install

GitHub Release assets are the zero-Bun-install path for supported targets.

Homebrew uses those release assets through the klinex/homebrew-tap tap:

brew install klinex/tap/klinex
klinex --version

Requirements

• package name: @klinex/klinex
• install target: npm registry
• runtime requirement: Bun for npm installs, none for standalone release binaries
• repo target: https://github.com/spencerjireh/klinex
• npm access to the @klinex/klinex package
• NPM_TOKEN configured in GitHub Actions for CI publishing
• HOMEBREW_TAP_TOKEN configured in GitHub Actions for updating klinex/homebrew-tap

License

MIT