LocIO

Appearance

CLI Usage ​

The LocIO CLI (locio) lets you quickly count files and lines of code in directories with powerful filters and rich statistics.

This page provides an overview of the most common commands and flags.

Basic usage ​

  • Installation, first run, and common workflows are covered in Get Started.
  • This page focuses on the full list of flags and options and how they behave.

Detailed Options Reference ​

Below is a complete list of all LocIO CLI arguments and what they do.

Positional Arguments ​

  • paths...
    • Type: one or more paths (default: .)
    • Description:
      • If you provide no arguments, LocIO scans the current directory.
      • If you provide one argument, LocIO scans either that directory or that single file.
      • If you provide multiple arguments, LocIO scans each path (directories and/or files) and then produces a combined report.
    • Examples:
      • locio (current directory)
      • locio ./src (directory)
      • locio /path/to/project (directory)
      • locio ./src/index.ts (single file)
      • locio /path/to/file.js (single file)
      • locio packages/core packages/web (multiple directories)

Mode Flags ​

  • -f, --files-only

    • Description: Count only files, ignoring line counts.
    • Use when: You just need file counts per directory/extension.
    • Example: locio --files-only

  • -l, --lines-only

    • Description: Count only lines, ignoring file counts.
    • Use when: You only care about total lines of code.
    • Example: locio --lines-only

  • --workspaces

    • Description: Auto-detect and scan workspace packages from a monorepo root (npm/Yarn workspaces, pnpm-workspace.yaml, or lerna.json).
    • Behavior:
      • Uses the first positional path as the monorepo root.
      • Discovers each workspace directory that contains a package.json.
      • Scans each workspace separately, then produces a combined report.
    • Examples:
      • locio . --workspaces --stats
      • locio /path/to/monorepo --workspaces --stats --export json,html

If both are omitted, LocIO reports both files and lines.

Include / Exclude by Pattern, Extension, Directory, Name ​

  • -e, --exclude <PATTERN>

    • Type: repeatable (regex)
    • Description: Exclude files whose full path matches the given regular expression.
    • Examples:
      • locio --exclude ".*\\.log$"
      • locio --exclude ".*\\.test\\.(js|ts)$"

  • --exclude-ext <EXTENSIONS>

    • Type: comma-separated list
    • Description: Exclude files with the given extensions. Dots are optional (ts and .ts are both accepted).
    • Examples:
      • locio --exclude-ext log,tmp
      • locio --exclude-ext .png,.jpg

  • --include-ext <EXTENSIONS>

    • Type: comma-separated list
    • Description: Include only files with the given extensions.
    • Examples:
      • locio --include-ext ts
      • locio --include-ext ts,tsx,js

  • --exclude-dir <PATTERN>

    • Type: repeatable (regex)
    • Description: Exclude directories whose path matches the regular expression (e.g. node_modules, dist).
    • Examples:
      • locio --exclude-dir node_modules
      • locio --exclude-dir dist --exclude-dir build

  • --include-dir <PATTERN>

    • Type: repeatable (regex)
    • Description: Only scan directories whose path matches the regular expression. All other directories are skipped.
    • Examples:
      • locio --include-dir src
      • locio --include-dir packages/core

  • --exclude-name <PATTERN>

    • Type: repeatable (regex)
    • Description: Exclude files by file name regular expression (not full path). Useful for things like README, LICENSE, etc.
    • Examples:
      • locio --exclude-name README.md
      • locio --exclude-name "*.spec.ts"

  • --include-name <PATTERN>

    • Type: repeatable (regex)
    • Description: Only include files whose name matches the regular expression.
    • Examples:
      • locio --include-name "*.ts"
      • locio --include-name "index.*"

Size and Depth Control ​

  • --max-size <SIZE>

    • Type: single value
    • Description: Skip files larger than the given size.
    • Examples:
      • locio --max-size 5MB
      • locio --max-size 100K

  • --min-size <SIZE>

    • Type: single value
    • Description: Skip files smaller than the given size.
    • Examples:
      • locio --min-size 1K
      • locio --min-size 10KB

  • --max-depth <DEPTH>

    • Type: integer
    • Description: Limit how deep LocIO will traverse from the root directory. 1 means only the root directory itself.
    • Examples:
      • locio --max-depth 1
      • locio --max-depth 3

  • --no-hidden

    • Description: Exclude hidden files and directories (e.g. .git, .env).
    • Example: locio --no-hidden

  • --no-empty

    • Description: Exclude empty files from counts.
    • Example: locio --no-empty

  • --follow-links

    • Description: Follow symbolic links when traversing directories.
    • Example: locio --follow-links

  • --no-binary

    • Description: Skip files detected as binary (e.g. images, compiled artifacts).
    • Example: locio --no-binary

