Get Started

This guide walks you through installing LocIO, running your first counts, and using a few common CLI patterns.

What's in a name?

LocIO combines:

Loc → Lines Of Code (industry-standard abbreviation)
IO → input/output or interface/system (common tech suffix)

So LocIO ≈ "lines-of-code I/O / system" — a tool that handles the input/output of counting your code.

1. Install LocIO

You can either run LocIO via npx (recommended) or install it globally.

Run with npx (no global install)

bash

npx locio@latest

This will download and run the latest LocIO release without adding anything permanent to your global PATH.

Install globally with npm

bash

npm install -g locio

After installation, verify it worked:

bash

locio --help
locio --version

2. Your first count

From any project directory, run:

bash

locio

This:

Scans the current directory recursively
Shows an interactive home page when run without arguments
Lets you explore basic stats quickly

To analyze a specific directory or file:

bash

# Analyze a directory
locio /path/to/directory

# Analyze a single file
locio ./src/index.ts
locio /path/to/file.js

Interactive Home Page

When you run locio without any arguments in an interactive terminal, LocIO displays a friendly interactive menu with the following options:

Quick scan of current directory (default settings) - Runs a scan immediately with default settings
Show common command examples - Displays helpful command examples
View full help (same as --help) - Shows the complete CLI help documentation
Quit - Exits the program

This interactive mode is perfect for first-time users or when you want to quickly explore what LocIO can do. If you're running LocIO in a non-interactive environment (like a script or CI), it will skip the interactive menu and run a scan directly.

3. Automatic project type detection

LocIO automatically detects your project type when scanning a directory. This helps provide better context and can automatically apply project-specific exclusions.

Supported project types

LocIO can detect the following project types:

Node.js - Detected via package.json
TypeScript - Detected via tsconfig.json or TypeScript files
React - Detected via React dependencies or JSX files
Vue - Detected via Vue config files or dependencies
Angular - Detected via angular.json or Angular CLI
Next.js - Detected via next.config.js or Next.js dependencies
Rust - Detected via Cargo.toml or Cargo.lock
Python - Detected via requirements.txt, setup.py, pyproject.toml, etc.
Go - Detected via go.mod or go.sum
Java - Detected via pom.xml or build.gradle
C# - Detected via .csproj or .sln files
Ruby - Detected via Gemfile or Rakefile
PHP - Detected via composer.json or artisan
Swift - Detected via Package.swift or Xcode project files
Kotlin - Detected via build.gradle.kts
Dart - Detected via pubspec.yaml

How it works

When you run LocIO on a directory, it:

Scans for project indicators - Looks for configuration files, dependencies, and project structure
Detects the project type - Uses a scoring system to identify the most likely project type
Displays the detection - Shows the detected project type in the output (e.g., "Detected project type: Node.js")
Applies auto-excludes automatically - Automatically excludes common build directories and files based on the detected project type

For example:

Node.js projects automatically exclude: node_modules, .next, dist, build, etc.
Rust projects automatically exclude: target, .cargo, Cargo.lock
Python projects automatically exclude: __pycache__, .venv, venv, .pytest_cache, etc.

These auto-excludes are merged with any manual excludes you specify, so you don't need to manually exclude common build artifacts for your project type.

Example output

bash

$ locio .

Detected project type: Node.js

📊 Summary
  Files: 142
  Lines: 8,234
  ...

The project type detection helps you understand what kind of project you're analyzing and can guide you in choosing appropriate filters and exclusions.

4. Focus on specific file types

Use --include-ext to limit the scan to certain extensions. Dots are optional (ts and .ts both work):

bash

# Only TypeScript files
locio --include-ext ts --stats

# TypeScript and JavaScript
locio --include-ext ts,tsx,js --stats

You can combine this with --stats to get a detailed breakdown by language, extension, and directory.

5. Exclude noise (logs, dependencies, etc.)

For real projects, you usually want to exclude logs and dependency folders:

bash

locio . \
  --exclude ".*\\.log$" \
  --exclude-dir node_modules \
  --stats

--exclude filters by full file path using a regular expression
--exclude-dir skips entire directories whose path matches the pattern

6. Control file size and binary files

Skip large or binary files to keep counts meaningful:

bash

locio --max-size 5MB --no-binary --stats

This:

Ignores files larger than 5MB
Skips binary files (when --no-binary is used)

7. Export results

Use structured formats to pipe results into other tools. You can either redirect output yourself or use --export to let LocIO write the report file for you.

bash

# JSON
locio --stats --export json             # writes LocIO-report.json

