pi-env-probe

Cross-platform environment diagnostics for Pi — shell, PATH, runtime, encoding, and non-ASCII path risks in compact JSON.

What this is

pi-env-probe collects lightweight environment diagnostics and returns them as compact JSON. Use it from the CLI, as a Pi slash command, or import probe() in your own tooling.

Features

• Detects the current shell (bash, pwsh, cmd, zsh, or null)
• Reports whether common shells are available in PATH
• Detects non-ASCII file/folder names in the current working directory
• Returns the platform path separator (; on Windows, : on POSIX)
• Aggregates identified risks into a sorted array
• Never throws from probe() — subprocess failures degrade to false / null

Probe result fields

Field	Type	Description
shell	string | null	Identified shell name ("bash", "pwsh", "cmd", "zsh", or null)
shell_available	boolean	Whether any shell is available in PATH or detected from environment
bash_in_path	boolean	Whether bash is found in PATH
pwsh_in_path	boolean	Whether pwsh is found in PATH
has_non_ascii_paths_in_cwd	boolean	Whether any direct child of CWD has a non-ASCII name
path_separator	string	Platform path separator (";" on Windows, ":" on POSIX)
node_version	string | null	Node.js version string (e.g. "v22.0.0"), or null if unavailable
bun_version	string | null	Bun version string, or null if unavailable
python_version	string | null	Python version string, or null if unavailable
encoding	string	Detected locale encoding from LC_CTYPE / LANG, defaults to "utf8"
risks	string[]	Ordered list of identified issues, empty [] when none

Risk strings

The risks array may contain any of the following strings, in order: shell issues first, runtime issues second, path issues last.

Risk string	Condition
"bash_not_in_path"	bash_in_path is false
"pwsh_not_in_path"	pwsh_in_path is false
"node_not_available"	node_version is null
"bun_not_available"	bun_version is null
"python_not_available"	python_version is null
"non_ascii_paths_in_cwd"	has_non_ascii_paths_in_cwd is true

The risk array is always present. When no issues are detected it is an empty array [].

Install

Install the published npm package with Pi:

pi install npm:pi-env-probe

Install into the current project instead of your user Pi settings:

pi install npm:pi-env-probe -l

Or install from GitHub:

pi install git:github.com/eiei114/pi-env-probe

Try it without permanently installing:

pi -e npm:pi-env-probe

Quick start

Try this package locally:

pi -e .

Then run:

/env-probe

Or use the standalone CLI:

node bin/env-probe.js

Package contents

Path	Purpose
lib/	Shared probe logic (probe.ts)
extensions/	Pi extension registering /env-probe
bin/	Standalone CLI entry point

Development

npm install
npm run ci

Verification

npm install
npm run typecheck
npm test
node bin/env-probe.js
node bin/env-probe.js | node -e "process.stdin.on('data',d=>{JSON.parse(d);console.log('valid JSON')})"
npm pack --dry-run

Release

This package is set up for npm Trusted Publishing, so no NPM_TOKEN is required.

npm version patch
git push --follow-tags

License

MIT — see LICENSE.