| name | hello-env |
| description | Zero-dependency Bash environment health check for Linux, macOS, containers, and K8s pods. Reports OS, current user, Node.js, Python3, basic tools (git/curl/jq/make/docker) with paths and versions, network (hostname, IP, inferred subnet), container/K8s detection with a configurable env-var probe, workdir and git status, optional config-file check, and PVC remount detection (device-number plus watch-dir count snapshot diff to catch silent K8s PersistentVolume reattach to a fresh disk). Three-layer config — CLI flags override env vars override defaults. Trigger when user wants to check the environment, verify a dev box is healthy, detect container or K8s context, look up local IP or subnet, see Node and Python versions, list installed basic tools, or watch for silent PVC rotation in K8s pods. Also triggers on 检查我的环境, 环境自检, hello-env, 查看系统信息, 环境有没有问题, IP 是多少, 在什么环境, PVC 换卷了吗, 基础工具检查, node 版本, 当前用户是谁.
|
hello-env
A zero-dependency Bash health check for any dev environment — host, container, or K8s pod.
一个零依赖的开源环境自检脚本，适用于本地、容器、K8s Pod 环境。
Pure bash. No Python, no npm, no third-party packages. Works on macOS, Linux, and inside containers.
Compatibility
| Platform | Status |
|---|
| Linux (any distro) | ✅ Full |
| macOS (bash 3.2.57+ default) | ✅ Full — uses eval-based indirect var expansion for bash 3.x |
| Windows (WSL / WSL2) | ✅ Full (effectively Linux) |
| Windows (Git Bash / MSYS / Cygwin) | ⚠️ Partial — OS/user/tools/network checks work; cgroup container detection and PVC monitoring are skipped (Linux-only kernel features) |
| Windows (PowerShell / cmd) | ❌ Not supported by design (bash script) |
| Agent Platform | Status |
|---|
| Claude Code | ✅ Standard SKILL.md, drops in |
| Codex | ✅ Same |
| OpenClaw | ✅ Native format |
| Cursor / Cline / others | ✅ Generic Markdown + bash, no platform hooks |
Quick start
bash scripts/check-env.sh
bash scripts/check-env.sh --workdir /opt/myapp
bash scripts/check-env.sh --probe-env "MY_REGION,MY_TIER,DEPLOY_ENV"
bash scripts/check-env.sh --force-pvc
bash scripts/check-env.sh \
--workdir /opt/myapp \
--watch-dir /opt/myapp/plugins \
--config /etc/myapp/config.json \
--probe-env "MY_REGION,MY_TIER" \
--force-pvc
What it checks
| # | Module | Output |
|---|
| 1 | OS | macOS / Linux distro + version |
| 2 | Current User | whoami + UID/GID |
| 3 | Node.js | Path (which node) + version |
| 4 | Python3 | Path + version |
| 5 | Basic Tools | git, curl, jq, docker, make — present / missing |
| 6 | Network | Hostname + IP + inferred private subnet (10.x / 172.16-31.x / 192.168.x) |
| 7 | Container / K8s | Probes configurable env vars; defaults to KUBERNETES_SERVICE_HOST + K8S_NAMESPACE; falls back to /.dockerenv / cgroup heuristics |
| 8 | Workdir | Path exists + git initialized check |
| 9 | Config file | Only checked if --config <path> provided |
| 10 | PVC persistence | Mount device-number + watch-dir count snapshot diff (auto when K8s probe hits, or --force-pvc) |
Output legend: ✅ ok · ℹ️ info · ⚠️ warning · ❌ failure
CLI flags
| Flag | Default | Description |
|---|
--workdir <path> | pwd | Working directory to check (existence + git init) |
--watch-dir <path> | <workdir> | Directory whose subfolder count is snapshotted for PVC monitoring |
--config <path> | (unset) | Optional config file to check existence |
--probe-env "A,B,C" | KUBERNETES_SERVICE_HOST,K8S_NAMESPACE | Comma-separated env vars to probe for container/K8s context |
--force-pvc | off | Force PVC monitoring even when no K8s indicator is found |
--snapshot-dir <path> | <workdir>/.hello-env | Where to store device/count snapshots |
-h, --help | — | Show inline help |
Environment variables (lower priority than CLI flags)
| Variable | Equivalent flag |
|---|
HELLO_ENV_WORKDIR | --workdir |
HELLO_ENV_WATCH_DIR | --watch-dir |
HELLO_ENV_CONFIG | --config |
HELLO_ENV_PROBE_ENV | --probe-env |
HELLO_ENV_FORCE_PVC=1 | --force-pvc |
HELLO_ENV_SNAPSHOT_DIR | --snapshot-dir |
PVC remount detection (why this matters)
K8s PersistentVolumes can silently get reattached to a fresh disk during pod restarts or node failover. Symptoms users typically see:
"All the files I created yesterday are gone after the pod restarted."
This script catches it early by snapshotting on each run:
<snapshot-dir>/last-device — the mount device for <workdir><snapshot-dir>/last-watch-count — find <watch-dir> -maxdepth 1 -mindepth 1 -type d | wc -l
Next run decides:
| Device | Watch-dir count | Verdict |
|---|
| changed | any | ⚠️ Likely PVC remount |
| unchanged | decreased | ℹ️ Probably manual removal |
| unchanged | not decreased | ✅ Healthy |
When PVC monitoring activates:
- Any of the env vars listed in
--probe-env is set, OR
--force-pvc / HELLO_ENV_FORCE_PVC=1 is on
If neither, you get a hint:
ℹ️ Not detected as containerized environment. Use --force-pvc to enable PVC monitoring anyway.
Examples
CI runner sanity check
bash scripts/check-env.sh --workdir "$CI_PROJECT_DIR" --probe-env "CI,GITLAB_CI,GITHUB_ACTIONS"
K8s pod with custom labels
bash scripts/check-env.sh \
--probe-env "KUBERNETES_SERVICE_HOST,K8S_NAMESPACE,MY_REGION,MY_TIER" \
--watch-dir /workspace/plugins
Local Docker container without K8s
bash scripts/check-env.sh --force-pvc --workdir /app
Exit codes
0 — All checks ran (warnings allowed)- Non-zero only on argument parsing errors
This is a diagnostic tool, not a gate. It reports — it doesn't block.
