CLI Reference

Invocation

lsw [options]

When running directly from a source checkout, python lsw.py [options] is equivalent.

The graphical launcher is included in the PyPI package:

py -m pip install lsw-directory-walker
lsw --gui

For a local checkout, use py -m pip install . instead.

The GUI is a one-shot desktop window. It collects scan settings, runs the same generation functions as the CLI, opens an HTML result unless disabled, and closes after a successful export. The plain lsw command remains CLI-first and does not open a window.

See the full Graphical Launcher guide for the layout, filter behavior, progress state, and standalone HTML workflow.

See stdout and stderr integration for application, AI-tool, and pipeline patterns.

--path is the directory to scan and defaults to the current working directory. Relative paths are resolved by the operating system from the shell's current directory.

Options at a glance

Detailed argument reference

Each option below includes a command you can run from the repository root. Replace paths and names with values from your project.

--path

Sets the directory to scan. It defaults to .. The path may be absolute or relative to the shell's current directory.

python lsw.py --path .\src
python lsw.py --path "C:\Projects\website" --type json --out website.json

--preset / -p

Loads a preset from lsw-presets/<name>.json. The available names are shown by python lsw.py --help.

python lsw.py --preset source-only --path .
python lsw.py -p large-files --path . --out large.csv

Only the preset's args object is applied. See Configuration and presets for precedence details.

--ext

Accepts comma-separated extensions and keeps matching files, such as .py,.js,.ts. Include the leading dot. Matching is case-sensitive.

python lsw.py --path . --ext .py,.pyi --type json --out python-files.json

This filter is applied to HTML and structured exports. It currently has no effect in the TXT branch.

--ignore

Excludes exact entry names. For directories, the matching directory is not traversed.

python lsw.py --path . --ignore node_modules,.git,__pycache__

--ignore-pattern

Adds comma-separated fnmatch glob patterns. Patterns match entry names, not full relative paths.

python lsw.py --path . --ignore-pattern "*.min.js,*.map,*.tmp" --type html

--ignore-regex

Adds one or more comma-separated regular expressions. A name is ignored when any expression searches successfully.

python lsw.py --path . --ignore-regex "^test_.*,.*\\.generated\\.py$" --type json

--include

Restricts the scan root to named child directories. Root-level files are skipped when this option is present.

python lsw.py --path . --include src,tests --type markdown --out selected.md

Nested directories are still traversed inside the selected root directories.

--include-pattern

Whitelists files matching at least one comma-separated glob pattern.

python lsw.py --path . --include-pattern "*.py,*.pyi" --type csv --out python.csv

--include-regex

Whitelists files matching at least one regular expression.

python lsw.py --path . --include-regex "^(main|test).*\\.(py|js)$" --type json

Because matching is performed against entry names rather than full relative paths, use --include for root-directory selection and use this option for filename selection.

--max-depth

Limits recursion. The scan root starts at depth 0; --max-depth 1 lists root-level entries without enumerating their children.

python lsw.py --path . --max-depth 2 --type txt --out shallow-tree.txt

--min-size

Includes files at or above a size threshold. Supported units are B, KB, MB, GB, and TB.

python lsw.py --path . --min-size 5MB --type csv --out files-over-5mb.csv

--max-size

Includes files at or below a size threshold.

python lsw.py --path . --max-size 100KB --type jsonl --out small-files.jsonl

Combine both size options for a range:

python lsw.py --path . --min-size 10KB --max-size 1MB --type markdown

--modified-after

Includes files modified at or after a local date or timestamp.

python lsw.py --path . --modified-after 2026-08-01 --type json
python lsw.py --path . --modified-after "2026-08-01 09:30:00" --type csv

--modified-before

Includes files modified at or before a local date or timestamp.

python lsw.py --path . --modified-before 2026-08-20 --type markdown --out before.md
python lsw.py --path . --modified-after 2026-08-01 --modified-before 2026-08-20

--out

Sets the output filename. LSW changes the suffix to match --type when necessary.

python lsw.py --path . --type csv --out reports\inventory.csv
python lsw.py --path . --type html --out reports\tree

The parent directory must already exist.

--stdout

Prints generated output to the terminal while still saving the file specified by --out. This is supported for HTML, TXT, CSV, JSON, JSONL, and Markdown, and is useful when another application or shell pipeline needs to consume the result immediately.

lsw --path . --type json --stdout --out inventory.json
lsw --path . --type csv --stdout --out inventory.csv
lsw --path . --type txt --stdout --out tree.txt

When --stdout is active, save-status messages go to stderr so stdout contains only the selected output format.

--stdout-only

Prints the generated output to stdout without creating the output file. This is the cleanest mode for applications that only need the result in memory or a pipeline.

lsw --path . --type json --stdout-only

--stdout-only implies --stdout; the difference is that --stdout also saves a file while --stdout-only does not. Both modes support HTML, TXT, CSV, JSON, JSONL, and Markdown. For JSON, stdout contains one complete JSON document and no status messages. For JSONL, it contains one JSON object per line. Errors and diagnostic messages are sent to stderr.

Data flow for applications

LSW uses the conventional process streams:

scanned directory
	|
	v
LSW filters and serializes the result
	|------------------------------|
	v                              v
stdout: output data              stderr: status/errors
	|                              |
	v                              v
your app parses JSON/text       your app logs or displays diagnostics

JSON example

PowerShell:

$json = lsw --path . --type json --stdout-only | ConvertFrom-Json

Python:

import json
import subprocess

result = subprocess.run(
    ["lsw", "--path", folder, "--type", "json", "--stdout-only"],
    capture_output=True,
    text=True,
    check=True,
)
items = json.loads(result.stdout)

With --stdout, the same serialized bytes go to stdout and a file is also written. With --stdout-only, no output file is opened or created. Status messages belong on stderr so they do not corrupt machine-readable stdout.

--type

Selects the output format: html, txt, csv, json, jsonl, or markdown.

python lsw.py --path . --type html --out report.html
python lsw.py --path . --type txt --out tree.txt --no-browser
python lsw.py --path . --type jsonl --out inventory.jsonl

--group

Controls HTML grouping: none keeps the expandable tree, type groups by extension, and prefix groups by the text before the first underscore.

python lsw.py --path . --type html --group type --out by-type.html
python lsw.py --path . --type html --group prefix --out by-prefix.html

The option does not affect TXT or structured exports.

--no-browser

Prevents LSW from opening the generated HTML file. It has no practical effect for non-HTML output.

python lsw.py --path . --type html --no-browser --out report.html

--txt-icons

Adds Unicode MIME icons to TXT tree entries. It is disabled by default.

python lsw.py --path . --type txt --txt-icons --out tree-with-icons.txt

--parallel

Requests parallel scanning. This flag is accepted for compatibility with the intended design, but the current implementation does not use it to create worker tasks.

python lsw.py --path . --parallel --workers 8

--no-parallel

Requests synchronous scanning. The current implementation is already synchronous, and this flag currently does not change behavior.

python lsw.py --path . --no-parallel --type json

--workers

Sets the requested worker count for parallel scanning. It is parsed and retained, but is currently unused because scanning is synchronous.

python lsw.py --path . --parallel --workers 8 --type csv --out inventory.csv

Size syntax

Accepted units are B, KB, MB, GB, and TB, using binary multiples: 1\,KB = 1024 bytes. Decimal values are accepted, for example 1.5MB. A bare number is interpreted as bytes.

Date syntax

Supported forms are:

YYYY-MM-DD
YYYY-MM-DD HH:MM:SS

Dates use the local timezone through Python's datetime.timestamp() conversion. An invalid date stops execution with an error message.

Examples

# HTML report for a source tree
python lsw.py --path . --ext .py,.js,.ts --ignore node_modules --out source.html

# Plain text tree with icons
python lsw.py --path . --type txt --txt-icons --out tree.txt

# Largest files as CSV
python lsw.py --path . --min-size 5MB --type csv --out large.csv

# Files changed in a time window
python lsw.py --path . --modified-after "2026-08-01" --modified-before "2026-08-20" --type json

# Only the root-level source and test folders
python lsw.py --path . --include src,test --type markdown --out selected.md

Exit and error behavior

Invalid preset names, malformed preset JSON, invalid ignore/include regexes, and invalid dates print an error and exit with status 1. Individual unreadable files and directories are generally skipped; HTML and text generation may emit [Permission Denied] where appropriate.