jq

Какую задачу решает

Разбирает JSON и достаёт из него нужное: поля, записи по условию, суммы и количество. Агент получает JSON отовсюду: ответы сервисов, выгрузки заказов и заявок, журналы программ. С jq он одной командой оставляет нужные записи, считает итоги и сохраняет таблицу CSV, которую можно открыть в Excel или Google Таблицах.

• Оставляет в выгрузке только нужные записи: оплаченные заказы, заявки за неделю, ошибки из ответа сервиса.
• Считает суммы и количество по дням, товарам или статусам.
• Сохраняет результат таблицей CSV: запятые и кавычки в названиях товаров не ломают столбцы.
• Показывает длинный ответ сервиса в читаемом виде и достаёт из него одно поле, например номер заказа или ссылку.
• Работает в хуках Claude Code: примеры хуков в документации Claude Code разбирают JSON через jq.

Пример результата

Установить агентом

Установи программу «jq». Работай по шагам и после каждого коротко говори, что сделал.

Что это за программа (каталог smyslokod.ru, официальные источники сверены 01.10.2026):
- официальный сайт: https://jqlang.org/
- исходный код: https://github.com/jqlang/jq
- инструкция по установке: https://jqlang.org/download/
- актуальная версия на 01.10.2026: 1.8.2
- лицензия: MIT
- для работы нужно (в отдельных случаях): curl - только чтобы скачать готовый файл на Linux: в минимальных системах и контейнерах его нет, в Ubuntu и Debian он ставится командой apt-get install curl ca-certificates
- для работы нужно (в отдельных случаях): Homebrew - на Mac, если jq в системе нет или нужна версия новее встроенной

Правила:
1. Ничего не устанавливай и не меняй, пока я не скажу «да» на твой план.
2. Ставь только способами из этого промпта. Сторонние сборки, скрипты с форумов и из чужих репозиториев не бери.
3. Мои проекты не трогай: не меняй их файлы, виртуальные окружения и списки зависимостей (package.json, requirements.txt, pyproject.toml).
4. Команды с sudo, правку профиля оболочки (~/.zshrc, ~/.bashrc) и переменной PATH делай только после моего отдельного «да» на каждую.
5. Не проси у меня пароли и ключи и не выводи их. Если нужен пароль администратора, дай команду, я выполню её сам.
6. Исходные файлы не меняй: результат jq сохраняй в новый файл и не пиши в тот же файл, который читаешь.
7. Сложный фильтр клади в файл и запускай jq -f файл. Значения передавай через --arg и --argjson, переменные оболочки внутрь фильтра в двойных кавычках не подставляй.
8. Перед подсчётом денег посмотри типы полей (например, jq '.orders[0] | map_values(type)' файл): числа там или строки. Итог округляй до копеек, для дней по Москве прибавляй 10800 секунд ко времени UTC.
9. CSV собирай через @csv или @tsv с флагом -r, поля через запятую вручную не склеивай. После сохранения покажи первые строки файла и сверь итог другим способом, например с суммой исходного поля.
10. Если стоит jq старше 1.8.2, а разбирать предстоит чужие данные (ответы сервисов, файлы от посторонних людей), скажи мне и предложи обновить способом из этого промпта.
11. После скачивания готового файла с GitHub сверь его SHA-256 с файлом sha256sum.txt со страницы выпуска и покажи результат.
12. На Windows сохраняй вывод jq в файл из Git Bash или cmd: в Windows PowerShell 5.1 оператор > пишет файл в UTF-16LE (так в документации PowerShell).

Шаги:
0. Определи, где ты работаешь: мой компьютер, сервер или контейнер. Какая система и процессор, какие менеджеры пакетов есть (Homebrew, apt, winget, uv, pipx). Ставить нужно туда, где ты сам запускаешь команды.
   - на компьютере: на Mac сначала посмотри jq --version: в macOS 15 и новее jq уже есть. На Windows - winget, на Linux - готовый файл в ~/.local/bin без sudo или пакет дистрибутива.
   - на сервере: готовый файл в ~/.local/bin ставится одной командой, без sudo и зависимостей. Если агент разбирает ответы чужих сервисов, бери 1.8.2 с исправлениями безопасности: пакет дистрибутива может быть старше.
   - в контейнере: в чистом образе ubuntu:24.04 нет ни jq, ни curl: сначала apt-get install curl ca-certificates, потом готовый файл. Базы часовых поясов там тоже нет. Есть официальный образ ghcr.io/jqlang/jq для amd64, arm64 и других процессоров.
