terminalbase

README

TerminalBase

TerminalBase is a local-first, cross-platform developer toolkit written in Go. It bundles five focused utilities behind one Cobra CLI while also providing standalone binaries for users who prefer short commands.

terminalbase portkill   # find and terminate listeners by port
terminalbase envdiff    # compare .env files without revealing values
terminalbase jwtdecode  # inspect JWTs locally without a third-party site
terminalbase envswitch  # activate named .env profiles safely
terminalbase nuke       # clean project-local Node dependency/cache directories

TerminalBase sends no telemetry and uploads no data. Commands are local-only by default. The sole network-capable path is the explicit nuke --install option, which launches your installed package manager and may contact its configured registry.

Requirements

• Go 1.24 or newer for go install
• Windows, macOS, or Linux

Install

Install the recommended all-in-one CLI:

go install github.com/Syedkaif29/terminalbase/cmd/terminalbase@latest

Ensure Go's binary directory is on PATH (%USERPROFILE%\go\bin on Windows or $HOME/go/bin on macOS/Linux), then run:

terminalbase --help
terminalbase --version

Optional standalone wrappers use the same implementations:

go install github.com/Syedkaif29/terminalbase/cmd/portkill@latest
go install github.com/Syedkaif29/terminalbase/cmd/envdiff@latest
go install github.com/Syedkaif29/terminalbase/cmd/jwtdecode@latest
go install github.com/Syedkaif29/terminalbase/cmd/envswitch@latest
go install github.com/Syedkaif29/terminalbase/cmd/nuke@latest

Every example below works either as terminalbase <command> ... or through its standalone wrapper.

portkill

Find the processes listening on one or more TCP ports, show their PID, name, command line, and matching ports, then ask before terminating them. Socket and process inspection uses gopsutil rather than shelling out to platform tools.

terminalbase portkill 3000
terminalbase portkill 3000 8080 --force
terminalbase portkill 5353 --udp --dry-run

--udp switches protocol, --dry-run never terminates, and --force skips the confirmation prompt. A port with no listener is informational and exits 0.

envdiff

Compare two or more .env-style files. Default output contains key names only; values are neither printed nor used for exit status.

terminalbase envdiff .env .env.example
terminalbase envdiff .env .env.staging .env.production
terminalbase envdiff .env .env.example --values

--values reports shared keys whose values differ without revealing either value. Actual values require the deliberate double opt-in --values --show-values; do not use that combination in shared logs or CI. Two files use missing-key sections, while three or more use a presence matrix.

jwtdecode

Decode a compact three-segment JWT entirely on your machine. TerminalBase pretty-prints the header and payload and renders numeric iat, nbf, and exp claims as UTC timestamps.

terminalbase jwtdecode eyJhbGciOi...
terminalbase jwtdecode --file token.txt

For sensitive tokens, prefer stdin so the token does not enter shell history:

Get-Clipboard | terminalbase jwtdecode

pbpaste | terminalbase jwtdecode       # macOS
cat token.txt | terminalbase jwtdecode # Linux/macOS

This command decodes only. It does not verify the JWT signature, issuer, audience, or trust chain, and it never contacts JWKS endpoints.

envswitch

Store named profiles beside a project and activate one by copying it to .env:

.env.local
.env.staging
.env.production

terminalbase envswitch --list
terminalbase envswitch staging
terminalbase envswitch production --dry-run
terminalbase envswitch local --dir ../another-project

The copy is transactional and receives private file permissions. If the current .env does not exactly match any available profile, TerminalBase refuses to overwrite it. Save those changes as a profile first, or use --force only when you intentionally want to replace them. Profile values are never printed.

nuke

Remove a fixed allowlist of generated directories from one Node project:

node_modules  .next  .nuxt  .svelte-kit  .turbo
.vite         .parcel-cache               coverage

terminalbase nuke --dry-run
terminalbase nuke
terminalbase nuke --force
terminalbase nuke --install
terminalbase nuke ../web-app --manager pnpm --install

By default, nuke only cleans after a y/N confirmation. It never deletes lockfiles, source files, global caches, or nested workspace packages. Reinstall is disabled unless --install is supplied; that flag may cause npm, yarn, or pnpm to access a package registry. Conflicting lockfiles are rejected unless --manager explicitly selects one.

Exit codes

• 0: success, no-op, cancellation, or nothing to report
• 1: detected env differences, safety refusal, or operational failure
• 2: invalid usage, malformed input, or configuration error

Development

gofmt -w .
go mod tidy
go test ./...
go vet ./...
go build ./cmd/...

Build a local branded executable on Windows:

New-Item -ItemType Directory -Force bin | Out-Null
go build -o .\bin\terminalbase.exe .\cmd\terminalbase

The test suite uses injected process, filesystem, clock, prompt, and subprocess boundaries. The only real process integration test opens an ephemeral loopback TCP listener and resolves it without terminating it.

License

TerminalBase is available under the MIT License.