# CSV
locio --stats --export csv              # writes LocIO-report.csv

# TSV
locio --stats --export tsv              # writes LocIO-report.tsv

# Markdown
locio --stats --export markdown         # writes LocIO-report.md

# HTML
locio --stats --export html             # writes LocIO-report.html

# Multiple formats at once
locio --stats --export json,html,markdown

# Custom output directory
locio --stats --export json --export-path ./reports

Export Format Details:

All formats include complete line breakdown: Code Lines, Comment Lines, and Blank Lines
JSON exports include blank_lines in summary and both by_extension and by_language statistics
CSV/TSV exports include:
- An extension table
- A language breakdown section
Markdown exports show:
- A summary table
- A Statistics by Language table
- A Statistics by Extension table
HTML exports display:
- Summary cards (files, size, lines, comments, blanks)
- A language bar chart and table
- An extension chart and table
- A directory structure graph
- An interactive treemap (zoomable, color-coded by language, with tooltips)
All exports include a Files by Directory section with file-level details

These files can be loaded into dashboards, spreadsheets, or analysis scripts.

8. Common workflows

Analyze a TypeScript project

bash

locio . --include-ext ts --stats

Analyze a TypeScript/JavaScript monorepo

bash

locio . \
  --include-ext ts,tsx,js \
  --exclude-dir node_modules,dist,build \
  --stats

Analyze all workspaces in a monorepo

From the monorepo root (where package.json or pnpm-workspace.yaml lives):

bash

# Auto-detect npm/Yarn/pnpm/Lerna workspaces and scan each package
locio . --workspaces --stats

LocIO will:

Discover workspace package directories
Scan each workspace independently
Produce a combined report (with per-directory and overall statistics)

Generate a JSON report for CI

bash

locio . --stats --export json    # writes LocIO-report.json

Analyze comments in your codebase

bash

# Comment analysis is enabled by default, showing code, comments, and blank lines
locio . --stats

# Show code vs comments ratio
locio . --code-vs-comments --stats

# Disable comment analysis if you only need total line counts
locio . --no-comments

Note: By default, LocIO shows a complete breakdown:

Code Lines: Lines containing actual code
Comment Lines: Lines containing comments (full-line and inline)
Blank Lines: Empty lines (always included in totals)

The formula is: Total Lines = Code Lines + Comment Lines + Blank Lines

Blank lines are always included in the total line count and shown in all output formats (console, JSON, CSV, TSV, Markdown, HTML).

Remove comments from code files

bash

# Remove comments from all supported files
locio . --rm-comments

# Remove comments only from TypeScript files
locio . --rm-comments ts

# Remove comments from multiple file types
locio . --rm-comments js,ts,py

Note: The --rm-comments flag automatically ignores documentation and config files (.md, .json, .yaml, .csv, .html, etc.) to prevent accidental modification.

Watch for changes

bash

# Automatically rescan when files change
locio . --watch

# Adjust watch debounce delay (default: 500ms)
locio . --watch --watch-debounce 1000  # 1 second delay

Watch Mode Features:

Automatically rescans when files are modified, added, or deleted
Shows changed files before rescanning
Configurable debounce delay with --watch-debounce <ms> (default: 500ms, min: 100ms, max: 5000ms)
Press Ctrl+C to stop watching

Get Started ​

What's in a name? ​

1. Install LocIO ​

Run with npx (no global install) ​

Install globally with npm ​

2. Your first count ​

Interactive Home Page ​

3. Automatic project type detection ​

Supported project types ​

How it works ​

Example output ​

4. Focus on specific file types ​

5. Exclude noise (logs, dependencies, etc.) ​

6. Control file size and binary files ​

7. Export results ​

8. Common workflows ​

Analyze a TypeScript project ​

Analyze a TypeScript/JavaScript monorepo ​

Analyze all workspaces in a monorepo ​

Generate a JSON report for CI ​

Analyze comments in your codebase ​

Remove comments from code files ​

Watch for changes ​

Links ​

Get Started

What's in a name?

1. Install LocIO

Run with npx (no global install)

Install globally with npm

2. Your first count

Interactive Home Page

3. Automatic project type detection

Supported project types

How it works

Example output

4. Focus on specific file types

5. Exclude noise (logs, dependencies, etc.)

6. Control file size and binary files

7. Export results

8. Common workflows

Analyze a TypeScript project

Analyze a TypeScript/JavaScript monorepo

Analyze all workspaces in a monorepo

Generate a JSON report for CI

Analyze comments in your codebase

Remove comments from code files

Watch for changes

Links