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

Hidden, Empty, Binary, and Symlinks

--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
--no-gitignore
- Description: Do not apply nested .gitignore rules. LocIO still excludes .git metadata.
- Example: locio --no-gitignore --explain

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
--stdout <FORMAT>
- Type: exactly one of human | json | csv | tsv | markdown | html
- Description: Print the selected report directly to stdout. Operational messages move to stderr, keeping structured output pipe-safe.
- Details: May be combined with --export to print one format and write report files in the same run.
- Examples:
  - locio --stdout json | jq '.files'
  - locio --stdout csv > report.csv
  - locio --stdout json --export html
--explain
- Description: Include exclusion reason totals and up to 100 candidate-path examples.
- Reasons include: .gitignore, extension/name/path filters, size/depth limits, hidden/empty/binary files, unsafe paths, and unreadable files.
- Examples:
  - locio --explain
  - locio --stdout json --explain | jq '.exclusions'

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)
--dry-run
- Description: Preview which files --rm-comments would modify without writing anything.
- Requirement: Must be used with --rm-comments.
- Examples:
  - locio --rm-comments --dry-run
  - locio --rm-comments ts,tsx --dry-run

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

Project Configuration

--init
- Description: Create a starter .lociorc.json in the target directory.
- Safety: Refuses to overwrite an existing config.
- Example: locio . --init
--force
- Description: Allow --init to overwrite an existing .lociorc.json.
- Requirement: Must be used with --init.
- Example: locio . --init --force

Generated config:

json

{
  "exclude_dirs": ["node_modules", "dist", "build", "coverage"],
  "no_binary": true,
  "comments": true,
  "stats": true
}

The config also accepts dry_run, stdout, explain, and no_gitignore.

Exit Codes

LocIO uses stable codes for scripts and CI:

0 — completed successfully
1 — fatal error; no usable result
2 — partial result; one or more targets/files failed

Example:

bash

locio package-a missing-package --stdout json
case $? in
  0) echo "complete" ;;
  1) echo "fatal" ;;
  2) echo "partial result" ;;
esac

CLI Usage ​

Basic usage ​

Detailed Options Reference ​

Positional Arguments ​

Mode Flags ​

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

Size and Depth Control ​

Hidden, Empty, Binary, and Symlinks ​

Output and statistics ​

Matching Behavior and Noise Control ​

Comment Analysis ​

Top Files and Directories ​

Watch Mode ​

Version ​

Project Configuration ​

Exit Codes ​

Links ​