devx

Local developer platform CLI for macOS — register microservices, get stable HTTPS hostnames, and manage processes from the terminal or a TUI.

Why devx?

• One manifest (devx.yaml) describes your services; devx sync updates Caddy and the local registry.
• HTTPS by default — https://auth.api.localhost style URLs via Caddy and a local CA.
• Port allocation — typed port ranges so services do not collide.
• devx dev — Ink TUI to start/stop services and tail logs.

Quick start

Prerequisites: macOS, Homebrew, Bun (to build from source).

bun install && bun run build

devx setup
devx trust-ca

cd /path/to/your-service
devx onboard

devx dev

Open the HTTPS URL shown in the TUI or devx list.

Documentation

Full user guide: docs/user-guide.md

Topics covered there:

• Installing and building devx
• devx.yaml manifest format
• All commands (setup, onboard, sync, start, stop, dev, …)
• Hostnames, ports, and HTTPS
• Troubleshooting SSL and empty HTTP pages

Example manifest: docs/examples/devx.yaml

Commands

devx setup | trust-ca | onboard | sync | new-service
devx list | start | stop | remove | dev

Run devx --help for a short summary.

Development

bun install
bun test
bun run lint
bun run build    # → dist/devx

See AGENTS.md for architecture and conventions (contributors).

Releasing

Versions and CHANGELOG.md are updated automatically on push to main via semantic-release (same approach as j26-cli). Successful releases publish @jalmquist/devx to npm. Use Conventional Commits (feat:, fix:, feat!: for breaking changes).

Details: docs/releasing.md (includes NPM_TOKEN / trusted publishing setup)

Git

This repository uses main as the default branch. CI runs on push and pull requests (see .github/workflows/ci.yml). Releases run in .github/workflows/release.yml.

git add .
git commit -m "Initial commit"
git remote add origin [email protected]:johanalmquist/devx.git
git push -u origin main

Replace the remote URL with your hosting provider. The compiled binary under dist/ is not committed; build it locally or in release automation.

Acknowledgments

devx is inspired by j26-cli — particularly its service manifest, local HTTPS via Caddy, and trust-ca workflow. devx adapts those ideas for a native (non-Docker) macOS control plane: per-service hostnames, port allocation, process lifecycle, and the devx dev TUI.

Thank you to the j26-cli authors and contributors for paving the way.

License

MIT — see LICENSE.