Output and statistics ​

  • --stats

    • Description: Show detailed statistics (extensions, directories, etc.) instead of just simple totals.
    • Examples:
      • locio --stats
      • locio --include-ext ts,tsx --stats

  • Language-level statistics (default when stats are shown)

    • LocIO groups counts by language as well as by file extension.
    • For each detected language you get:
      • Files
      • Total lines
      • Code lines
      • Comment lines
      • Blank lines
      • Total size
    • All export formats now include a language breakdown:
      • Human/terminal output – “Statistics by Language” section
      • JSON – by_language array
      • CSV/TSV – “Language Breakdown” section
      • Markdown – “Statistics by Language” table
      • HTML – language bar chart and table

  • --no-progress

    • Description: Disable progress indicator. Progress is enabled by default.
    • Example: locio --no-progress

  • --export <FORMAT>

    • Type: human | json | csv | tsv | markdown | html (optional, defaults to human if omitted)
    • Description: Write the report to a file named LocIO-report.{ext} in the given format instead of only printing to stdout.
    • Details:
      • --export or --export human → LocIO-report.txt
      • --export json → LocIO-report.json (includes blank_lines in summary and by_extension stats)
      • --export csv → LocIO-report.csv (includes Blank Lines column)
      • --export tsv → LocIO-report.tsv (includes Blank Lines column)
      • --export markdown or --export md → LocIO-report.md (includes Blank Lines in summary and tables)
      • --export html → LocIO-report.html (includes Blank Lines card/columns, language charts, directory graph, and an interactive treemap)
      • Multiple formats: --export json,html,markdown → creates all three files
    • Note: All export formats include blank lines in the breakdown. The formula is: Total Lines = Code Lines + Comment Lines + Blank Lines
    • Examples:
      • locio --stats --export
      • locio --stats --export json
      • locio --stats --export json,html,markdown

  • --export-path <DIR>

    • Type: directory path
    • Description: Specify output directory for exported reports. Files will use default naming (LocIO-report.{ext}). Directories will be created automatically if they don't exist.
    • Examples:
      • locio --stats --export json --export-path ./reports
      • locio --stats --export json,html --export-path ./output

  • --duplicates

    • Description: Enable duplicate file detection. LocIO will hash file contents, group identical files, and report “wasted lines” per group.
    • Notes:
      • Results appear in a “Duplicate Files” section of the human/Markdown/HTML outputs.
      • JSON exports include a duplicate_groups array.
      • See Duplicate File Detection below for full details.
    • Example: locio . --stats --duplicates

Matching Behavior and Noise Control ​

  • -i, --ignore-case

    • Description: Make pattern matching for include/exclude options case-insensitive.
    • Example: locio --exclude ".*\\.LOG$" --ignore-case

  • -q, --quiet

    • Description: Reduce or suppress non-essential output (useful in scripts/CI).
    • Example: locio --quiet --stats --export json

Comment Analysis ​

  • --no-comments

    • Description: Disable comment counting. Comment analysis is enabled by default and provides breakdown of code lines, comment lines (full-line and inline), and blank lines.
    • Example: locio --no-comments

  • --comments (deprecated)

    • Description: This flag is now the default behavior. Use --no-comments to disable comment analysis.
    • Note: Comment analysis is automatically enabled by default, showing:
      • Code Lines: Lines containing actual code
      • Comment Lines: Lines containing comments (full-line and inline)
      • Blank Lines: Empty lines (always included in totals)

    Important: Blank lines are always included in the total line count and shown in all output formats. The formula is: Total Lines = Code Lines + Comment Lines + Blank Lines

  • --code-vs-comments

    • Description: Show code vs comments ratio. Automatically enables --comments.
    • Example: locio --code-vs-comments

  • --rm-comments [EXTENSIONS]

    • Type: optional comma-separated extensions
    • Description: Remove comments from files (modifies files in place). Optionally specify file extensions to limit processing (e.g., js,ts,py). If no extensions specified, all supported files are processed.
    • Important:
      • This modifies files permanently - use with caution!
      • Certain file types are automatically ignored: .md, .json, .yaml, .csv, .html, .log, .lock, etc.
      • When --rm-comments is used, normal reporting is skipped and only comment removal messages are shown.
    • Examples:
      • locio --rm-comments (removes comments from all supported files)
      • locio --rm-comments ts,js (removes comments only from TypeScript and JavaScript files)
      • locio src --rm-comments py (removes comments from Python files in src directory)

