toolbox-cli

A zero-dependency, cross-platform CLI for checking, diagnosing, and standardizing local developer environments.

toolbox scans installed tools, detects project stacks, runs setup diagnostics, manages common development ports, inventories installed packages, applies shared toolbox.json setup files, and exports JSON reports — all from a single binary with no runtime dependencies.

---

Highlights

• Cross-platform — first-class support for Windows, macOS, and Linux
• Project detection — Node.js, Rust, Tauri, Python, Bun, Deno, Go, Java, .NET, Docker
• Doctor mode — surfaces missing tools, broken PATH, missing toolchains, with optional auto-fix
• Guided install wizard — winget / brew / apt / curl per platform
• Config-driven setup — a single toolbox.json describes your project's expected stack
• Package inventory — npm, pnpm, Yarn, Cargo, pip, winget, Chocolatey, Scoop, Homebrew, plus PATH-visible binaries
• Dev port toolkit — list, watch, free up common ports like 3000, 5173, 5432, 6379, 8080
• Interactive shell — Claude Code-style command palette with /-prefixed commands, ↑↓ navigation, scrolling overflow
• Machine-readable reports — toolbox report writes a full environment snapshot to toolbox-report.json
• Zero runtime dependencies — uses only Node.js built-ins

---

Installation

From npm (global)

npm install -g toolbox-cli
toolbox help

From source

git clone https://github.com/Sushankthatipally/toolbox_cli.git
cd toolbox_cli
npm install -g .
toolbox help

Without installing globally

git clone https://github.com/Sushankthatipally/toolbox_cli.git
cd toolbox_cli
node ./bin/toolbox.js help

Requirements

• Node.js 16 or later
• Git (only for cloning the repository)

---

Quick start

toolbox            # open the interactive shell (recommended)
toolbox scan       # one-shot scan of every detected tool
toolbox detect     # detect project type in the current folder
toolbox doctor     # diagnose missing tools / PATH issues
toolbox ports      # show which dev ports are free vs. in use
toolbox packages   # full installed-package inventory
toolbox report     # export toolbox-report.json

Inside the interactive shell, type / to open the command palette, use ↑/↓ to navigate, Enter to run, Esc to clear, Ctrl+C to quit.

---

Commands

Command	Description
toolbox	Open the interactive command palette
toolbox help	Show all available commands
toolbox scan	Scan installed tools, versions, and executable paths
toolbox detect	Detect the project stack in the current directory
toolbox doctor	Diagnose environment issues
toolbox doctor --fix	Diagnose and offer interactive auto-fixes
toolbox install	Guided install wizard for supported tools
toolbox init	Generate a starter toolbox.json from the detected project
toolbox apply	Install everything declared in toolbox.json
toolbox packages	Full package and command inventory
toolbox packages --summary	Compact package counts by category
toolbox packages --category <name>	Show one category (npm, pnpm, yarn, cargo, pip, winget, choco, scoop, brew, path)
toolbox packages --search <term>	Filter packages by name, source, version, or path
toolbox packages --all	Full inventory including all PATH binaries
toolbox ports	Show common dev ports — in use vs. free
toolbox ports --used	Only occupied dev ports
toolbox ports --free	Only free dev ports
toolbox ports --json	JSON output (CI-friendly)
toolbox ports watch	Live monitor — press Ctrl+C to stop
toolbox ports kill <port>	Kill the process holding a port (with confirmation)
toolbox report	Export a full JSON snapshot to toolbox-report.json

Both toolbox scan and toolbox /scan work. Commands are case-insensitive on the CLI.

---

Interactive shell

Running toolbox with no arguments opens an interactive Claude Code-style palette:

  ╭────────────────────────────────────────────────────────────╮
  │ ✻ Welcome to toolbox  v1.1                                 │
  │                                                            │
  │ Type  /  to open the command palette                       │
  │ Use   ↑↓ to navigate, Enter to run, /exit to quit          │
  │                                                            │
  │ cwd     ~/projects/my-app                                  │
  │ project node                                               │
  ╰────────────────────────────────────────────────────────────╯

  ❯ /

  ▸ /scan                  Scan all tools — version, path, status
    /detect                Detect project type from current folder
    /doctor                Diagnose environment issues
    /install               Guided install wizard for any tool
    /packages              Full package inventory
    /ports                 Show port usage — in use vs free
    ↓ 8 more below

    ↑↓ navigate · Enter run · Esc clear · Ctrl+C quit

