@kszongic/walk-dir-cli

Recursively walk a directory and print all file paths. Zero dependencies. Works everywhere Node.js runs.

$ walk-dir src/
src/index.js
src/utils/parse.js
src/utils/format.js
src/cli.js
src/constants.js

Why?

• Cross-platform — find doesn't exist on Windows, Get-ChildItem doesn't exist on macOS/Linux. walk-dir works everywhere.
• Zero dependencies — No glob, no fast-glob, no transitive dependency tree. Just Node.js built-ins.
• Pipe-friendly — NUL-separated output (-0) for safe xargs usage. One path per line by default.
• Filtered walks — Extension filtering, depth limiting, and directory ignoring built in.
• Fast — Synchronous readdirSync with no overhead. Handles tens of thousands of files without breaking a sweat.

Install

npm install -g @kszongic/walk-dir-cli

Or run it instantly with npx:

npx @kszongic/walk-dir-cli src/

Usage

# List all files in current directory recursively
walk-dir

# List files in a specific directory
walk-dir src/

# Include directories in output
walk-dir -d src/

# Print absolute paths
walk-dir -a

# Filter by extension
walk-dir --ext .js src/

# Limit recursion depth
walk-dir --depth 2

# Ignore directories (repeatable)
walk-dir --ignore node_modules --ignore .git

# NUL-separated output (for xargs -0)
walk-dir -0 | xargs -0 wc -l

# Combine options
walk-dir -a --ext .ts --ignore node_modules --depth 3 src/

Options

Option	Description
-d, --dirs	Include directories in output
-a, --absolute	Print absolute paths
-0, --null	Separate entries with NUL instead of newline
--depth <n>	Maximum recursion depth
--ext <ext>	Filter by file extension (e.g. .js)
--ignore <dir>	Ignore directory name (repeatable)
-h, --help	Show help
-v, --version	Show version

Recipes

Count files by extension

walk-dir --ext .ts src/ | wc -l
# 47

Find large files in a project

walk-dir --ignore node_modules --ignore .git | xargs ls -lS | head -20

Delete all .log files safely

walk-dir --ext .log -0 /var/app/logs | xargs -0 rm -v

Project file breakdown (by extension)

walk-dir --ignore node_modules --ignore .git | sed 's/.*\.//' | sort | uniq -c | sort -rn
#  142 ts
#   38 json
#   12 md
#    7 yml

Audit Docker build context

walk-dir --ignore node_modules --ignore .git --ignore dist | wc -l
# 83 files

Chain with other tools

# Total size of all TypeScript files
walk-dir --ext .ts src/ -0 | xargs -0 cat | wc -c

# Feed paths into checksum verification
walk-dir --ext .js dist/ | while read f; do sha256sum "$f"; done

npm scripts

{
  "scripts": {
    "files:ts": "walk-dir --ext .ts --ignore node_modules src/",
    "files:count": "walk-dir --ignore node_modules --ignore .git | wc -l",
    "files:abs": "walk-dir -a --depth 2"
  }
}

How It Works

walk-dir uses Node.js fs.readdirSync with recursive directory traversal. It reads directory entries one at a time, applies filters (extension, depth, ignore list), and writes matching paths to stdout. No temporary arrays, no buffering — paths stream out as they are found.

The -0 (NUL separator) flag ensures filenames with spaces, newlines, or special characters are handled correctly when piped to xargs -0.

Use Cases

• Project audits — Quickly see every file in a monorepo, filtered by type
• Build tooling — Feed file lists into custom build scripts, linters, or formatters
• CI pipelines — Count files, check for unexpected file types, or validate directory structure
• Docker optimization — Audit what is in your build context before shipping bloated images
• Migration scripts — List all files of a certain type for batch processing
• Documentation — Generate file tree snapshots for READMEs or wikis

Comparison

Feature	walk-dir	find (Unix)	Get-ChildItem (PS)	glob (npm)	fd (Rust)
Cross-platform	Yes	Unix only	Windows only	Yes	Yes
Zero dependencies	Yes	system	system	No (7+ deps)	binary
Extension filter	--ext	-name	-Filter	pattern	-e
Depth limit	--depth	-maxdepth	-Depth	No	-d
NUL separator	-0	-print0	No	No	-0
Ignore dirs	--ignore	-prune	-Exclude	ignore option	-E
Install	npm i -g	pre-installed	pre-installed	npm i	binary

When to use walk-dir: You need a simple, cross-platform file lister that works in CI (Linux runners), local dev (macOS/Windows), and npm scripts — without learning platform-specific syntax or adding heavy glob libraries.

Related Tools

• @kszongic/glob-size-cli — Check total size of files matching a glob pattern
• @kszongic/file-stat-cli — Get file metadata (size, dates, permissions)
• @kszongic/dep-size — Check npm package install sizes before adding them
• @kszongic/path-depth-cli — Calculate file path nesting depth
• @kszongic/env-lint-cli — Validate .env files against .env.example

License

MIT