1. Проверь, не стоит ли программа уже: jq --version ; which -a jq. Если стоит и запускается, ничего не ставь и переходи к шагу 5.
2. Обязательных зависимостей у программы нет, то, что нужно в отдельных случаях, перечислено выше. Проверь свободное место на диске: нужно около 2 МБ (готовый файл для Linux - 1,8 МБ для arm64 и 2,3 МБ для amd64, для Windows - 1,0 МБ, для Mac - 0,8 МБ; пакет Ubuntu вместе с библиотеками libjq1 и libonig5 - 1,2 МБ; Homebrew скачивает jq и oniguruma, около 0,9 МБ).
3. Составь план: каким одним способом из списка ниже будешь ставить, что появится на диске и сколько места займёт, что поменяется в системе и как потом удалить. Покажи план и жди моего «да».
   Способы из официальных источников:
   - macOS, Homebrew: brew install jq (ставит 1.8.2 вместе с библиотекой oniguruma; встроенный /usr/bin/jq остаётся, which -a jq покажет обе копии)
   - Windows, winget: winget install jqlang.jq (в каталоге winget 1.8.2 для x64, ARM64 и x86; ставится как переносная программа, папку с командой jq winget дописывает в PATH, и видно её только в новом окне терминала)
   - Linux, готовый файл с GitHub: mkdir -p ~/.local/bin && curl -fL -o ~/.local/bin/jq https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-amd64 && chmod +x ~/.local/bin/jq (для процессоров x86_64, их же называют amd64; sudo не нужен; если ~/.local/bin нет в PATH, запускай ~/.local/bin/jq)
   - Linux, готовый файл с GitHub: mkdir -p ~/.local/bin && curl -fL -o ~/.local/bin/jq https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-arm64 && chmod +x ~/.local/bin/jq (для процессоров ARM64, их же называют aarch64)
   - Linux, apt: sudo apt-get install jq (Debian и Ubuntu; в Ubuntu 24.04 это 1.7.1 (jq --version пишет jq-1.7), и в нём закрыта только часть уязвимостей из 1.8.2; в Ubuntu 26.04 - 1.8.1)
   - Linux, dnf: sudo dnf install jq (Fedora; в Fedora 44 это 1.8.1)
   - Linux, pacman: sudo pacman -S jq (Arch Linux, версия 1.8.2)
4. Установи по согласованному плану. Если что-то идёт не так, как в плане, остановись и спроси.
5. Проверь результат:
   - jq --version: программа запускается без ошибки;
   - Сделай маленькую выгрузку orders.json: два оплаченных заказа и один отменённый, второй оплачен в 00:40 по Москве. Оставь оплаченные, посчитай суммы по дням по московскому времени и по товарам, сохрани два CSV и покажи их. Итог по дням и по товарам должен совпасть, 4370.3, а второй заказ должен попасть в 29.09. Делай это во временной папке и не трогай мои файлы.
     printf '%s\n' '{"orders":[{"id":1,"created_at":"2026-09-28T09:15:00.000Z","status":"paid","total":2980,"items":[{"title":"Футболка \"Смысл\", белая","qty":2,"price":1490}]},{"id":2,"created_at":"2026-09-28T21:40:00.000Z","status":"paid","total":1390.3,"items":[{"title":"Кружка","qty":1,"price":690.5},{"title":"Наклейки, набор из 5","qty":2,"price":349.9}]},{"id":3,"created_at":"2026-09-29T10:05:00.000Z","status":"cancelled","total":3990,"items":[{"title":"Худи серое","qty":1,"price":3990}]}]}' > orders.json
     jq '[.orders[] | select(.status == "paid")] | length' orders.json
     jq -r '["день","заказов","сумма"], ([.orders[] | select(.status == "paid") | {day: (.created_at[0:19] + "Z" | fromdateiso8601 + 10800 | strftime("%Y-%m-%d")), total}] | group_by(.day)[] | [.[0].day, length, (map(.total) | add * 100 | round / 100)]) | @csv' orders.json > by_day.csv
     jq -r '["товар","штук","сумма"], ([.orders[] | select(.status == "paid") | .items[] | .qty //= 1] | group_by(.title)[] | [.[0].title, (map(.qty) | add), (map(.qty * .price) | add * 100 | round / 100)]) | @csv' orders.json > by_product.csv
     cat by_day.csv by_product.csv
   - если ты работаешь в папке моего проекта, покажи git status: от установки в проекте не должно появиться изменений.
