whitespace-cli 🔍

Visualize and inspect invisible whitespace characters in any file. Tabs, spaces, CRs, NBSP, zero-width — nothing hides.

Why?

Invisible characters cause real bugs:

• Mixed tabs and spaces break Python indentation and YAML configs
• Trailing whitespace creates noisy git diffs and fails lint rules
• Carriage returns sneak into files when someone edits on Windows
• Non-breaking spaces (NBSP) look identical to regular spaces but break parsers
• Zero-width characters hide in copy-pasted text and cause mysterious comparison failures

Your editor "shows whitespace" but only partially. whitespace-cli reveals everything — in any file, from any pipeline.

npx @kszongic/whitespace-cli --show config.yml

Install

npm install -g @kszongic/whitespace-cli

Or run directly without installing:

npx @kszongic/whitespace-cli file.txt

Quick Start

# Visualize all whitespace in a file
whitespace file.txt

# Pipe from stdin
echo "hello	world" | whitespace --show

# Count whitespace characters by type
whitespace --count src/index.js

# Find lines with leading/trailing whitespace
whitespace --trim src/index.js

Modes

--show (default) — Visualize Whitespace

Replaces invisible characters with visible symbols:

Character	Symbol	Unicode
Space	·	U+0020
Tab	⇥	U+0009
CR (\r)	␍	U+000D
LF (\n)	↵	U+000A
NBSP	⍽	U+00A0
Zero-width space	∅	U+200B

--count — Whitespace Statistics

whitespace --count package.json

spaces:    42
tabs:      8
CR (\r):   0
LF (\n):   15
NBSP:      0
ZWSP:      0
other:     0
total:     65

--trim — Find Leading/Trailing Whitespace

whitespace --trim src/index.js

   1 | [lead:4]    function main() {
   2 |  return 0;
   3 | [lead:4, trail:2]    }

Recipes

Audit a project for mixed indentation

find src -name "*.js" -exec whitespace --count {} + | grep tabs

Check for Windows line endings in a git repo

git ls-files | xargs -I{} sh -c 'whitespace --count "{}" | grep -q "CR.*[1-9]" && echo "CRLF found: {}"'

Pre-commit hook — reject trailing whitespace

#!/bin/sh
# .git/hooks/pre-commit
for file in $(git diff --cached --name-only); do
  if whitespace --trim "$file" | grep -q "trail:"; then
    echo "Trailing whitespace in $file"
    exit 1
  fi
done

CI pipeline — enforce clean whitespace

# GitHub Actions
- name: Check whitespace
  run: |
    npm install -g @kszongic/whitespace-cli
    find src -name "*.ts" | xargs -I{} sh -c '
      if whitespace --count "{}" | grep -q "NBSP.*[1-9]"; then
        echo "NBSP found in {}" && exit 1
      fi
    '

Debug copy-paste issues

Text copied from web pages or PDFs often contains invisible zero-width characters:

echo "suspicious string" | whitespace --show
# reveals zero-width spaces hiding between characters

npm scripts

{
  "scripts": {
    "lint:whitespace": "whitespace --count src/index.js",
    "check:trailing": "whitespace --trim src/**/*.js | grep trail && exit 1 || exit 0"
  }
}

Use Cases

• Code review — Spot mixed indentation before it reaches the PR
• YAML/Python debugging — Find that invisible tab breaking your config
• Cross-platform projects — Detect CRLF line endings from Windows contributors
• Security auditing — Find zero-width characters in homograph attacks
• Data cleaning — Identify NBSP and Unicode whitespace in CSV/JSON data
• Documentation — Ensure Markdown files have consistent formatting

Options

Flag	Description
-s, --show	Show whitespace as visible symbols (default)
-c, --count	Count whitespace characters by type
-t, --trim	Show leading/trailing whitespace per line
-h, --help	Show help
-v, --version	Show version

How It Works

Reads the file (or stdin) as a UTF-8 string, then walks each character checking against a map of whitespace Unicode code points. In --show mode, each whitespace character is replaced with its visible symbol. In --count mode, it tallies by category. In --trim mode, it measures leading/trailing lengths per line. No regex, no dependencies — just character-by-character inspection.

Comparison

Tool	Zero deps	Cross-platform	Visualize	Count	Trailing detect	NBSP/ZWSP
whitespace-cli	✅	✅ Win/Mac/Linux	✅	✅	✅	✅
cat -A	N/A	❌ Unix only	Partial	❌	❌	❌
cat -vet	N/A	❌ Unix only	Partial	❌	❌	❌
VS Code whitespace	N/A	✅	In editor	❌	❌	❌
hexdump / xxd	N/A	❌ Unix only	Raw bytes	❌	❌	Manual

Related Tools

Part of a zero-dependency CLI toolkit:

• env-lint-cli — Lint .env files against .env.example
• checksum-verify-cli — Verify file checksums cross-platform
• string-hash-cli — Hash strings from the command line
• freq-table-cli — Frequency tables from stdin
• detect-lang-cli — Detect programming language of files

License

MIT © kszongic