xmlq

xmlq

A pipe-friendly CLI for exploring and querying XML files. Built with Node.js/TypeScript.

Published on npm as @pvasek/xmlq.

Installation

npm install -g @pvasek/xmlq

Or run directly with npx:

npx @pvasek/xmlq <command> [options] [file]

Usage

All commands accept a file path or read from stdin when no file is given. Output goes to stdout, errors to stderr.

Commands

Command	Description
stat	Quick overview of an XML file (size, root, element count, namespaces)
tags	List all unique element names with occurrence counts
tree	Show the structural skeleton of the document
select	Query nodes using XPath expressions
first	Select first N matching nodes (shorthand for select --first)
count	Count matches for an XPath expression
text	Extract text content of matched nodes
attrs	List attributes of matched elements
fmt	Pretty-print or reformat XML
json	Convert XML to JSON
validate	Check if the file is well-formed XML
ns	List namespaces used in the document
schema	Infer a rough schema from the document

Global flags

Flag	Description
--help, -h	Show help
--version, -V	Show version
--no-color	Disable colored output
--ns PREFIX=URI	Register namespace prefix for XPath queries

Examples

# Get a quick overview of an XML file
xmlq stat data.xml

# See the structure
xmlq tree data.xml

# Find all unique element names
xmlq tags data.xml

# Query with XPath
xmlq select '//product[price > 100]' data.xml

# Peek at the first record
xmlq first '//product' data.xml

# Count matches
xmlq count '//product' data.xml

# Extract text values
xmlq text '//product/name' data.xml

# Convert to JSON and pipe to jq
xmlq json data.xml | jq '.catalog.product[0]'

# Pretty-print
xmlq fmt --indent 4 data.xml

# Validate
xmlq validate data.xml

# Pipe from stdin
curl -s https://example.com/feed.xml | xmlq first 3 '//item'

AI Agent Integration (Claude Code)

xmlq works with Claude Code — install the skill so Claude learns to use it automatically:

# 1. Install xmlq globally
npm install -g @pvasek/xmlq

# 2. In your project, install the skill
xmlq skill --install

This creates .claude/skills/xmlq/SKILL.md in your project. Claude Code discovers it and can then use xmlq to explore XML files on your behalf.

See SPEC.md for the full specification.

Development

Prerequisites

• Node.js >= 18
• npm

Setup

git clone https://github.com/pvasek/xmlq.git
cd xmlq
npm install

Build

npm run build        # compile TypeScript to dist/
npm run dev          # watch mode — recompile on changes

Run locally

node dist/index.js stat data.xml

# Or link globally for development
npm link
xmlq stat data.xml

Project structure

src/
├── index.ts               Entry point — CLI setup with commander
├── commands/
│   ├── stat.ts            Quick file overview
│   ├── tags.ts            List element names
│   ├── tree.ts            Structural skeleton
│   ├── select.ts          XPath query (core command)
│   ├── first.ts           First N matches shorthand
│   ├── count.ts           Count matches
│   ├── text.ts            Extract text content
│   ├── attrs.ts           List attributes
│   ├── fmt.ts             Pretty-print / reformat
│   ├── json.ts            XML to JSON conversion
│   ├── validate.ts        Well-formedness check
│   ├── ns.ts              List namespaces
│   └── schema.ts          Infer schema
└── utils/
    ├── input.ts           Read from file or stdin
    └── output.ts          TTY detection, output formatting

Each command file exports a register(program: Command): void function that adds its subcommand to the commander program.