checkcli

checkcli is a cross-ecosystem environment health checker for developer machines.

It helps you detect and fix common setup issues across PATH, package managers, versions, symlinks, and permissions.

Install

Run without installing:

npx @hermannmaier/checkcli --help

Install globally:

npm install -g @hermannmaier/checkcli
checkcli --help

Run from source:

npm install
npm run build
node dist/src/cli.js --help

Quick Start

# full report
checkcli

# machine-readable output
checkcli --json

# show available checks
checkcli --list-checks

# run a subset
checkcli --only path-health,project-versions

# skip expensive checks
checkcli --fast

# apply low-risk remediations
checkcli --apply-safe

Included Checks

• path-health: PATH duplication, command shadowing, manager overlap hints.
• symlink-health: broken symlink scan in common bin directories.
• node-health: Node/npm availability, npm prefix health, npm doctor.
• ownership-health: root-owned files in user-managed directories (common after sudo installs).
• project-versions: project constraints vs active runtime versions (.nvmrc, .node-version, .tool-versions, package.json#engines, .python-version, pyproject.toml).

Safety Model

Default behavior is non-destructive and report-only.

--apply-safe is intentionally limited to low-risk actions:

• create missing npm prefix directories,
• optionally remove broken symlinks after confirmation.

For permission-protected paths, the tool prints a follow-up elevated command for the specific operation. Do not run the entire tool with elevated privileges unless you explicitly intend to.

CLI Options

• --json: JSON output.
• --apply-safe: apply low-risk fixes.
• --yes: auto-confirm prompts during safe fixes.
• --only <id>[,<id>...]: run only selected checks.
• --skip <id>[,<id>...]: exclude selected checks.
• --list-checks: print check ids and titles.
• --fast: reduced-cost mode (skips npm doctor, smaller ownership/symlink scans).
• --color / --no-color: force-enable/disable ANSI colors in human output.

Output Colors

• Red: error findings and failed safe-fix actions.
• Yellow: warnings and skipped safe-fix actions.
• Green: suggested fixes and commands.

Colors auto-enable for TTY output and are disabled in JSON mode.

Exit Codes

• 0: no error-level findings and no failed safe-fix actions.
• 1: at least one error-level finding or a failed safe-fix action.

Development

See CONTRIBUTING.md for local workflow, adding checks, and release steps.