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.

tb portkill   # find and terminate listeners by port
tb envdiff    # compare .env files without revealing values
tb jwtdecode  # inspect JWTs locally without a third-party site
tb envswitch  # activate named .env profiles safely
tb 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

• Windows, macOS, or Linux
• No Go installation is required when using a prebuilt release
• Go 1.24 or newer only when installing from source

Install

Package manager (recommended)

On Windows with Scoop:

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

On macOS with Homebrew:

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

Package-manager installs place tb on PATH and can be upgraded with scoop update terminalbase or brew upgrade --cask terminalbase.

Prebuilt release

Download the archive for your operating system and CPU from the latest release:

terminalbase_VERSION_windows_amd64.zip
terminalbase_VERSION_windows_arm64.zip
terminalbase_VERSION_darwin_amd64.tar.gz
terminalbase_VERSION_darwin_arm64.tar.gz
terminalbase_VERSION_linux_amd64.tar.gz
terminalbase_VERSION_linux_arm64.tar.gz

Each archive contains tb (or tb.exe on Windows), the README, and the MIT license. The release also provides checksums.txt for SHA-256 verification.

On Windows, extract the ZIP and place tb.exe in a directory on your user PATH. For example:

$installDir = "$env:LOCALAPPDATA\Programs\TerminalBase"
New-Item -ItemType Directory -Force $installDir | Out-Null
Copy-Item .\tb.exe (Join-Path $installDir "tb.exe")

$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if (($userPath -split ";") -notcontains $installDir) {
    $newPath = if ([string]::IsNullOrWhiteSpace($userPath)) {
        $installDir
    } else {
        "$userPath;$installDir"
    }
    [Environment]::SetEnvironmentVariable("Path", $newPath, "User")
}

Open a new PowerShell window after updating PATH.

On macOS or Linux, extract the archive and install the executable:

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

Then verify the installation:

tb --version
tb --help

Install from source

Developers with Go 1.24 or newer can install the latest tagged version:

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

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

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 tb <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.

tb portkill 3000
tb portkill 3000 8080 --force
tb 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.

tb envdiff .env .env.example
tb envdiff .env .env.staging .env.production
tb 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.

tb jwtdecode eyJhbGciOi...
tb jwtdecode --file token.txt

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

Get-Clipboard | tb jwtdecode

pbpaste | tb jwtdecode       # macOS
cat token.txt | tb 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

tb envswitch --list
tb envswitch staging
tb envswitch production --dry-run
tb 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

tb nuke --dry-run
tb nuke
tb nuke --force
tb nuke --install
tb 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/...
goreleaser check
goreleaser release --snapshot --clean

Build a local branded executable on Windows:

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

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.

Pushing a version tag such as v0.3.0 runs tests and vet before GoReleaser creates the GitHub Release, six platform archives, and checksums.txt.

License

TerminalBase is available under the MIT License.