Командная строка (snapzy)

Обзор

Snapzy поставляется с командой snapzy, чтобы ИИ-агенты (Claude Code, Cursor, Codex…), скрипты оболочки и ваш собственный терминал могли делать снимки экрана, не прикасаясь к мыши. Каждая команда возвращает путь к файлу, метаданные в формате JSON и осмысленный код выхода.

Тонкий клиент. snapzy общается с запущенным приложением Snapzy через приватный Unix-сокет. Захват выполняет Snapzy, поэтому разрешение на запись экрана остаётся у Snapzy — вашему терминалу или агенту оно никогда не требуется.
Запускает Snapzy за вас. Если Snapzy не запущен, команда открывает его в фоновом режиме и дожидается готовности (без заставки, если онбординг завершён). Передайте --no-launch, чтобы вместо этого завершиться с ошибкой.
Без интерфейса. Захваты из командной строки никогда не открывают Quick Access, не трогают буфер обмена, не добавляют записи в историю, не применяют пресеты, не воспроизводят звук и не вызывают запрос разрешений.
Одобрение для каждого приложения. Когда приложение впервые использует snapzy, Snapzy спрашивает, разрешить ли ему это.

Установка команды

Исполняемый файл всегда находится внутри приложения по пути:

/Applications/Snapzy.app/Contents/Helpers/snapzy

Агенты и скрипты могут вызывать этот путь напрямую. Чтобы вводить snapzy из любого места, добавьте его в PATH:

Способ	Как
Settings → Command Line (Настройки → Командная строка)	Нажмите кнопку ⓘ на панели инструментов, затем Install (Установить). Будет создан `/usr/local/bin/snapzy` (пароль администратора запрашивается, только если `/usr/local/bin` недоступен для записи). Включение переключателя Command line access (Доступ из командной строки) также выполняет установку. Установка отклоняется, пока Snapzy запущен из DMG или временного расположения — сначала переместите его в папку «Программы».
Скрипт оболочки	`install.sh` создаёт ссылку `/usr/local/bin/snapzy`, когда это возможно, или выводит команду `sudo ln -sfn …` для запуска. Он никогда не перезаписывает обычный файл или ссылку другого инструмента.
Homebrew	Cask будет автоматически создавать ссылку `snapzy`, начиная с первого стабильного релиза, который её включает. Если в настройках отображается Copy Command (Скопировать команду), выполните `brew reinstall --cask snapzy`, чтобы создать ссылку.
Вручную	`sudo ln -sfn /Applications/Snapzy.app/Contents/Helpers/snapzy /usr/local/bin/snapzy`

Поскольку команда находится внутри пакета приложения, встроенные обновления (Sparkle) обновляют её вместе со Snapzy. Uninstall (Удалить) в том же всплывающем окне удаляет только ссылку, указывающую на это приложение.

Проверьте настройку:

snapzy doctor

Быстрый старт

# Is Snapzy ready? (never needs approval)
snapzy status

# Find something to capture
snapzy list displays
snapzy list apps
snapzy list windows --app Safari

# Capture
snapzy capture screen -o ~/Desktop/screen.png
snapzy capture window --app Safari --max-dimension 1568 -o shot.png
snapzy capture window --active --no-shadow -o focused.png
snapzy capture area --rect 0,0,800,600 -o area.jpg --quality 0.8

Команды

Команда	Что делает
`snapzy status`	Версия приложения, включён ли доступ из командной строки, онбординг, разрешение на запись экрана и одобрено ли вызывающее приложение. Никогда не требует одобрения.
`snapzy doctor`	Проверяет путь к CLI, `PATH`, приложение, соединение и статус, объясняя каждую ошибку подсказкой. Никогда не запускает Snapzy.
`snapzy version`	Версии CLI и приложения. Никогда не запускает Snapzy; если Snapzy недоступен, после вывода завершается с кодом `5`.
`snapzy list displays`	Подключённые дисплеи (ID, имя, рамка, масштаб, основной).
`snapzy list windows [--app NAME] [--all]`	Окна, доступные для захвата, от переднего к заднему. `--all` добавляет окна, которых нет на экране.
`snapzy list apps`	Запущенные приложения, у которых есть окна.
`snapzy capture screen [--display main\|all\|ID]`	Весь дисплей (по умолчанию `main`) или все дисплеи — по одному файлу на дисплей.
`snapzy capture window --id ID`	Одно окно по ID, даже если его перекрывают другие окна.
`snapzy capture window --app NAME [--title REGEX] [--index N]`	Самое переднее окно приложения; `--title` фильтрует по регулярному выражению, `--index` выбирает другое совпадение (с 0, от переднего к заднему).
`snapzy capture window --active`	Окно в фокусе у самого переднего приложения.
`snapzy capture area --rect x,y,w,h`	Прямоугольник в пунктах. Он должен полностью находиться на экране.

