{"id":25952048,"url":"https://github.com/harehare/mq","last_synced_at":"2026-02-19T15:04:53.192Z","repository":{"id":279237561,"uuid":"938149101","full_name":"harehare/mq","owner":"harehare","description":"jq-like command-line tool for markdown processing","archived":false,"fork":false,"pushed_at":"2026-01-20T20:10:31.000Z","size":12021,"stargazers_count":275,"open_issues_count":4,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-20T21:40:28.449Z","etag":null,"topics":["cli","interpreter","jq","language-server","markdown","mcp","md","query","repl","rust","tui"],"latest_commit_sha":null,"homepage":"https://mqlang.org","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harehare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-02-24T13:55:22.000Z","updated_at":"2026-01-20T15:14:57.000Z","dependencies_parsed_at":"2025-02-24T15:25:07.686Z","dependency_job_id":"2a546887-66b0-4964-b31f-eaf4a7da86c0","html_url":"https://github.com/harehare/mq","commit_stats":null,"previous_names":["harehare/mdq","harehare/mq"],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/harehare/mq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fmq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fmq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fmq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fmq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harehare","download_url":"https://codeload.github.com/harehare/mq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fmq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28755045,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T13:59:49.818Z","status":"ssl_error","status_checked_at":"2026-01-25T13:59:33.728Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","interpreter","jq","language-server","markdown","mcp","md","query","repl","rust","tui"],"created_at":"2025-03-04T14:32:48.597Z","updated_at":"2026-02-19T15:04:53.184Z","avatar_url":"https://github.com/harehare.png","language":"Rust","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.svg\" style=\"width: 128px; height: 128px;\"/\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://mqlang.org\"\u003eVisit the site 🌐\u003c/a\u003e\n  \u0026mdash;\n  \u003ca href=\"https://mqlang.org/book\"\u003eRead the book 📖\u003c/a\u003e\n  \u0026mdash;\n  \u003ca href=\"https://mqlang.org/playground\"\u003ePlayground 🎮\u003c/a\u003e\n\u003c/div\u003e\n\n\u003ch1 align=\"center\"\u003emq\u003c/h1\u003e\n\n[![ci](https://github.com/harehare/mq/actions/workflows/ci.yml/badge.svg)](https://github.com/harehare/mq/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/harehare/mq/graph/badge.svg?token=E4UD7Q9NC3)](https://codecov.io/gh/harehare/mq)\n[![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json?style=for-the-badge)](https://codspeed.io/harehare/mq)\n[![audit](https://github.com/harehare/mq/actions/workflows/audit.yml/badge.svg)](https://github.com/harehare/mq/actions/workflows/audit.yml)\n[![GitHub Release](https://img.shields.io/github/v/release/harehare/mq)](https://github.com/harehare/mq/releases)\n[![Crates.io](https://img.shields.io/crates/v/mq-lang)](https://crates.io/crates/mq-lang)\n[![npm](https://img.shields.io/npm/v/mq-web)](https://www.npmjs.com/package/mq-web)\n\nmq is a command-line tool that processes Markdown using a syntax similar to jq.\nIt's written in Rust, allowing you to easily slice, filter, map, and transform structured data.\n\n![demo](assets/demo.gif)\n\n\u003e [!IMPORTANT]\n\u003e This project is under active development.\n\n## Why mq?\n\nmq makes working with Markdown files as easy as jq makes working with JSON. It's especially useful for:\n\n- **LLM Workflows**: Efficiently manipulate and process Markdown used in LLM prompts and outputs\n- **LLM Input Generation**: Generate structured Markdown content optimized for LLM consumption, since Markdown serves as the primary input format for most language models\n- **Documentation Management**: Extract, transform, and organize content across multiple documentation files\n- **Content Analysis**: Quickly extract specific sections or patterns from Markdown documents\n- **Batch Processing**: Apply consistent transformations across multiple Markdown files\n\nSince LLM inputs are primarily in Markdown format, mq provides efficient tools for generating and processing the structured Markdown content that LLMs require.\n\n## Features\n\n- **Slice and Filter**: Extract specific parts of your Markdown documents with ease.\n- **Map and Transform**: Apply transformations to your Markdown content.\n- **Command-line Interface**: Simple and intuitive CLI for quick operations.\n- **Extensibility**: Easily extendable with custom functions.\n- **Built-in support**: Filter and transform content with many built-in functions and selectors.\n- **REPL Support**: Interactive command-line REPL for testing and experimenting.\n- **IDE Support**: VSCode Extension and Language Server **Protocol** (LSP) support for custom function development.\n- **Debugger**: Includes an experimental debugger (`mq-dbg`) for inspecting and stepping through mq queries interactively.\n- **External Subcommands**: Extend mq with custom subcommands by placing executable files starting with `mq-` in `~/.mq/bin/`.\n\n## Installation\n\n### Quick Install\n\n```bash\ncurl -sSL https://mqlang.org/install.sh | bash\n```\n\nThe installer will:\n\n- Download the latest mq binary for your platform\n- Install it to `~/.mq/bin/`\n- Update your shell profile to add mq to your PATH\n\n### Cargo\n\n```sh\n# Install from crates.io\ncargo install mq-run\n# Install from Github\ncargo install --git https://github.com/harehare/mq.git mq-run --tag v0.5.16\n# Latest Development Version\ncargo install --git https://github.com/harehare/mq.git mq-run --bin mq\n# Install the debugger\ncargo install --git https://github.com/harehare/mq.git mq-run --bin mq-dbg --features=\"debugger\"\n# Install using binstall\ncargo binstall mq-run@0.5.16\n```\n\n### Binaries\n\nYou can download pre-built binaries from the [GitHub releases page](https://github.com/harehare/mq/releases):\n\n```sh\n# macOS (Apple Silicon)\ncurl -L https://github.com/harehare/mq/releases/download/v0.5.16/mq-aarch64-apple-darwin -o /usr/local/bin/mq \u0026\u0026 chmod +x /usr/local/bin/mq\n# Linux x86_64\ncurl -L https://github.com/harehare/mq/releases/download/v0.5.16/mq-x86_64-unknown-linux-gnu -o /usr/local/bin/mq \u0026\u0026 chmod +x /usr/local/bin/mq\n# Linux arm64\ncurl -L https://github.com/harehare/mq/releases/download/v0.5.16/mq-aarch64-unknown-linux-gnu -o /usr/local/bin/mq \u0026\u0026 chmod +x /usr/local/bin/mq\n# Windows (PowerShell)\nInvoke-WebRequest -Uri https://github.com/harehare/mq/releases/download/v0.5.16/mq-x86_64-pc-windows-msvc.exe -OutFile \"$env:USERPROFILE\\bin\\mq.exe\"\n```\n\n### Homebrew\n\n```sh\n# Using Homebrew (macOS and Linux)\nbrew install mq\n```\n\n### Docker\n\n```sh\n$ docker run --rm ghcr.io/harehare/mq:0.5.16\n```\n\n### mq-lsp (Language Server)\n\nThe mq Language Server provides IDE features like completion, hover, and diagnostics for mq query files.\n\n#### Quick Install\n\n```bash\ncurl -sSL https://mqlang.org/install_lsp.sh | bash\n```\n\n#### Cargo\n\n```sh\n# Install from crates.io\ncargo install mq-lsp\n# Install from Github\ncargo install --git https://github.com/harehare/mq.git mq-lsp --tag v0.5.16\n# Latest Development Version\ncargo install --git https://github.com/harehare/mq.git mq-lsp\n# Install using binstall\ncargo binstall mq-lsp@0.5.16\n```\n\n#### Binaries\n\nYou can download pre-built binaries from the [GitHub releases page](https://github.com/harehare/mq/releases):\n\n```sh\n# macOS (Apple Silicon)\ncurl -L https://github.com/harehare/mq/releases/download/v0.5.16/mq-lsp-aarch64-apple-darwin -o /usr/local/bin/mq-lsp \u0026\u0026 chmod +x /usr/local/bin/mq-lsp\n# Linux x86_64\ncurl -L https://github.com/harehare/mq/releases/download/v0.5.16/mq-lsp-x86_64-unknown-linux-gnu -o /usr/local/bin/mq-lsp \u0026\u0026 chmod +x /usr/local/bin/mq-lsp\n# Linux arm64\ncurl -L https://github.com/harehare/mq/releases/download/v0.5.16/mq-lsp-aarch64-unknown-linux-gnu -o /usr/local/bin/mq-lsp \u0026\u0026 chmod +x /usr/local/bin/mq-lsp\n# Windows (PowerShell)\nInvoke-WebRequest -Uri https://github.com/harehare/mq/releases/download/v0.5.16/mq-lsp-x86_64-pc-windows-msvc.exe -OutFile \"$env:USERPROFILE\\bin\\mq-lsp.exe\"\n```\n\n### Visual Studio Code Extension\n\nYou can install the VSCode extension from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=harehare.vscode-mq).\n\n### Neovim\n\nYou can install the Neovim plugin by following the instructions in the [mq.nvim README](https://github.com/harehare/mq/blob/main/editors/neovim/README.md).\n\n### Zed\n\nYou can install the Zed extension by following the instructions in the [zed-mq README](https://github.com/harehare/mq/blob/main/editors/zed/README.md).\n\n### GitHub Actions\n\nYou can use mq in your GitHub Actions workflows with the [Setup mq](https://github.com/marketplace/actions/setup-mq) action:\n\n```yaml\nsteps:\n  - uses: actions/checkout@v5\n  - uses: harehare/setup-mq@v1\n  - run: mq '.code' README.md\n```\n\n## Language Bindings\n\nLanguage bindings are available for the following programming languages:\n\n- [mq_elixir](https://github.com/harehare/mq_elixir)\n- [mq-python](https://github.com/harehare/mq/blob/main/crates/mq-python)\n- [mq-ruby](https://github.com/harehare/mq-ruby)\n\n## Usage\n\nFor more detailed usage and examples, refer to the [documentation](https://mqlang.org/book/).\n\nFor a comprehensive collection of practical examples, see the [Example Guide](https://mqlang.org/book/start/example/).\n\n### Basic usage\n\n\u003cdetails\u003e\n\u003csummary\u003eComplete list of options (click to show)\u003c/summary\u003e\n\n```sh\nUsage: mq [OPTIONS] [QUERY OR FILE] [FILES]... [COMMAND]\n\nCommands:\n  repl  Start a REPL session for interactive query execution\n  fmt   Format mq files based on specified formatting options\n  help  Print this message or the help of the given subcommand(s)\n\nArguments:\n  [QUERY OR FILE]  \n  [FILES]...       \n\nOptions:\n  -A, --aggregate\n          Aggregate all input files/content into a single array\n  -f, --from-file\n          load filter from the file\n  -I, --input-format \u003cINPUT_FORMAT\u003e\n          Set input format [possible values: markdown, mdx, html, text, null, raw]\n  -L, --directory \u003cMODULE_DIRECTORIES\u003e\n          Search modules from the directory\n  -M, --module-names \u003cMODULE_NAMES\u003e\n          Load additional modules from specified files\n      --args \u003cNAME\u003e \u003cVALUE\u003e\n          Sets string that can be referenced at runtime\n      --rawfile \u003cNAME\u003e \u003cFILE\u003e\n          Sets file contents that can be referenced at runtime\n      --stream\n          Enable streaming mode for processing large files line by line\n      --json\n          Include the built-in JSON module\n      --csv\n          Include the built-in CSV module\n      --fuzzy\n          Include the built-in Fuzzy module\n      --yaml\n          Include the built-in YAML module\n      --toml\n          Include the built-in TOML module\n      --xml\n          Include the built-in XML module\n      --test\n          Include the built-in test module\n  -F, --output-format \u003cOUTPUT_FORMAT\u003e\n          Set output format [default: markdown] [possible values: markdown, html, text, json, none]\n  -U, --update\n          Update the input markdown (aliases: -i, --in-place, --inplace)\n      --unbuffered\n          Unbuffered output\n      --list-style \u003cLIST_STYLE\u003e\n          Set the list style for markdown output [default: dash] [possible values: dash, plus, star]\n      --link-title-style \u003cLINK_TITLE_STYLE\u003e\n          Set the link title surround style for markdown output [default: double] [possible values: double, single, paren]\n      --link-url-style \u003cLINK_URL_STYLE\u003e\n          Set the link URL surround style for markdown links [default: none] [possible values: none, angle]\n  -S, --separator \u003cQUERY\u003e\n          Specify a query to insert between files as a separator\n  -o, --output \u003cFILE\u003e\n          Output to the specified file\n  -C, --color-output\n          Colorize markdown output\n      --list\n          List all available subcommands (built-in and external)\n  -P \u003cPARALLEL_THRESHOLD\u003e\n          Number of files to process before switching to parallel processing [default: 10]\n  -h, --help\n          Print help\n  -V, --version\n          Print version\n\n# Examples:\n\n## To filter markdown nodes:\nmq 'query' file.md\n\n## To read query from file:\nmq -f 'file' file.md\n\n## To start a REPL session:\nmq repl\n\n## To format mq file:\nmq fmt --check file.mq\n```\n\n\u003c/details\u003e\n\nHere's a basic example of how to use `mq`:\n\n```sh\n# Extract all headings from a document\nmq '.h' README.md\n\n# Extract code blocks containing \"name\"\nmq '.code | select(contains(\"name\"))' example.md\n\n# Extract code values from code blocks\nmq -A 'pluck(.code.value)' example.md\n\n# Extract language names from code blocks\nmq '.code.lang' documentation.md\n\n# Extract URLs from all links\nmq '.link.url' README.md\n\n# Filter table cells containing \"name\"\nmq '.[][] | select(contains(\"name\"))' data.md\n\n# Select lists or headers containing \"name\"\nmq 'select(.[] || .h) | select(contains(\"name\"))' docs.md\n\n# Exclude JavaScript code blocks\nmq '.code | select(.code.lang != \"js\")' examples.md\n\n# Convert CSV to markdown table\nmq 'include \"csv\" | csv_parse(true) | csv_to_markdown_table()' example.csv\n```\n\n### Advanced Usage\n\nYou can chain multiple operations to perform complex transformations:\n\n```sh\n# Generate a table of contents from headings\nmq '.h | let link = to_link(\"#\" + to_text(self), to_text(self), \"\") | let level = .h.level | if (!is_none(level)): to_md_list(link, level)' docs/books/**/*.md\n\n# String interpolation\nmq 'let name = \"Alice\" | let age = 30 | s\"Hello, my name is ${name} and I am ${age} years old.\"'\n\n# Merge multiple files with separators\nmq -S 's\"\\n${__FILE__}\\n\"' 'identity()' docs/books/**/**.md\n\n# Extract all code blocks from an HTML file\nmq '.code' example.html\n\n# Convert HTML to Markdown and filter headers\nmq 'select(.h1 || .h2)' example.html\n\n# Extract specific cell from a Markdown table\nmq '.[1][2] | to_text()' data.md\n```\n\n### Using with markitdown\n\nYou can combine `mq` with [markitdown](https://github.com/microsoft/markitdown) for even more powerful Markdown processing workflows:\n\n```sh\n# Extract code blocks from markdown\nmarkitdown https://github.com/harehare/mq | mq '.code'\n# Extract table from markdown\nmarkitdown test.xlsx | mq '.[][]'\n```\n\n## External Subcommands\n\nYou can extend `mq` with custom subcommands by placing executable files starting with `mq-` in `~/.mq/bin/` or anywhere in your `PATH`.\n\n```sh\n# Create a custom subcommand\ncat \u003e ~/.mq/bin/mq-hello \u003c\u003c 'EOF'\n#!/bin/bash\necho \"Hello from mq-hello!\"\necho \"Arguments: $@\"\nEOF\nchmod +x ~/.mq/bin/mq-hello\n\n# Use the custom subcommand\nmq hello world\n# Output: Hello from mq-hello!\n#         Arguments: world\n\n# List all available subcommands\nmq --list\n```\n\nThis makes it easy to add your own tools and workflows to `mq` without modifying the core binary.\n\n### External Tools\n\nThe following external tools are available to extend mq's functionality:\n\n- [mq-check](https://github.com/harehare/mq-check) - A syntax and semantic checker for mq files.\n- [mq-conv](https://github.com/harehare/mq-conv) - A CLI tool for converting various file formats to Markdown.\n- [mq-docs](https://github.com/harehare/mq-docs) - A documentation generator for mq functions, macros, and selectors.\n- [mq-edit](https://github.com/harehare/mq-edit) - A terminal-based Markdown and code editor with WYSIWYG rendering and LSP support.\n- [mq-mcp](https://github.com/harehare/mq-mcp) - Model Context Protocol (MCP) server implementation for AI assistants\n- [mq-task](https://github.com/harehare/mq-task) - Task runner using mq for Markdown-based task definitions\n- [mq-tui](https://github.com/harehare/mq-tui) - Terminal User Interface (TUI) for interactive mq query\n- [mq-update](https://github.com/harehare/mq-update) - Update mq binary to the latest version\n- [mq-view](https://github.com/harehare/mq-view) - viewer for Markdown content\n\n## Support\n\n- 🐛 [Report bugs](https://github.com/harehare/mq/issues)\n- 💡 [Request features](https://github.com/harehare/mq/issues)\n- ⭐ [Star the project](https://github.com/harehare/mq) if you find it useful!\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","funding_links":[],"categories":["Utilities","📚 Projects (1974 total)","MCP Frameworks and libraries","Rust"],"sub_categories":["Markdown","MCP Servers","Rust"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharehare%2Fmq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharehare%2Fmq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharehare%2Fmq/lists"}