mq

mq is a command-line tool written in Rust that lets you slice, filter, map, and transform Markdown documents using a jq-like syntax. It supports a variety of built-in functions and selectors, a REPL for interactive experimentation, and an IDE workflow via a VSCode extension and language server. Typical use cases include manipulating Markdown used in LLM prompts and outputs, generating structured Markdown content for LLM consumption, and performing content analysis or batch transformations across multiple files. To get started, install mq via one of the supported methods, then invoke mq with a query to filter or transform your Markdown data, or run mq -r to enter the REPL for interactive testing. The tool also supports combining commands, formatting, and extending functionality with custom subcommands.

Prerequisites:

• A supported OS (Linux, macOS, Windows) with internet access
• Basic shell environment (bash, zsh, or PowerShell)
• Optional: Docker if you prefer containerized execution

Install options:

1. Quick install (curl script):

curl -sSL https://mqlang.org/install.sh | bash

This downloads the latest mq binary to ~/.mq/bin and adds mq to your PATH.

2. Cargo (Rust toolchain required):

# Install from crates.io
cargo install mq-run
# Install from GitHub (example tag)
cargo install --git https://github.com/harehare/mq.git mq-run --tag v0.5.17
# Latest development version (optional)
cargo install --git https://github.com/harehare/mq.git mq-run --bin mq
# Install the debugger (optional)
cargo install --git https://github.com/harehare/mq.git mq-run --bin mq-dbg --features="debugger"
# Install using binstall (optional)
cargo binstall mq-run@0.5.17

3. Binaries (pre-built executables):

# macOS (Apple Silicon)
curl -L https://github.com/harehare/mq/releases/download/v0.5.17/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.17/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.17/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.17/mq-x86_64-pc-windows-msvc.exe -OutFile "$env:USERPROFILE\bin\mq.exe"

4. Docker (containerized):

docker run --rm ghcr.io/harehare/mq:0.5.17

5. mq-lsp (Language Server) and editors: follow the dedicated installation steps in the README for IDE support.

Note: Replace version numbers with the latest available release as needed.

Tips:

• If you plan to integrate mq into scripts or CI, using the binary or Docker image ensures consistent behavior across environments.
• The mq ecosystem includes a REPL (repl) for interactive experimentation and an debugger (mq-dbg) for stepping through queries.
• You can extend mq with custom subcommands by placing executables named mq-<subcommand> in ~/.mq/bin/.
• For LSP and editor support, install the mq language server and VSCode extension to get features like completion and diagnostics while editing mq queries.

Common issues:

• PATH issues after installation: ensure ~/.mq/bin is in your PATH (or the directory where mq is installed).
• Permission errors when using pre-built binaries: chmod +x the binary and retry.
• If using Docker, ensure you’re pulling a compatible architecture image for your host (e.g., linux/amd64 or linux/arm64).