capture window принимает ровно один из параметров --id, --app или --active; --no-shadow захватывает окно без тени. Выполните snapzy help <command>, чтобы получить встроенную справку.

Сопоставление приложений

--app принимает bundle ID или имя без учёта регистра в следующем порядке: точный bundle ID, затем точное имя, затем префикс имени — и используется только лучший уровень. Поэтому --app Code совпадает с приложением, которое называется ровно «Code», и никогда не подмешивает Codex; если приложения с именем ровно «Code» нет, уровень префикса всё ещё может совпасть с Codex.

Если совпадает несколько окон, выигрывает самое переднее, а поле matchedCandidates в результате сообщает, сколько окон совпало. Используйте --index N, чтобы выбрать другое, или list windows --app NAME и захват по --id.

Параметры захвата

Параметр	Значение
`-o, --output PATH`	Куда записать захват: путь к файлу, каталог (завершающий `/` или существующая папка сохраняет имена файлов Snapzy) или `-`, чтобы записать байты изображения в stdout (только один файл). При нескольких дисплеях файлы называются `name-1.png`, `name-2.png`…
`--format png\|jpg\|webp`	Формат изображения. По умолчанию определяется расширением `--output`, иначе `png`. Формат, противоречащий расширению, считается ошибкой.
`--quality 0…1`	Качество JPEG (только jpg), по умолчанию `0.9`.
`--max-dimension PX`	Уменьшает изображение так, чтобы длинная сторона была не больше `PX` пикселей (никогда не увеличивает). `1568` — хорошее значение для моделей компьютерного зрения.
`--cursor`	Включить указатель мыши.
`--force`	Перезаписать существующий файл по пути `--output`. Без этого флага существующий файл вызывает ошибку до захвата.

Без -o файл остаётся в промежуточной папке Snapzy (~/Library/Application Support/Snapzy/CLI/Captures/) и удаляется через 24 часа — всегда передавайте -o, если хотите его сохранить.

Глобальные параметры

Работают с любой командой:

Параметр	По умолчанию	Значение
`--json`	выкл.	Выводить JSON, даже если stdout — терминал (с форматированием).
`--timeout S`	`30`	Сколько секунд ждать ответа на каждый запрос.
`--launch-timeout S`	`15`	Сколько секунд ждать запуска Snapzy.
`--no-launch`	выкл.	Завершаться с ошибкой вместо запуска Snapzy, если он не запущен.

Вывод

Вывод выполняется в формате JSON, когда stdout не является терминалом (конвейеры, агенты, скрипты) или при указании --json; в терминале вы получаете по одной читаемой строке на элемент. Ошибки выводятся в stderr в том же режиме.

{"durationMs":244,"files":[{"bytes":1204134,"displayID":1,"format":"png","height":2338,"path":"/Users/me/shot.png","scale":2,"width":3600}]}

scale — количество пикселей на пункт в записанном файле (меньше масштаба дисплея после --max-dimension).
format — png, jpeg или webp.
Захваты окон также включают window (id, title, app {name, bundleID, pid}, frame, displayID, isOnScreen, isActive) и matchedCandidates.
При -o - stdout передаёт байты изображения; метаданные JSON выводятся в stderr, только если вы также передали --json.

Ошибки выглядят так:

{"error":{"code":"targetNotFound","message":"…","hint":"…"}}

Координаты

Все рамки и значения --rect используют глобальные пункты с началом координат в левом верхнем углу основного дисплея. Дисплеи слева от основного или над ним имеют отрицательные координаты — --rect -1440,0,800,600 работает как есть. frame окна из list windows можно передать напрямую в capture area.

Коды выхода

