SystemInspector

Lightweight, zero-dependency system and OS inspection library for Node.js.

What It Does

SystemInspector provides 58+ asynchronous functions for retrieving hardware, operating system, runtime, storage, network, process, service, and peripheral information. It is written in strict TypeScript, compiles to CommonJS, and has zero npm runtime dependencies.

Supported platforms: Linux, macOS, Windows, FreeBSD, OpenBSD, NetBSD, SunOS, Android.

Installation

npm install @ambicuity/systeminspector

Requires Node.js ≥ 18.0.0.

Quick Start

ESM (Vite, Next.js, Bun, modern Node ESM)

import * as si from '@ambicuity/systeminspector';

const cpu = await si.cpu();
const os = await si.osInfo();
console.log(cpu, os);

CommonJS

const si = require('@ambicuity/systeminspector');

async function main() {
  const cpu = await si.cpu();
  const os = await si.osInfo();
  console.log(cpu, os);
}

main();

Callback Style (deprecated, removed in v2.0)

const si = require('@ambicuity/systeminspector');

si.cpu((data) => {
  console.log(data);
});

Tip: the modern call form is await si.cpu({ timeoutMs, signal, redact, envelope }). Callback overloads still work but carry an @deprecated JSDoc tag and will be removed in v2.0. See docs/general.md for the full options surface.

CLI

SystemInspector includes a CLI for quick terminal inspection.

# Readable system report
npx @ambicuity/systeminspector info

# Full static data as JSON (useful for scripts and pipes)
npx @ambicuity/systeminspector

# Interactive terminal inspector
npx @ambicuity/systeminspector interactive

# Check support, tools, permissions, and diagnostics
npx @ambicuity/systeminspector doctor

# Inspect capability metadata
npx @ambicuity/systeminspector capabilities --json

# Select APIs and print JSON
npx @ambicuity/systeminspector get cpu,mem,osInfo --pretty

# Print schema metadata
npx @ambicuity/systeminspector schema CpuData

# Redact sensitive values from readable reports
npx @ambicuity/systeminspector info --redact

# Help
npx @ambicuity/systeminspector --help

API Reference

All functions (except version() and time()) return Promises and accept an optional callback.

General

Function	Returns	Description
`version()`	`string`	Library version
`time()`	`TimeData`	Current time, uptime, timezone

System Hardware

Function	Returns
`system()`	`SystemData`
`bios()`	`BiosData`
`baseboard()`	`BaseboardData`
`chassis()`	`ChassisData`

CPU & Load

Function	Returns
`cpu()`	`CpuData`
`cpuFlags()`	`string`
`cpuCache()`	`CpuCacheData`
`cpuCurrentSpeed()`	`CpuCurrentSpeedData`
`cpuTemperature()`	`CpuTemperatureData`
`currentLoad()`	`CurrentLoadData`
`fullLoad()`	`number`

Memory & Battery

Function	Returns
`mem()`	`MemData`
`memLayout()`	`MemLayoutData[]`
`battery()`	`BatteryData`

Graphics & Peripherals

Function	Returns
`graphics()`	`GraphicsData`
`usb()`	`UsbData[]`
`printer()`	`PrinterData[]`
`audio()`	`AudioData[]`
`bluetoothDevices()`	`BluetoothDeviceData[]`

Operating System

Function	Returns
`osInfo()`	`OsData`
`versions()`	`VersionData`
`shell()`	`string`
`uuid()`	`UuidData`
`users()`	`UserData[]`

File System & Disks

Function	Returns
`fsSize()`	`FsSizeData[]`
`fsOpenFiles()`	`FsOpenFilesData`
`blockDevices()`	`BlockDevicesData[]`
`fsStats()`	`FsStatsData`
`disksIO()`	`DisksIoData`
`diskLayout()`	`DiskLayoutData[]`

Network & Wi-Fi

Function	Returns
`networkInterfaces()`	`NetworkInterfacesData[]`
`networkInterfaceDefault()`	`string`
`networkGatewayDefault()`	`string`
`networkStats()`	`NetworkStatsData[]`
`networkConnections()`	`NetworkConnectionsData[]`
`wifiNetworks()`	`WifiNetworkData[]`
`wifiInterfaces()`	`WifiInterfaceData[]`
`wifiConnections()`	`WifiConnectionData[]`

Processes & Services

Function	Returns
`processes()`	`ProcessesData`
`processLoad()`	`ProcessesProcessLoadData[]`
`services()`	`ServicesData[]`

Internet

Function	Returns
`inetChecksite()`	`InetChecksiteData`
`inetLatency()`	`number \| null`

Docker & VirtualBox