The palette scrolls when matches exceed the visible window and uses the alternate screen buffer, so the menu never pollutes your scrollback. Both /scan and bare scan are accepted as input.

---

Supported tools

toolbox scan detects versions and paths for:

• VCS: Git
• Node.js stack: Node.js, npm, pnpm, Yarn, Bun
• Rust stack: rustc, Cargo, rustup, Tauri CLI
• Python: Python, pip
• Other languages: Go, Java/javac, .NET SDK, Deno
• DevOps: Docker, kubectl
• Package managers: winget, Chocolatey, Scoop, Homebrew
• Editors / shells / utilities: VS Code, PowerShell, curl

---

Package inventory

toolbox packages inspects package managers, project dependencies, global tools, package runners, and visible PATH commands.

Categories:

• npm — globally installed npm packages
• npm-project — dependencies of the current project (when package.json is present)
• pnpm — globally installed pnpm packages
• yarn — globally installed Yarn packages
• cargo — globally installed Cargo crates
• pip — globally installed pip packages
• winget / choco / scoop / brew — OS-level package managers
• path — executables visible on PATH, grouped by source (npm-global-bin, cargo-bin, python scripts, winget-linked, other)

Each entry can include the package name, version, install path, binary path, and source hint.

---

Dev port toolkit

toolbox ports helps find and free common development ports such as 3000, 5173, 5432, 6379, 8000, 8080, 9229, 27017, and many more.

toolbox ports                  # full status table
toolbox ports --used           # only what's occupied
toolbox ports --free           # only what's available
toolbox ports --json           # JSON output for CI / scripting
toolbox ports watch            # live refresh every 3 seconds
toolbox ports kill 3000        # kill the process on :3000 (confirms first)

Process names resolve via tasklist on Windows and ss / lsof on Linux / macOS.

---

Configuration

toolbox reads configuration from either:

• toolbox.json
• .toolbox.json

Generate a starter from the detected project:

toolbox init

Example:

{
  "project": "tauri-desktop-app",
  "tools": [
    { "name": "git" },
    { "name": "node" },
    { "name": "npm" },
    { "name": "rustc" },
    { "name": "cargo" },
    { "name": "tauri-cli", "scope": "project" }
  ],
  "packages": {
    "npm": ["@tauri-apps/cli"],
    "cargo": []
  },
  "env": {
    "autoPath": true
  }
}

Apply the configuration:

toolbox apply

---

Reports

toolbox report

Writes toolbox-report.json containing:

• Detected project types and evidence
• Versions, paths, and status of every supported tool
• Diagnostic issues with suggested fixes
• Full package inventory across every supported source
• ISO timestamp and platform

Useful for issue reports, CI artefacts, environment audits, or comparing two machines.

---

Development

git clone https://github.com/Sushankthatipally/toolbox_cli.git
cd toolbox_cli
npm install
npm run check        # syntax-check both modules
node ./bin/toolbox.js scan

The codebase is two files: src/index.mjs (CLI + commands) and src/ports.mjs (port toolkit). Both rely only on Node.js built-ins.

---

Contributing

Pull requests are welcome! For larger changes, please open an issue first to discuss the direction.

Helpful starting points:

• Add a tool — extend TOOL_DEFS in src/index.mjs with version, path, and per-platform install specs
• Add a project type — extend detectProject with the file evidence and recommended tools
• Improve the interactive shell — see promptSlashCommandLive and buildInteractiveShellDynamic in src/index.mjs
• Add a package source — implement a getInstalled<Source>Packages() collector and wire it into collectPackageInventory

Please run npm run check before opening a PR.

---

License

MIT © Sushank Thatipelly