Код выхода	Коды ошибок	Значение
`0`	—	Успех
`1`	`internal`	Непредвиденный сбой
`2`	`invalidArguments`	Неверные флаги, область частично за пределами экрана или существующий `--output` без `--force`
`3`	`permissionDenied`, `onboardingIncomplete`	Разрешение на запись экрана отсутствует или ещё не действует, либо настройка Snapzy не завершена
`4`	`targetNotFound`	Нет такого дисплея, окна или приложения, либо область за пределами экрана
`5`	`appUnavailable`, `launchTimeout`, `disabled`, `busy`, `versionMismatch`, `unknownMethod`	Snapzy недоступен, доступ из командной строки выключен, выполняется другой захват, экран заблокирован или версии не совпадают
`7`	`notAuthorized`	Вызывающему приложению отказано, оно не было одобрено вовремя или его не удалось идентифицировать

Одобрение и разрешённые приложения

Каждая команда, кроме status, требует, чтобы вызывающее приложение было одобрено — то есть приложение, из которого вы запускаете snapzy, например Terminal, iTerm, VS Code, Cursor или Claude. Snapzy определяет его, поднимаясь от процесса snapzy до первого обычного приложения, и проверяет его подпись кода. Приложения, которые не удаётся проверить, отображаются с универсальным значком, предупреждением и своим реальным расположением на диске.

При первом запросе появляется окно с кнопками Always Allow (Всегда разрешать), Allow Once (Разрешить один раз) и Don't Allow (Не разрешать):

Клавиша Return не выбирает кнопку; Escape означает Don't Allow (Не разрешать).
Запрос истекает через 25 секунд, и команда завершается с кодом 7.
Allow Once (Разрешить один раз) действует только до конца этой команды snapzy.
Решения хранятся только на этом Mac и никогда не экспортируются в config.toml.

Просматривайте или отзывайте решения в Settings → Command Line → Allowed apps (Настройки → Командная строка → Разрешённые приложения) с помощью Remove (Удалить) или Remove All (Удалить все). Откройте этот раздел напрямую через snapzy://settings/command-line.

Пока выполняется захват из командной строки, значок в строке меню подсвечивается цветом. Если значок в строке меню скрыт, вместо этого приложение указывается в уведомлении.

Отключение

Переключатель Command line access (Доступ из командной строки) в Settings → Command Line (Настройки → Командная строка) по умолчанию включён. Когда он выключен, Snapzy закрывает свой сокет, и каждая команда завершается с ошибкой disabled (код выхода 5). Та же настройка доступна в config.toml:

[general]
cli_enabled = true

Использование snapzy с ИИ-агентами

Один раз выполните snapzy status. Если authorization имеет значение undetermined, при следующем захвате появится запрос Snapzy — нажмите Always Allow (Всегда разрешать) или Allow Once (Разрешить один раз) в течение 25 секунд.
Находите цели с помощью list displays, list apps или list windows.
Всегда сохраняйте захват по выбранному вами пути с помощью -o.
Добавьте --max-dimension 1568, чтобы изображение оставалось достаточно маленьким для визуального ввода, затем прочитайте возвращённый files[].path.

Репозиторий Snapzy содержит готовый навык для агентов skills/snapzy, который обучает агентов этому рабочему процессу.

Устранение неполадок

Сначала выполните snapzy doctor — она объясняет каждую ошибку и предлагает исправление.

Симптом	Причина и исправление
`disabled` (5)	Доступ из командной строки выключен. Включите его в Settings → Command Line (Настройки → Командная строка).
`launchTimeout` (5)	Snapzy был запущен, но не ответил в пределах `--launch-timeout` — чаще всего потому, что доступ из командной строки выключен или приложение медленно запускается.
`permissionDenied` (3), «granted but not usable yet»	Разрешение на запись экрана было выдано, пока Snapzy работал. Перезапустите Snapzy; если проблема сохраняется, удалите и снова добавьте Snapzy в разделе Системные настройки → Конфиденциальность и безопасность → Screen & System Audio Recording (Запись экрана и системного аудио).
`onboardingIncomplete` (3)	Откройте Snapzy и завершите настройку.
`appUnavailable` (5), «The screen is locked or asleep»	macOS не разрешает захват, пока сеанс заблокирован.
`notAuthorized` (7)	Вызывающему приложению отказано, или никто не ответил на запрос. Проверьте Settings → Command Line → Allowed apps (Настройки → Командная строка → Разрешённые приложения).
`snapzy: command not found`	Команды нет в `PATH`. Используйте Settings → Command Line → Install (Настройки → Командная строка → Установить), `brew reinstall --cask snapzy` для установок через Homebrew или вызывайте полный путь внутри `Snapzy.app`.