6. Итог одним сообщением: что установлено, какой версии и куда, сколько места заняло, что поменялось в системе и как всё удалить (macOS, Homebrew: brew uninstall jq; Windows, winget: winget uninstall jqlang.jq; Linux, готовый файл с GitHub: rm -f ~/.local/bin/jq; Linux, apt: sudo apt-get remove jq; Linux, dnf: sudo dnf remove jq; Linux, pacman: sudo pacman -R jq).

Если на любом шаге ошибка, не чини наугад: покажи текст ошибки и скажи, что, по-твоему, случилось. Частые проблемы: https://smyslokod.ru/cli/jq#problemy

Промпт собран из официальных инструкций, сверенных 01.10.2026. Агент сначала проверит, что уже стоит, покажет план с местом на диске и способом удаления и без твоего «да» ничего не поставит.

Как ставят вручную

Способы из официальных источников, у каждого ссылка на первоисточник.

• macOS · Homebrew · источник

  brew install jq

  ставит 1.8.2 вместе с библиотекой oniguruma; встроенный /usr/bin/jq остаётся, which -a jq покажет обе копии

• Windows · winget · источник

  winget install jqlang.jq

  в каталоге winget 1.8.2 для x64, ARM64 и x86; ставится как переносная программа, папку с командой jq winget дописывает в PATH, и видно её только в новом окне терминала

• Linux · готовый файл с GitHub · источник

  mkdir -p ~/.local/bin && curl -fL -o ~/.local/bin/jq https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-amd64 && chmod +x ~/.local/bin/jq

  для процессоров x86_64, их же называют amd64; sudo не нужен; если ~/.local/bin нет в PATH, запускай ~/.local/bin/jq

• Linux · готовый файл с GitHub · источник

  mkdir -p ~/.local/bin && curl -fL -o ~/.local/bin/jq https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-arm64 && chmod +x ~/.local/bin/jq

  для процессоров ARM64, их же называют aarch64

• Linux · apt · источник

  sudo apt-get install jq

  Debian и Ubuntu; в Ubuntu 24.04 это 1.7.1 (jq --version пишет jq-1.7), и в нём закрыта только часть уязвимостей из 1.8.2; в Ubuntu 26.04 - 1.8.1

• Linux · dnf · источник

  sudo dnf install jq

  Fedora; в Fedora 44 это 1.8.1

• Linux · pacman · источник

  sudo pacman -S jq

  Arch Linux, версия 1.8.2

Как удалить

• macOS, Homebrew: brew uninstall jq
• Windows, winget: winget uninstall jqlang.jq
• Linux, готовый файл с GitHub: rm -f ~/.local/bin/jq
• Linux, apt: sudo apt-get remove jq
• Linux, dnf: sudo dnf remove jq
• Linux, pacman: sudo pacman -R jq

Что нужно для работы

• curl (в отдельных случаях) - только чтобы скачать готовый файл на Linux: в минимальных системах и контейнерах его нет, в Ubuntu и Debian он ставится командой apt-get install curl ca-certificates
• Homebrew (в отдельных случаях) - на Mac, если jq в системе нет или нужна версия новее встроенной

Системы

• macOS - в macOS 15 и новее jq уже есть в системе (/usr/bin/jq, на macOS 26.6 это версия 1.7.1 от Apple). Версия 1.8.2 ставится через Homebrew, есть и готовые файлы для Apple Silicon и Intel.
• Windows - готовые файлы для x64, ARM64 и 32-битной Windows, ставится через winget.
• Linux - готовый файл без зависимостей для amd64, arm64 и других процессоров или пакет дистрибутива; в Ubuntu 24.04 и Debian 13 пакет старше, 1.7.1.

Где запускать

Ставить нужно туда, где работает агент: на твой компьютер, сервер или в контейнер.

• На компьютере - на Mac сначала посмотри jq --version: в macOS 15 и новее jq уже есть. На Windows - winget, на Linux - готовый файл в ~/.local/bin без sudo или пакет дистрибутива.
• На сервере - готовый файл в ~/.local/bin ставится одной командой, без sudo и зависимостей. Если агент разбирает ответы чужих сервисов, бери 1.8.2 с исправлениями безопасности: пакет дистрибутива может быть старше.
• В контейнере - в чистом образе ubuntu:24.04 нет ни jq, ни curl: сначала apt-get install curl ca-certificates, потом готовый файл. Базы часовых поясов там тоже нет. Есть официальный образ ghcr.io/jqlang/jq для amd64, arm64 и других процессоров.

Сколько ресурсов нужно

Место на диске