Top Files and Directories ​

  • --top-files <N>

    • Type: integer
    • Description: Show top N largest files by size in the statistics output.
    • Example: locio --stats --top-files 10

  • --top-dirs <N>

    • Type: integer
    • Description: Show top N directories with most files in the statistics output.
    • Example: locio --stats --top-dirs 5

Watch Mode ​

  • -w, --watch

    • Description: Watch directory for changes and automatically rescan when files are modified, added, or deleted. Press Ctrl+C to stop.
    • Example: locio --watch

  • --watch-debounce <ms>

    • Type: integer (milliseconds)
    • Description: Set the debounce delay for watch mode. This controls how long LocIO waits after detecting a file change before rescanning. Default is 500ms. Minimum is 100ms, maximum is 5000ms.
    • Use when: You want to adjust the responsiveness of watch mode. Lower values make it more responsive but may cause more frequent scans. Higher values reduce scan frequency but increase delay.
    • Examples:
      • locio --watch --watch-debounce 1000 (1 second debounce)
      • locio --watch --watch-debounce 200 (200ms debounce for faster response)

Version ​

  • -v, --version
    • Description: Show version information and exit.
    • Example: locio --version

Configuration Files ​

LocIO can read default options from project configuration files so you don’t have to repeat long flag lists.

  • Supported locations (searched from the scan directory up to the filesystem root, in this order):
    1. .lociorc.json
    2. locio.config.json
    3. package.json → "locio" field
  • Precedence:
    • .lociorc.json overrides locio.config.json
    • locio.config.json overrides package.json["locio"]
    • CLI flags always override config file values

Example .lociorc.json ​

json
{
  "exclude_dirs": ["node_modules", "dist", "build"],
  "include_extensions": ["ts", "tsx"],
  "no_binary": true,
  "no_hidden": true,
  "stats": true,
  "export": "json,html",
  "duplicates": true
}

With this file in your project root you can simply run:

bash
locio .

LocIO will:

  • Scan . with the configured filters (exclude_dirs, include_extensions, etc.)
  • Enable --stats by default
  • Export both LocIO-report.json and LocIO-report.html
  • Run duplicate detection unless you override it on the CLI

Any CLI flag you pass (for example --no-duplicates or a different --export value) will win over the configuration file.

Monorepos, Workspaces, and Multi-Target Scans ​

LocIO understands multi-package repositories and can scan them efficiently.

Multiple directories ​

bash
# Scan two top-level packages and show combined stats
locio packages/core packages/web --stats

LocIO scans each directory separately and then:

  • Shows per-directory statistics
  • Shows a combined summary across all directories

Workspaces (--workspaces) ​

Use --workspaces to automatically discover workspace packages:

bash
# From the monorepo root
locio . --workspaces --stats

LocIO looks for:

  • package.json "workspaces" (npm / Yarn)
  • pnpm-workspace.yaml (pnpm)
  • lerna.json (Lerna)

and resolves each workspace directory that contains a package.json. Each package is scanned independently and combined into a single report.

Duplicate File Detection ​

LocIO can detect duplicate files by content to help you find copy-pasted code and redundant assets.

  • Flag: --duplicates
  • How it works:
    • Looks at all scanned files (within a safe cap)
    • Computes a content hash for each file
    • Groups files that have identical content
    • Sorts groups by “wasted lines”: lines × (number of copies - 1)

Example ​

bash
# Find duplicate files in the current project
locio . --stats --duplicates

In the output you’ll see:

  • Human / terminal: a “Duplicate Files” section listing groups, line counts, and file paths
  • JSON: a duplicate_groups array with hashes, sizes, line counts, and file lists
  • CSV/TSV: “Duplicate Files” section rows
  • Markdown/HTML: nicely formatted duplicate groups with file paths and wasted line counts

"LocIO: Count your code, not your worries."

Released under the MIT License.

Copyright © 2026 - LocIO