Mq
A jq-like Markdown query language for command-line processing
Install / Use
/learn @harehare/MqAbout this skill
Quality Score
0/100
Category
Development & EngineeringSupported Platforms
Claude Code
Cursor
README
<div align="center">
<img src="assets/logo.svg" style="width: 128px; height: 128px;"/>
</div>
<div align="center">
<a href="https://mqlang.org">Visit the site 🌐</a>
—
<a href="https://mqlang.org/book">Read the book 📖</a>
—
<a href="https://mqlang.org/playground">Playground 🎮</a>
</div>
<h1 align="center">mq</h1>
mq is a command-line tool that processes Markdown using a syntax similar to jq. It's written in Rust, allowing you to easily slice, filter, map, and transform structured data.
[!IMPORTANT] This project is under active development.
Why mq?
mq makes working with Markdown files as easy as jq makes working with JSON. It's especially useful for:
- LLM Workflows: Efficiently manipulate and process Markdown used in LLM prompts and outputs
- LLM Input Generation: Generate structured Markdown content optimized for LLM consumption, since Markdown serves as the primary input format for most language models
- Documentation Management: Extract, transform, and organize content across multiple documentation files
- Content Analysis: Quickly extract specific sections or patterns from Markdown documents
- Batch Processing: Apply consistent transformations across multiple Markdown files
Since LLM inputs are primarily in Markdown format, mq provides efficient tools for generating and processing the structured Markdown content that LLMs require.
Features
- Slice and Filter: Extract specific parts of your Markdown documents with ease.
- Map and Transform: Apply transformations to your Markdown content.
- Command-line Interface: Simple and intuitive CLI for quick operations.
- Extensibility: Easily extendable with custom functions.
- Built-in support: Filter and transform content with many built-in functions and selectors.
- REPL Support: Interactive command-line REPL for testing and experimenting.
- IDE Support: VSCode Extension and Language Server Protocol (LSP) support for custom function development.
- Debugger: Includes an experimental debugger (
mq-dbg) for inspecting and stepping through mq queries interactively. - External Subcommands: Extend mq with custom subcommands by placing executable files starting with
mq-in~/.mq/bin/.
Installation
Quick Install
curl -sSL https://mqlang.org/install.sh | bash
The installer will:
- Download the latest mq binary for your platform
- Install it to
~/.mq/bin/ - Update your shell profile to add mq to your PATH
Cargo
# Install from crates.io
cargo install mq-run
# Install from Github
cargo install --git https://github.com/harehare/mq.git mq-run --tag v0.5.24
# Latest Development Version
cargo install --git https://github.com/harehare/mq.git mq-run --bin mq
# Install the debugger
cargo install --git https://github.com/harehare/mq.git mq-run --bin mq-dbg --features="debugger"
# Install using binstall
cargo binstall mq-run@0.5.24
Binaries
You can download pre-built binaries from the GitHub releases page:
# macOS (Apple Silicon)
curl -L https://github.com/harehare/mq/releases/download/v0.5.24/mq-aarch64-apple-darwin -o /usr/local/bin/mq && chmod +x /usr/local/bin/mq
# Linux x86_64
curl -L https://github.com/harehare/mq/releases/download/v0.5.24/mq-x86_64-unknown-linux-gnu -o /usr/local/bin/mq && chmod +x /usr/local/bin/mq
# Linux arm64
curl -L https://github.com/harehare/mq/releases/download/v0.5.24/mq-aarch64-unknown-linux-gnu -o /usr/local/bin/mq && chmod +x /usr/local/bin/mq
# Windows (PowerShell)
Invoke-WebRequest -Uri https://github.com/harehare/mq/releases/download/v0.5.24/mq-x86_64-pc-windows-msvc.exe -OutFile "$env:USERPROFILE\bin\mq.exe"
Homebrew
# Using Homebrew (macOS and Linux)
brew install mq
Docker
$ docker run --rm ghcr.io/harehare/mq:0.5.24
mq-lsp (Language Server)
The mq Language Server provides IDE features like completion, hover, and diagnostics for mq query files.
Quick Install
curl -sSL https://mqlang.org/install_lsp.sh | bash
Cargo
# Install from crates.io
cargo install mq-lsp
# Install from Github
cargo install --git https://github.com/harehare/mq.git mq-lsp --tag v0.5.24
# Latest Development Version
cargo install --git https://github.com/harehare/mq.git mq-lsp
# Install using binstall
cargo binstall mq-lsp@0.5.24
Binaries
You can download pre-built binaries from the GitHub releases page:
# macOS (Apple Silicon)
curl -L https://github.com/harehare/mq/releases/download/v0.5.24/mq-lsp-aarch64-apple-darwin -o /usr/local/bin/mq-lsp && chmod +x /usr/local/bin/mq-lsp
# Linux x86_64
curl -L https://github.com/harehare/mq/releases/download/v0.5.24/mq-lsp-x86_64-unknown-linux-gnu -o /usr/local/bin/mq-lsp && chmod +x /usr/local/bin/mq-lsp
# Linux arm64
curl -L https://github.com/harehare/mq/releases/download/v0.5.24/mq-lsp-aarch64-unknown-linux-gnu -o /usr/local/bin/mq-lsp && chmod +x /usr/local/bin/mq-lsp
# Windows (PowerShell)
Invoke-WebRequest -Uri https://github.com/harehare/mq/releases/download/v0.5.24/mq-lsp-x86_64-pc-windows-msvc.exe -OutFile "$env:USERPROFILE\bin\mq-lsp.exe"
Visual Studio Code Extension
You can install the VSCode extension from the Visual Studio Marketplace.
Neovim
You can install the Neovim plugin by following the instructions in the mq.nvim README.
Zed
You can install the Zed extension by following the instructions in the zed-mq README.
GitHub Actions
You can use mq in your GitHub Actions workflows with the Setup mq action:
steps:
- uses: actions/checkout@v6
- uses: harehare/setup-mq@v1
- run: mq '.code' README.md
Language Bindings
Language bindings are available for the following programming languages:
Usage
For more detailed usage and examples, refer to the documentation.
For a comprehensive collection of practical examples, see the Example Guide.
Basic usage
<details> <summary>Complete list of options (click to show)</summary>Usage: mq [OPTIONS] [QUERY OR FILE] [FILES]... [COMMAND]
Commands:
repl Start a REPL session for interactive query execution
fmt Format mq files based on specified formatting options
help Print this message or the help of the given subcommand(s)
Arguments:
[QUERY OR FILE]
[FILES]...
Options:
-A, --aggregate
Aggregate all input files/content into a single array
-f, --from-file
load filter from the file
-I, --input-format <INPUT_FORMAT>
Set input format [possible values: markdown, mdx, html, text, null, raw]
-L, --directory <MODULE_DIRECTORIES>
Search modules from the directory
-M, --module-names <MODULE_NAMES>
Load additional modules from specified files
-m, --import-module-names <IMPORT_MODULE_NAMES>
Import modules by name, making them available as `name::fn()` in queries
--args <NAME> <VALUE>
Sets string that can be referenced at runtime
--rawfile <NAME> <FILE>
Sets file contents that can be referenced at runtime
--stream
Enable streaming mode for processing large files line by line
-F, --output-format <OUTPUT_FORMAT>
Set output format [default: markdown] [possible values: markdown, html, text, json, none]
-U, --update
Update the input markdown (aliases: -i, --in-place, --inplace)
--unbuffered
Unbuffered output
--list-style <LIST_STYLE>
Set the list style for markdown output [default: dash] [possible values: dash, plus, star]
--link-title-style <LINK_TITLE_STYLE>
Set the link title surround style for markdown output [default: double] [possible values: double, single, paren]
--link-url-style <LINK_URL_STYLE>
Set the link URL surround style for markdown links [default: none] [possible values: none, angle]
-S, --separator <QUERY>
Specify a query to insert between files as a separator
-o, --output <FILE>
Output to the specified file
-C, --color-output
Colorize markdown output
--list
List all available subcommands (built-in and external)
-P <PARALLEL_THRESHOLD>
Number of files to process before switching to parallel processing [default: 10]
-h, --help
Print help
-V, --version
Print version
# Examples:
## To filter markdown nodes:
mq 'query' file.md
## To read query from file:
mq -f 'file' file.md
#