Около 2 МБ (готовый файл для Linux - 1,8 МБ для arm64 и 2,3 МБ для amd64, для Windows - 1,0 МБ, для Mac - 0,8 МБ; пакет Ubuntu вместе с библиотеками libjq1 и libonig5 - 1,2 МБ; Homebrew скачивает jq и oniguruma, около 0,9 МБ)

Память

jq читает файл в память целиком. На выгрузке в 100 000 заказов (38 МБ) отчёты по дням и по товарам заняли 270-300 МБ памяти и 0,7-1 с, подсчёт оплаченных - 250 МБ и 0,5 с (замер в контейнере на Mac с Apple Silicon). Для файлов больше памяти есть режим --stream: тот же подсчёт в нём занял 2 МБ памяти и 1,1 с.

Видеокарта

Не нужна.

Сеть

Только чтобы скачать программу. Данные jq обрабатывает на месте и никуда не отправляет.

Лицензия и платные замены

Лицензия MIT. Код jq идёт под MIT, так сказано в файле COPYING. Документация и сайт (папка docs) - под CC BY 3.0. Встроенные части со своими разрешительными условиями перечислены там же: библиотека decNumber (ICU License), код из Heimdal и NetBSD (BSD), dtoa.c. Условия важны тем, кто распространяет jq вместе со своим продуктом; чтобы обрабатывать свои файлы, делать ничего не нужно. Текст лицензии

Цена: Бесплатно

Платные замены

Платной замены, которую агент вызывал бы так же, нет: jq, gojq, jaq и DuckDB бесплатные. В Excel JSON загружают руками через Power Query: Данные → Получить данные → Из файла → Из JSON.

Бесплатные замены

• gojq - Программа на Go с тем же языком фильтров. Её автор itchyny пишет и исправления для самого jq. Считает большие целые числа без потерь, читает и пишет YAML, но порядок ключей в объектах не сохраняет. Лицензия MIT.
• jaq - Клон jq на Rust: автор делает упор на правильность, скорость и простоту. Лицензия MIT.
• DuckDB - Встраиваемая база данных с консольной программой duckdb: читает JSON и CSV, считает запросом SQL и сохраняет результат в CSV или сразу в файл Excel (xlsx). Лицензия MIT.

О чём помнить

• Обновляй jq до 1.8.2, если агент разбирает чужие данные: ответы сервисов, файлы от посторонних людей. В 1.8.2 закрыли 16 уязвимостей (CVE), три из них проект отметил как высокой важности. Пакет Ubuntu 24.04 (1.7.1) по трекеру Ubuntu получил исправления шести из них, ещё десять на 01.10.2026 не закрыты.
• Суммы с копейками jq считает в дробных числах: 349.90 * 7 даёт 2449.2999999999997. Итог округляй до копеек: add * 100 | round / 100.
• Если суммы в выгрузке записаны строками в кавычках ("1490.00"), add склеит их в "1490.00690.50" без всякой ошибки, а умножение на число повторит строку. Переводи такие поля в числа: tonumber.
• Время в выгрузках обычно в UTC. Заказ, оплаченный в 00:40 по Москве, записан как 21:40 прошлого дня и при подсчёте по дате из строки уедет во вчера. Для дня по Москве прибавляй 3 часа (10800 секунд). TZ=Europe/Moscow не поможет там, где нет базы часовых поясов, например в чистом контейнере Ubuntu: jq молча покажет время UTC.
• Excel открывает CSV в UTF-8 двойным щелчком правильно, только если в начале файла есть метка BOM (так в справке Microsoft). jq пишет файл без неё: агент добавит метку командой printf '\357\273\277' перед выводом jq, или открывай файл через Данные → Получить данные → Из файла → Из текстового/CSV-файла.
• Не пиши результат в тот же файл, который jq читает: jq ... orders.json > orders.json оставит пустой файл. Сначала сохрани во временный файл, потом переименуй.
• На Mac с macOS 15 и новее после brew install jq в системе две копии: /usr/bin/jq от Apple и jq из Homebrew. which -a jq покажет обе, работает та, что раньше в PATH.
• apt-get remove jq оставляет библиотеки libjq1 и libonig5. Их убирает apt-get autoremove, но он удаляет и другие ненужные пакеты: сначала посмотри список.

Частые проблемы

Проверка

✓ Проверено 01.10.2026: Docker Desktop 29.2.1 на Mac с Apple Silicon: одноразовый контейнер ubuntu:24.04 (Ubuntu 24.04.5, arm64), jq 1.8.2 - официальный файл jq-linux-arm64 с GitHub в ~/.local/bin.

«Проверено» ставим, только когда сами поставили программу и прогнали её на задаче. Сверка ссылок и вывод версии так не называются.