Function	Returns
`dockerInfo()`	`DockerInfoData`
`dockerImages()`	`DockerImageData[]`
`dockerContainers()`	`DockerContainerData[]`
`dockerContainerStats()`	`DockerContainerStatsData[]`
`dockerContainerProcesses()`	`DockerContainerProcessData[]`
`dockerVolumes()`	`DockerVolumeData[]`
`dockerAll()`	`any[]`
`vboxInfo()`	`VboxInfoData[]`

Aggregate Helpers

Function	Returns	Description
`getStaticData()`	`StaticData`	All static hardware/OS data in one call
`getDynamicData()`	`DynamicData`	All dynamic/runtime data in one call
`getAllData()`	`AllData`	Combined static + dynamic data
`get(valueObject)`	`object`	Selective data retrieval with field filtering
`observe(valueObject, interval, cb)`	`ObserveHandle`	Periodic observation with change detection

Diagnostics

Function	Returns	Description
`diagnostics()`	`DiagnosticData[]`	Non-breaking diagnostic records
`diagnostics({ sinceLastCall: true })`	`DiagnosticData[]`	Drain diagnostics recorded since the previous call
`clearDiagnostics()`	`void`	Clear diagnostic buffer
`onDiagnostic(cb)`	`() => void`	Subscribe to diagnostic records

await si.diskLayout();
console.log(si.diagnostics()); // check for missing tools, permission issues, etc.
si.clearDiagnostics();

Capabilities

Use capabilities before collecting data when you need to explain missing values or build support UIs.

const all = await si.capabilities();
const docker = await si.capability('dockerContainers');

Capability records include the function name, platform, required tools, detected tools, permission hints, support status, and confidence.

Options, Envelopes, and Redaction

Existing return shapes remain unchanged. Newer APIs can opt into metadata with an options object while keeping callbacks last.

const cpu = await si.cpu({ timeoutMs: 3000 });

const detailed = await si.cpu({
  envelope: true,
  timeoutMs: 3000,
  redact: true
});

console.log(detailed.data);
console.log(detailed.diagnostics);

Redaction can hide serial numbers, MAC addresses, usernames, IP addresses, UUIDs, and process arguments when supported by the call path.

Watch and Schemas

for await (const snapshot of si.watch({ cpuCurrentSpeed: '*', mem: '*' }, { intervalMs: 1000 })) {
  console.log(snapshot);
}

console.log(si.schemaVersion());
console.log(si.getSchema('CpuData'));

Architecture

systeminspector/
├── src/                    # TypeScript source (24 modules)
│   ├── index.ts            # Public API — exports all 58+ functions
│   ├── cli.ts              # CLI entry point (bin: systeminspector)
│   ├── types.ts            # Shared type definitions
│   ├── util.ts             # Internal utilities (exec, parsing, caching)
│   ├── cpu.ts              # CPU inspection
│   ├── memory.ts           # Memory inspection
│   ├── osinfo.ts           # OS information
│   ├── network.ts          # Network interfaces and stats
│   ├── filesystem.ts       # Filesystem and disk inspection
│   ├── processes.ts        # Process and service inspection
│   ├── docker.ts           # Docker container inspection
│   ├── graphics.ts         # GPU and display inspection
│   ├── wifi.ts             # Wi-Fi network inspection
│   ├── system.ts           # System/BIOS/baseboard/chassis
│   ├── battery.ts          # Battery status
│   ├── bluetooth.ts        # Bluetooth device discovery
│   ├── audio.ts            # Audio device inspection
│   ├── printer.ts          # Printer inspection
│   ├── usb.ts              # USB device inspection
│   ├── internet.ts         # Internet connectivity checks
│   ├── users.ts            # User session inspection
│   ├── virtualbox.ts       # VirtualBox VM inspection
│   ├── dockerSocket.ts     # Docker socket communication
│   └── bluetoothVendors.ts # Bluetooth vendor OUI database
├── dist/                   # Compiled output (CommonJS + declarations)
├── test/                   # Tests
│   ├── index.test.ts       # Vitest unit tests
│   ├── ci.ts               # CI smoke tests (runs against built dist)
│   ├── test.ts             # Interactive test runner
│   └── si.ts               # Test helper
├── docs/                   # VitePress documentation site
├── scripts/                # Build and verification scripts
├── biome.json              # Biome linter/formatter configuration
├── tsconfig.json           # TypeScript compiler configuration
├── tsconfig.test.json      # TypeScript config for test files
└── vitest.config.ts        # Vitest test configuration

Development

Build

npm run build

Compiles TypeScript from src/ to dist/ using tsc.

Typecheck

npm run typecheck          # source only
npm run typecheck:test     # source + tests

Lint

npm run lint               # check with Biome
npm run format             # auto-format with Biome

Test

npm test                   # Vitest unit tests
npm run test:ci            # CI smoke tests (requires built dist)

Verify Release

