GEX: Global & Local Dependency Auditing CLI

A production-ready tool for documenting and managing Node.js and Bun environments across projects and machines.

Overview

GEX solves a common friction point for JavaScript developers: losing track of dependencies when switching Node.js versions or machines. Instead of manually inventorying global CLIs and local packages before an environment migration, GEX generates structured, version-controlled reports of your entire dependency landscape—instantly.

Built as a focused CLI tool, it audits both npm and bun ecosystems, outputting machine-readable JSON for automation or human-friendly Markdown for documentation and handovers.

---

Key Features

• Dual Runtime Support: Seamlessly works with both Node.js/npm and Bun ecosystems
• Interactive Launcher: gex command provides a menu-driven interface to choose runtime and operation
• Multi-Format Output: JSON (default) for scripting, Markdown for documentation
• Global & Local Auditing: Report on globally installed packages or per-project dependencies
• Outdated Package Management: Built-in commands to check and update outdated dependencies
• Reproducible Reports: Deterministic output with sorted packages and stable timestamps
• CI/CD Ready: Zero-dependency execution via npx or bunx for pipeline integration
• Version Controlled: Reports are designed to be committed, enabling diffable dependency history

---

Installation

Global Install (Recommended)

Via npm:

npm i -g @yabasha/gex

Via Bun:

bun add -g @yabasha/gex

Local Build / Development

# Clone the repository
git clone <https://github.com/yabasha/yabasha-gex.git>
cd yabasha-gex

# Using npm
npm i
npm run build
node dist/cli.cjs --help

# Using Bun
bun install
bun run build
bun dist/cli-bun.mjs --help

---

Usage

Interactive Launcher: gex

Starting with v1.3.6, the primary gex binary is an interactive launcher:

$ gex

GEX interactive launcher
Choose a runtime and command to run:

  1) gex-node local  – Node (npm) local project report
  2) gex-node global – Node (npm) global packages report
  3) gex-node read   – Node (npm) read existing report
  4) gex-bun local   – Bun local project report
  5) gex-bun global  – Bun global packages report
  6) gex-bun read    – Bun read existing report
  q) Quit without running anything

Selected: gex-node local
Enter extra flags/arguments for "gex-node local" (or press Enter for none):

You can pass additional flags (e.g., -full-tree -f md -o report.md) which get forwarded to the underlying command.

Direct Mode: If you run gex with arguments (e.g., gex local --check-outdated), it behaves as gex-node for backward compatibility.

Direct Runtimes: gex-node & gex-bun

For scriptability or CI/CD, call runtimes directly:

# Node.js/npm runtime
gex-node [command] [options]    # Alias: gn

# Bun runtime
gex-bun [command] [options]     # Alias: gb

Available Commands:

• local - Audit local project dependencies (default)
• global - Audit globally installed packages
• read - Read and optionally install from an existing report

Common Flags:

• f, --output-format <md|json> - Output format (default: json)
• o, --out-file <path> - Write output to file instead of stdout
• full-tree - Include full npm ls JSON under tree key
• omit-dev - Exclude devDependencies (local only)
• c, --check-outdated - Show outdated packages as a table
• u, --update-outdated [pkg...] - Update outdated packages

Examples

<details> <summary> <strong>View Full CLI Examples</strong> (click to expand) </summary>

# Local reports - JSON (default)
gex-node                                    # Print to console
gex-node -o report.json                     # Write to file
gex-bun local -o report.json                # Bun runtime

# Local reports - Markdown
gex-node -f md                              # Print to console
gex-node -f md -o report.md                 # Write to file

# Exclude devDependencies
gex-node local --omit-dev -o deps.json

# Global packages
gex-node global -o global.json
gex-bun global -f md -o global.md

# Read existing reports
gex-node read -r path/to/report.json        # JSON report
gex-node read global.md                     # Markdown report
gex-node read -i                            # Install packages from report

# Pipeline processing
gex-node global | jq '.global_packages'     # Use with jq
gex-bun local > report.json                 # Shell redirection

# Outdated package management
gex-node local --check-outdated             # Show outdated table
gex-node local -u axios react               # Update specific packages
gex-bun global --update-outdated            # Update all global Bun packages

</details>

---

Output Formats

JSON Schema

Reports include metadata and dependency arrays:

{
  "report_version": "1.0",
  "timestamp": "2025-01-01T12:00:00.000Z",
  "tool_version": "0.1.0",
  "project_name": "my-app",
  "project_version": "1.2.3",
  "global_packages": [
    {
      "name": "@yabasha/gex",
      "version": "1.3.6",
      "resolved_path": "/usr/local/lib/node_modules/@yabasha/gex"
    }
  ],
  "local_dependencies": [
    {
      "name": "commander",
      "version": "12.1.0",
      "resolved_path": "/path/to/project/node_modules/commander"
    }
  ],
  "local_dev_dependencies": [
    {
      "name": "vitest",
      "version": "2.1.1",
      "resolved_path": "/path/to/project/node_modules/vitest"
    }
  ],
  "tree": { /* Full npm ls JSON when --full-tree is used */}
}

Markdown Example

# Dependency Report: my-app v1.2.3
Generated: 2025-01-01T12:00:00.000Z

## Global Packages (3)
- `@yabasha/gex@1.3.6`
- `bun@1.1.0`
- `npm@10.0.0`

## Local Dependencies (5)
- `commander@12.1.0`
- `express@4.18.2`

## Dev Dependencies (4)
- `vitest@2.1.1`
- `typescript@5.3.3`

---

Outdated Package Management

GEX integrates directly with package managers to handle outdated dependencies:

Check Outdated:

gex-node local --check-outdated
# Shows: Name | Current | Wanted | Latest | Type

Update Outdated:

gex-node local --update-outdated          # Update all
gex-node local -u axios react             # Update specific packages
gex-bun global --update-outdated          # Bun reinstalls globals at latest

After updating, rerun with --check-outdated to verify, and generate a new report with -o to capture the updated state.

---

CI/CD Integration

GEX is designed for zero-config CI/CD pipelines:

# GitHub Actions (Node.js)
- name: Generate dependency report
  run: npx -y @yabasha/gex@latest -f json -o gex-report.json

# GitHub Actions (Bun)
- name: Generate dependency report
  run: bunx @yabasha/gex@latest -f json -o gex-report.json

# Commit report for diffing
- name: Commit dependency report
  run: |
    git add gex-report.json
    git commit -m "chore: update dependency report" || echo "No changes"

---

Development & Contributing

# Initial setup
npm install
npm run build

# Development loop
npm run dev      # Watch mode + CLI help on success

# Quality checks
npm test         # Vitest
npm run lint
npm run format

# Contributing workflow
# 1. Create branch: feat/my-feature
# 2. Make changes + add tests
# 3. Add changeset: npx changeset
# 4. Open PR: gh pr create --fill

We welcome contributions! The repository is open-source to allow community-driven expansion and adaptation.

---

License: MIT

Built to solve real developer friction—open-sourced to help the community manage dependencies across Node.js and Bun ecosystems with confidence.