TerminalBase

Five recurring developer chores. One local-first CLI.

TerminalBase (tb) handles the small terminal jobs developers repeatedly solve with copied shell commands or online tools: freeing a port, comparing environment files, inspecting a JWT, switching environment profiles, and cleaning a Node project.

$ tb portkill 3000 --dry-run
PID    NAME      PORTS  COMMAND
23908  node.exe  3000   node .../start-server.js
Dry run: no processes were terminated.

It is distributed as a single cross-platform binary, sends no telemetry, and does not upload your files or tokens.

What can tb do?

Command	Purpose	Safe default
tb portkill	Find and terminate processes listening on local ports	Shows the process and asks before terminating
tb envdiff	Compare two or more .env files	Prints key names, never values
tb jwtdecode	Decode JWT headers, payloads, and timestamps	Runs locally and always warns that the signature is unverified
tb envswitch	Activate a named .env profile	Refuses to overwrite an unrecognized .env
tb nuke	Remove generated Node dependency and cache directories	Uses a fixed allowlist and asks before deleting

Why TerminalBase?

• Local-first: JWTs and environment files stay on your machine.
• Safe by default: destructive commands confirm first and support dry runs.
• One small binary: no runtime, account, daemon, or configuration required.
• Cross-platform: Windows, macOS, and Linux on AMD64 and ARM64.
• Script-friendly: predictable output and documented exit codes.

Install

No Go installation is required unless you choose to build from source.

Windows — Scoop

scoop bucket add terminalbase https://github.com/Syedkaif29/scoop-terminalbase
scoop install terminalbase

Upgrade later with:

scoop update terminalbase

macOS or Linux — Homebrew

brew tap Syedkaif29/terminalbase
brew install --cask Syedkaif29/terminalbase/terminalbase

Upgrade later with:

brew upgrade --cask terminalbase

Prebuilt binary

Download the archive for your operating system and CPU from the latest release. Every release includes Windows, macOS, and Linux builds for AMD64 and ARM64, plus a checksums.txt file for SHA-256 verification.

On macOS or Linux, extract the archive and place tb on PATH:

sudo install -m 0755 tb /usr/local/bin/tb

On Windows, extract tb.exe into a directory already on your user PATH.

From source

With Go 1.24 or newer installed:

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

Make sure Go's binary directory is on PATH: %USERPROFILE%\go\bin on Windows or $HOME/go/bin on macOS and Linux.

Verify any installation with:

tb --version
tb --help

Quick tour

Free a development port

See exactly which process owns a TCP port before doing anything:

tb portkill 3000 --dry-run

Terminate it after one y/N confirmation:

tb portkill 3000

Multiple ports, UDP inspection, and non-interactive operation are supported:

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

portkill displays the PID, process name, command line, and matching ports. A port with no listener is a successful no-op.

Compare environment files without exposing secrets

tb envdiff .env .env.example
tb envdiff .env .env.staging .env.production

Default output reports missing key names only. To detect whether shared values differ without printing those values:

tb envdiff .env .env.example --values

Printing actual values requires the deliberate double opt-in below. Avoid it in shared terminals, screenshots, and CI logs.

tb envdiff .env .env.example --values --show-values

Decode a JWT without pasting it into a website

For sensitive tokens, use stdin or a file so the token does not enter shell history:

Get-Clipboard | tb jwtdecode

cat token.txt | tb jwtdecode
tb jwtdecode --file token.txt

jwtdecode pretty-prints the header and payload, renders numeric iat, nbf, and exp claims as UTC timestamps, and reports whether the token is valid, expired, not yet valid, or missing an expiry.

Important

Decoding is not verification. TerminalBase does not verify the JWT signature, issuer, audience, or trust chain.

Switch between .env profiles safely

Keep named profiles beside your project:

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

Then list or activate them:

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

TerminalBase copies .env.<profile> to .env transactionally and never prints profile values. If the current .env does not match any available profile, the command refuses to overwrite it. Save the changes as a profile, or use --force only when replacement is intentional.

Clean generated Node project directories

Preview the cleanup first:

tb nuke --dry-run

Then clean after confirmation, or explicitly reinstall dependencies:

tb nuke
tb nuke --install
tb nuke ../web-app --manager pnpm --install

Only these direct children of the selected project can be removed:

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

nuke requires a package.json. It never deletes lockfiles, source files, global caches, or nested workspace packages. It detects npm, Yarn, or pnpm from the lockfile and packageManager field; conflicting lockfiles require an explicit --manager choice.

Privacy and safety

TerminalBase itself makes no runtime network requests and collects no telemetry. The only network-capable path is tb nuke --install, which explicitly launches your installed package manager and may contact its configured registry.

Safety boundaries are part of each command rather than optional configuration:

• portkill resolves processes with native APIs and confirms before termination.
• envdiff hides values unless both value flags are supplied.
• jwtdecode accepts at most 1 MiB and performs no JWKS lookup.
• envswitch validates profile names and uses rollback-safe replacement.
• nuke stays inside one project root and uses a fixed deletion allowlist.

Standalone commands

Prefer the branded tb command to avoid global name collisions. Developers who want individual wrappers can install them from source; they use the same tested implementations as the corresponding tb subcommands.

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

Shell completion

Cobra-generated completion is available for Bash, Zsh, Fish, and PowerShell:

tb completion --help
tb completion bash > tb-completion.bash

Follow the shell-specific instructions shown by tb completion <shell> --help.

Exit codes

Code	Meaning
0	Success, no-op, cancellation, or nothing to report
1	Environment difference, safety refusal, or operational failure
2	Invalid usage, malformed input, or configuration error

Contributing

Bug reports, documentation improvements, portability fixes, tests, and focused new command ideas are welcome. Please open an issue before starting a large behavior change so the design can be discussed first.

To work on TerminalBase locally:

git clone https://github.com/Syedkaif29/terminalbase.git
cd terminalbase
go test ./...
go vet ./...
go build ./cmd/...

Before submitting a pull request:

go fmt ./...
go mod tidy
go test ./...
go vet ./...

The project uses injectable process, filesystem, clock, prompt, and subprocess boundaries so tests run without terminating real processes, exposing secrets, or launching package-manager installs.

Release integrity

GitHub Actions tests and vets the project on Windows, macOS, and Linux. Tagged releases are built with GoReleaser and publish six platform archives plus checksums.txt. Scoop and Homebrew installations are smoke-tested against the published packages.

See CHANGELOG.md for release history.

License

TerminalBase is available under the MIT License.

If TerminalBase saves you time, consider starring the repository. It helps other developers discover the project.