npm run verify:release     # full release verification suite
npm run verify:terminal    # terminal API smoke test

CI/CD

GitHub Actions workflows:

Workflow	Trigger	Purpose
CI (`ci.yml`)	Push/PR to `main`	Lint, typecheck, build, test across Ubuntu/macOS/Windows × Node.js 20/22, plus a Node.js 18 packaged runtime smoke test
npm Publish (`npm-publish.yml`)	GitHub Release/manual	Build, test, publish to npmjs with provenance and mirror to GitHub Packages
CodeQL (`codeql.yml`)	Push/PR + weekly	Security analysis for JavaScript/TypeScript
Deploy Docs (`deploy.yml`)	Push to `main`	Build and deploy VitePress site to GitHub Pages

GitHub Pages must be configured with Source: GitHub Actions in repository settings before the docs deployment can publish.

Release Process

Update version in package.json.
Update CHANGELOG.md.
Commit: git commit -m "chore: prepare vX.Y.Z release".
Tag: git tag vX.Y.Z.
Push: git push origin main && git push origin vX.Y.Z.
Create a GitHub Release from the tag — this triggers npm publish automatically.

For the scoped npm package, publish to the public npm registry. This command pins the registry because some developer machines map the @ambicuity scope to GitHub Packages:

npm publish --access public --provenance --registry=https://registry.npmjs.org/

For release verification, check the tag and package availability first:

git ls-remote --tags origin vX.Y.Z
npm view @ambicuity/systeminspector version --@ambicuity:registry=https://registry.npmjs.org/

Dependency Audit

The published package has zero runtime dependencies. The documentation toolchain currently inherits a moderate dev-server advisory through VitePress/Vite/esbuild; npm does not provide an automatic fix for the current VitePress line. Do not run the VitePress development server on an untrusted network, and revisit this when VitePress publishes a compatible fixed release.

Notes

fsStats(), disksIO(), and networkStats() calculate per-second values from the difference between calls. The first call returns null for transfer-rate fields; subsequent calls return rates based on elapsed time.

const si = require('@ambicuity/systeminspector');

setInterval(() => {
  si.networkStats().then((data) => console.log(data));
}, 1000);

Some APIs depend on platform tools such as PowerShell, sensors, Docker, VirtualBox, or smartmontools. Unsupported values may be returned as null, empty strings, or empty collections.

Platform Support Matrix

Function	Linux	macOS	Windows	BSD	SunOS	Android
`cpu`, `mem`, `osInfo`, `time`, `currentLoad`	✅	✅	✅	✅	✅	✅
`cpuTemperature`	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️
`system`, `bios`, `baseboard`, `chassis`	⚠️	✅	✅	⚠️	⚠️	⚠️
`fsSize`, `blockDevices`, `diskLayout`	✅	✅	✅	⚠️	⚠️	⚠️
`fsStats`, `disksIO`	✅	✅	❌	⚠️	❌	✅
`networkInterfaces`, `networkStats`	✅	✅	✅	✅	⚠️	✅
`wifiNetworks`, `wifiInterfaces`, `wifiConnections`	⚠️	⚠️	⚠️	❌	❌	⚠️
`docker*`	⚠️	⚠️	⚠️	❌	❌	❌
`vboxInfo`	⚠️	⚠️	⚠️	❌	❌	❌
`usb`, `audio`, `bluetoothDevices`, `printer`, `graphics`	⚠️	⚠️	⚠️	⚠️	⚠️	⚠️

Legend: ✅ supported, ⚠️ partial or requires platform tools/permissions, ❌ unsupported or not currently implemented.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Security

See SECURITY.md for vulnerability reporting guidance.

Sponsorship

If SystemInspector is useful to you, consider supporting the project:

License

Maintainer

Ritesh Rana — GitHub

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
examples/otel		examples/otel
scripts		scripts
src		src
test		test
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.lint-warning-baseline		.lint-warning-baseline
.markdownlint.json		.markdownlint.json
.nvmrc		.nvmrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
biome.json		biome.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.esm.json		tsconfig.esm.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

SystemInspector

What It Does

Installation

Quick Start

ESM (Vite, Next.js, Bun, modern Node ESM)

CommonJS

Callback Style (deprecated, removed in v2.0)

CLI

API Reference

General

System Hardware

CPU & Load

Memory & Battery

Graphics & Peripherals

Operating System

File System & Disks

Network & Wi-Fi

Processes & Services

Internet

Docker & VirtualBox

Aggregate Helpers

Diagnostics

Capabilities

Options, Envelopes, and Redaction

Watch and Schemas

Architecture

Development

Build

Typecheck

Lint

Test

Verify Release

CI/CD

Release Process

Dependency Audit

Notes

Platform Support Matrix

Contributing

Security

Sponsorship

License

Maintainer

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages