API Reference

Full reference documentation for ZigZag's CLI commands, flags, and configuration file.

Subcommands

Command	Description
zigzag init	Creates zig.conf.json with default values in the current directory. No-ops if the file already exists.
zigzag run	Loads zig.conf.json as the base config, then applies any CLI flags on top.

Without a subcommand, ZigZag applies CLI flags directly — no config file is loaded.

CLI Flags

General

Flag	Type	Default	Description
--version	bool	false	Show ZigZag version
--help	bool	false	Show help information
--log	bool	false	Enable logging

Input

Flag	Type	Default	Description
--path	string	—	Directory to scan. Can be specified multiple times for multi-path scanning
--ignore	string[]	[]	Pattern(s) to ignore. Same syntax as ignore_patterns in config

Output

Flag	Type	Default	Description
--output	string	"report.md"	Filename for the Markdown report
--output-dir	string	"zigzag-reports"	Directory to store generated reports
--json	bool	false	Generate a JSON report alongside Markdown
--html	bool	false	Generate an interactive HTML dashboard
--port	number	—	Port for serving the HTML dashboard
--open	bool	false	Automatically open the HTML report in a browser

LLM Reports

Flag	Type	Default	Description
--llm-report	bool	false	Enable LLM-optimized report generation
--llm-max-lines	number	150	Maximum number of lines per file in LLM reports
--llm-description	string	null	Optional project description included in LLM reports

Performance

Flag	Type	Default	Description
--skip-cache	bool	false	Skip cache operations and force a clean rebuild
--small	number	1048576	Threshold (bytes) below which files are read fully into memory
--mmap	number	16777216	Threshold (bytes) above which memory-mapped I/O is used
--watch	bool	false	Enable watch mode for real-time report updates
--timezone	string	null	Timezone offset for timestamps (e.g., "+1", "-5:30")

Configuration File

The zig.conf.json file maps directly to CLI flags. Create one with zigzag init:

{
  "paths": [],
  "ignore_patterns": [],
  "skip_cache": false,
  "skip_git": false,
  "small_threshold": 1048576,
  "mmap_threshold": 16777216,
  "timezone": null,
  "output": "report.md",
  "watch": false,
  "log": false,
  "json_output": false,
  "html_output": false,
  "output_dir": "zigzag-reports",
  "llm_report": false,
  "llm_max_lines": 150,
  "llm_description": null
}

Config Fields

Field	Type	Default	Description
paths	string[]	[]	Directories to scan
ignore_patterns	string[]	[]	Patterns to exclude from scanning
skip_cache	bool	false	Bypass the cache and rebuild from scratch
skip_git	bool	false	Skip .git directory detection
small_threshold	number	1048576	File size limit (bytes) for full in-memory reads
mmap_threshold	number	16777216	File size limit (bytes) for memory-mapped I/O
timezone	string|null	null	Timezone offset for report timestamps
output	string	"report.md"	Output filename for Markdown reports
watch	bool	false	Enable filesystem watch mode
log	bool	false	Enable logging output
json_output	bool	false	Generate JSON reports
html_output	bool	false	Generate HTML dashboards
output_dir	string	"zigzag-reports"	Output directory for all reports
llm_report	bool	false	Enable LLM-optimized reporting
llm_max_lines	number	150	Max lines per file in LLM reports
llm_description	string|null	null	Project description for LLM reports

Output Formats

Markdown Report

The default output. Each scanned directory gets a report.md containing:

• A header with the scanned path and generation timestamp
• A table of contents linking to every file
• Each file's metadata (size, language, last modified) followed by its syntax-highlighted source code

JSON Report

Enabled with --json. Written as report.json next to the Markdown file. Contains structured metadata: version info, summary statistics, per-file details (path, size, language, line count), and detected binary files.

HTML Dashboard

Enabled with --html. A single self-contained .html file with all assets bundled. Features summary cards, language charts, size distribution, sortable file table, source viewer with syntax highlighting, virtual scrolling for large files, and automatic dark mode.

File Reading Strategies

ZigZag automatically selects the optimal reading strategy based on file size:

File Size	Strategy	Description
0 – 1 MiB	readFileAlloc	Load entire file into memory
1 – 16 MiB	readFileMapped	Memory-mapped I/O (platform-specific)
> 16 MiB	readFileChunked	Stream in chunks

Thresholds are configurable with --small and --mmap flags.

Processing Pipeline

1. Argument Parsing — Parse CLI flags and configuration
2. Config File Loading — Apply zig.conf.json as base (when using run)
3. Cache Initialization — Load and validate cache, remove stale entries
4. Thread Pool Setup — Configure parallel workers based on CPU cores
5. Directory Traversal — Walk each specified path
6. File Filtering — Apply ignore patterns and binary detection
7. File Processing — Read, cache, and collect metadata in parallel
8. Report Generation — Generate outputs (Markdown, JSON, HTML)
9. Cleanup — Save cache, free resources

Statistics

After each run, ZigZag reports processing statistics in three categories:

Category	Description
Cached	Files read from cache (unchanged since last run)
Processed	Files that were read and processed (new or modified)
Ignored	Files excluded by patterns or binary detection