@lanexio/parser-cli

This page documents @lanexio/parser-cli, the command-line interface for parsing files, running LexQuery patterns, and serializing parse trees.

• Version: Stable
• Module name: parser-cli
• Package: @lanexio/parser-cli
• Import path: @lanexio/parser-cli
• Layer: 6 (CLI)
• Runtime: Node.js only
• Module format: ESM
• Stability: Stable
• Primary use case: Parse, query, and serialize files from the command line.

Layer contract

Layer 6 dependency rules

@lanexio/parser-cli is Node.js only and wraps Layers 1-4 for command-line use.

When to use this module

• You want to parse files from the command line without writing code.
• You want to run LexQuery patterns on files from the terminal.
• You want to serialize parsed files back to their source format.

Module boundary

Boundary	Description
Inputs	Command-line arguments, stdin
Outputs	stdout (tree, JSON, serialized output)
Side effects	File I/O, stdout writes
Determinism	Yes (same input produces same output)
External dependencies	@lanexio/parser-core, @lanexio/parser-grammar-html, @lanexio/parser-grammar-markdown, @lanexio/parser-query
Never-throw guarantee	No: exits with code 1 on fatal errors. Parse operations within a grammar are never-throw.
Security surface	None (processes local files)

Installation

pnpm add -g @lanexio/parser-cli

The CLI is available as both lanexio-parser and parser:

lanexio-parser parse index.html
parser parse index.html

Basic Usage

Parse a file

parser parse index.html
parser parse README.md --output json

Run a query

parser query Element index.html
parser query "Element, Text" --grammar html --output json < input.html

Serialize

parser serialize index.html
parser serialize --grammar markdown README.md

Exports

Export	Type	Description
LANEXIO_PARSER_CLI_PACKAGE_NAME	string	Stable npm package name constant.
CLI_VERSION	string	The current package version (read from package.json).
validateEncoding	(label: string) => string | null	Validates a WHATWG encoding label.
decode	(bytes: Uint8Array, encoding: string) => string	Decodes bytes using the given encoding.

The CLI binary (dist/bin.js) is the primary interface.

Options

Global flags

These flags work with any subcommand:

Flag	Description
--version	Print the CLI version and exit. Overrides the subcommand.
--quiet	Suppress stderr diagnostic output. Useful in scripting.
--help	Show help for the subcommand.

parse subcommand

Flag	Values	Default	Description
--grammar	html, markdown, auto	auto	Grammar to use. auto infers from file extension.
--output	tree, json	tree	Output format. tree prints indented text; json prints serialized tree.
--encoding	WHATWG label	utf-8	Input file encoding.

query subcommand

Flag	Values	Default	Description
--grammar	html, markdown, auto	auto	Grammar to use.
--output	text, json	text	Output format.
--encoding	WHATWG label	utf-8	Input file encoding.

serialize subcommand

Flag	Values	Default	Description
--grammar	html, markdown, auto	auto	Grammar to use.

Exit codes

Code	Meaning
0	Success. A tree was produced, even if it contains LexError nodes.
1	System error (file not found, I/O failure).
2	Argument misuse (missing argument, unknown flag, invalid grammar, invalid encoding).

Configuration and Extension

Grammar auto-detection

When --grammar auto (default), the grammar is inferred from file extension using the shared grammar registry. All registered grammar packages are available:

Extension	Grammar
.html, .htm	html
.md, .markdown	markdown

The registry is extensible: when new grammar packages are added to the workspace, the CLI automatically detects them without code changes. Use --grammar to force a specific grammar for files with ambiguous or unsupported extensions.

When reading from stdin, --grammar is required (no file extension to infer from).

-- separator

Per POSIX convention, the -- token separates flags from positional arguments. Everything after -- is treated as a file path or argument, even if it looks like a flag:

parser parse -- some-file.html --output json
# --output and json are treated as part of the filename (warning: file likely not found)

Stdin

echo '<p>Hello</p>' | parser parse --grammar html
cat index.html | parser parse --grammar html --output json

Accessibility

Accessibility requirements

• No direct accessibility surface. The CLI produces text output for terminal use.

Accessibility checklist

Concern	Status
Generated output semantics	Not applicable (terminal output)
ARIA attributes in serialized output	Not applicable
Semantic element round-trip	Not applicable

Security

Security considerations

• The CLI reads files from the local filesystem. It does not execute remote code.
• Parse operations within recognized grammars are never-throw.

Threat	Mitigation	Status
Malformed input file	Grammar parse functions never throw. CLI exits 0 with error nodes in tree.	Implemented
Grammar not recognized	Exits with code 2 and clear error message.	Implemented

Companion packages

Package	Relationship	Layer	Notes
@lanexio/parser-core	Requires	1	Core tree and protocol
@lanexio/parser-grammar-html	Requires	2	HTML grammar for CLI
@lanexio/parser-grammar-markdown	Requires	2	Markdown grammar for CLI
@lanexio/parser-query	Requires	3	LexQuery for query subcommand

Changelog

Version	Date	Status	Notable changes
1.0.0	2026-05-29	Current	Initial stable release. Apache-2.0.

Migration notes

• None.

Known limitations

• Query selectors are kind names, not CSS selectors.
• No --include-errors flag. The parse --output json format includes hasError per node.
• Markdown serialization is available and functional (MD-S4).
• Multi-file glob patterns and streaming parse for large inputs are not yet supported.

Related Content

CLI Guide: command-line usage of parser parse, query, and serialize.

LexQuery Pattern-based tree queries with LexQuery.

Stability Guarantees Never-throw, panic-free, and 3-token recovery.