Dòng lệnh (snapzy)

Tổng quan

Snapzy đi kèm lệnh snapzy để các AI agent (Claude Code, Cursor, Codex…), shell script và chính Terminal của bạn có thể chụp ảnh màn hình mà không cần chạm vào chuột. Mỗi lệnh trả về đường dẫn tệp, metadata dạng JSON và một mã thoát có ý nghĩa.

• Client mỏng. snapzy giao tiếp với ứng dụng Snapzy đang chạy qua một Unix socket riêng. Snapzy thực hiện việc chụp, vì vậy quyền Ghi màn hình vẫn thuộc về Snapzy — Terminal hoặc agent của bạn không bao giờ cần quyền này.
• Tự khởi động Snapzy. Nếu Snapzy chưa chạy, lệnh sẽ mở ứng dụng ở chế độ nền và chờ ứng dụng sẵn sàng (không hiện màn hình chào khi đã hoàn tất hướng dẫn ban đầu). Truyền --no-launch để lệnh báo lỗi thay vì khởi động.
• Không giao diện. Ảnh chụp từ dòng lệnh không bao giờ mở Truy cập nhanh (Quick Access), không đụng tới clipboard, không thêm mục vào lịch sử, không áp dụng preset hay phát âm thanh, và không bao giờ kích hoạt hộp thoại xin quyền.
• Phê duyệt theo từng ứng dụng. Lần đầu một ứng dụng sử dụng snapzy, Snapzy sẽ hỏi bạn có cho phép ứng dụng đó hay không.

Cài đặt lệnh

Tệp thực thi luôn nằm bên trong ứng dụng tại:

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

Agent và script có thể gọi trực tiếp đường dẫn đó. Để gõ snapzy ở bất kỳ đâu, hãy đưa nó vào PATH:

Phương thức	Cách thực hiện
Settings → Command Line (Cài đặt → Dòng lệnh)	Nhấp nút ⓘ trên thanh công cụ, sau đó chọn Install (Cài đặt). Thao tác này tạo /usr/local/bin/snapzy (chỉ yêu cầu mật khẩu quản trị viên nếu /usr/local/bin không cho phép ghi). Bật công tắc Command line access (Truy cập dòng lệnh) cũng sẽ cài đặt lệnh. Việc cài đặt bị từ chối khi Snapzy đang chạy từ DMG hoặc một vị trí tạm thời — hãy chuyển ứng dụng vào thư mục Applications trước.
Shell script	install.sh tạo liên kết /usr/local/bin/snapzy khi có thể, hoặc in ra lệnh sudo ln -sfn … để bạn tự chạy. Script không bao giờ ghi đè một tệp thông thường hoặc liên kết của công cụ khác.
Homebrew	Cask sẽ tự động liên kết snapzy bắt đầu từ bản phát hành ổn định đầu tiên có chứa lệnh này. Nếu Cài đặt hiển thị Copy Command (Sao chép lệnh), hãy chạy brew reinstall --cask snapzy để tạo liên kết.
Thủ công	sudo ln -sfn /Applications/Snapzy.app/Contents/Helpers/snapzy /usr/local/bin/snapzy

Vì lệnh nằm bên trong gói ứng dụng, các bản cập nhật trong ứng dụng (Sparkle) sẽ cập nhật lệnh cùng với Snapzy. Uninstall (Gỡ cài đặt) trong cùng popover chỉ xóa liên kết trỏ tới ứng dụng này.

Kiểm tra thiết lập:

snapzy doctor

Bắt đầu nhanh

# 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

Các lệnh

Lệnh	Chức năng
snapzy status	Phiên bản ứng dụng, truy cập dòng lệnh có đang bật không, trạng thái hướng dẫn ban đầu, quyền Ghi màn hình và ứng dụng gọi lệnh đã được phê duyệt hay chưa. Không bao giờ cần phê duyệt.
snapzy doctor	Kiểm tra đường dẫn CLI, PATH, ứng dụng, kết nối và trạng thái, đồng thời giải thích từng lỗi kèm gợi ý. Không bao giờ khởi động Snapzy.
snapzy version	Phiên bản CLI và ứng dụng. Không bao giờ khởi động Snapzy; thoát với mã 5 sau khi in nếu không kết nối được tới Snapzy.
snapzy list displays	Các màn hình đang kết nối (ID, tên, khung, tỉ lệ, màn hình chính).
snapzy list windows [--app NAME] [--all]	Các cửa sổ có thể chụp, từ trước ra sau. --all thêm các cửa sổ không hiển thị trên màn hình.
snapzy list apps	Các ứng dụng đang chạy có cửa sổ.
snapzy capture screen [--display main|all|ID]	Toàn bộ một màn hình (mặc định main), hoặc mọi màn hình — mỗi màn hình một tệp.
snapzy capture window --id ID	Một cửa sổ theo ID, kể cả khi bị các cửa sổ khác che.
snapzy capture window --app NAME [--title REGEX] [--index N]	Cửa sổ trên cùng của một ứng dụng; --title lọc theo biểu thức chính quy, --index chọn kết quả khớp khác (bắt đầu từ 0, từ trước ra sau).
snapzy capture window --active	Cửa sổ đang được focus của ứng dụng trên cùng.
snapzy capture area --rect x,y,w,h	Một hình chữ nhật tính bằng point. Vùng này phải nằm hoàn toàn trên màn hình.

capture window nhận đúng một trong các tùy chọn --id, --app hoặc --active; --no-shadow chụp cửa sổ không kèm bóng đổ. Chạy snapzy help <command> để xem trợ giúp tích hợp.

Khớp ứng dụng

--app chấp nhận bundle ID hoặc tên, không phân biệt hoa thường, theo thứ tự: bundle ID chính xác, rồi tên chính xác, rồi tiền tố tên — và chỉ cấp khớp tốt nhất được sử dụng. Vì vậy --app Code khớp với ứng dụng có tên chính xác là “Code” và không bao giờ lẫn Codex vào; nếu không có ứng dụng nào tên chính xác là “Code”, cấp tiền tố vẫn có thể khớp với Codex.

Khi có nhiều cửa sổ khớp, cửa sổ trên cùng được chọn và trường matchedCandidates trong kết quả cho biết có bao nhiêu cửa sổ khớp. Dùng --index N để chọn cửa sổ khác, hoặc dùng list windows --app NAME rồi chụp theo --id.

Tùy chọn chụp

Tùy chọn	Ý nghĩa
-o, --output PATH	Nơi ghi ảnh chụp: một đường dẫn tệp, một thư mục (dấu / ở cuối hoặc một thư mục đã tồn tại sẽ giữ tên tệp của Snapzy), hoặc - để ghi dữ liệu ảnh ra stdout (chỉ với một tệp). Với nhiều màn hình, các tệp được đặt tên name-1.png, name-2.png…
--format png|jpg|webp	Định dạng ảnh. Mặc định theo phần mở rộng của --output, nếu không thì là png. Định dạng xung đột với phần mở rộng sẽ gây lỗi.
--quality 0…1	Chất lượng JPEG (chỉ với jpg), mặc định 0.9.
--max-dimension PX	Thu nhỏ để cạnh dài nhất tối đa PX pixel (không bao giờ phóng to). 1568 là giá trị phù hợp cho các mô hình thị giác.
--cursor	Bao gồm con trỏ chuột.
--force	Ghi đè tệp đã tồn tại tại --output. Nếu không có tùy chọn này, tệp đã tồn tại sẽ gây lỗi trước khi chụp.

Nếu không có -o, tệp sẽ nằm trong thư mục tạm của Snapzy (~/Library/Application Support/Snapzy/CLI/Captures/) và bị xóa sau 24 giờ — hãy luôn truyền -o khi bạn muốn giữ lại tệp.

Tùy chọn chung

Các tùy chọn này hoạt động với mọi lệnh:

Tùy chọn	Mặc định	Ý nghĩa
--json	tắt	In JSON kể cả khi stdout là terminal (định dạng dễ đọc).
--timeout S	30	Số giây chờ cho mỗi yêu cầu.
--launch-timeout S	15	Số giây chờ Snapzy khởi động.
--no-launch	tắt	Báo lỗi thay vì khởi động Snapzy khi ứng dụng chưa chạy.

Đầu ra

Đầu ra là JSON khi stdout không phải terminal (pipe, agent, script) hoặc khi có --json; trong terminal, bạn nhận được một dòng dễ đọc cho mỗi mục. Lỗi được ghi ra stderr theo cùng chế độ.

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

• scale là số pixel trên mỗi point của tệp được ghi (thấp hơn tỉ lệ màn hình khi dùng --max-dimension).
• format là png, jpeg hoặc webp.
• Ảnh chụp cửa sổ còn bao gồm window (id, title, app {name, bundleID, pid}, frame, displayID, isOnScreen, isActive) và matchedCandidates.
• Với -o -, stdout chứa dữ liệu ảnh; metadata JSON chỉ được ghi ra stderr khi bạn truyền thêm --json.

Lỗi có dạng như sau:

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

Tọa độ

Tất cả các khung và giá trị --rect đều dùng point toàn cục với gốc tọa độ ở góc trên bên trái của màn hình chính. Các màn hình nằm bên trái hoặc phía trên màn hình chính có tọa độ âm — --rect -1440,0,800,600 hoạt động bình thường. Giá trị frame của cửa sổ từ list windows có thể truyền thẳng vào capture area.

Mã thoát

Mã thoát	Mã lỗi	Ý nghĩa
0	—	Thành công
1	internal	Lỗi không mong muốn
2	invalidArguments	Cờ không hợp lệ, vùng chụp nằm một phần ngoài màn hình, hoặc --output đã tồn tại mà không có --force
3	permissionDenied, onboardingIncomplete	Thiếu quyền Ghi màn hình hoặc quyền chưa có hiệu lực, hoặc chưa hoàn tất thiết lập Snapzy
4	targetNotFound	Không có màn hình, cửa sổ hoặc ứng dụng như vậy, hoặc vùng chụp nằm ngoài màn hình
5	appUnavailable, launchTimeout, disabled, busy, versionMismatch, unknownMethod	Không kết nối được tới Snapzy, truy cập dòng lệnh đang tắt, một lần chụp khác đang chạy, màn hình đang khóa, hoặc phiên bản không khớp
7	notAuthorized	Ứng dụng gọi lệnh bị từ chối, không được phê duyệt kịp thời, hoặc không thể xác định

Phê duyệt & Ứng dụng được cho phép

Mọi lệnh trừ status đều cần ứng dụng gọi lệnh được phê duyệt — tức ứng dụng mà bạn chạy snapzy từ đó, chẳng hạn Terminal, iTerm, VS Code, Cursor hoặc Claude. Snapzy xác định ứng dụng này bằng cách đi ngược từ tiến trình snapzy lên tới ứng dụng thông thường đầu tiên, và kiểm tra chữ ký mã của nó. Các ứng dụng không thể xác minh sẽ hiển thị biểu tượng chung, một cảnh báo và vị trí thực của chúng trên ổ đĩa.

Yêu cầu đầu tiên hiển thị hộp thoại với các nút Always Allow (Luôn cho phép), Allow Once (Cho phép một lần) và Don't Allow (Không cho phép):

• Phím Return không chọn nút nào; Escape nghĩa là Don't Allow.
• Hộp thoại hết hạn sau 25 giây và lệnh thoát với mã 7.
• Allow Once chỉ áp dụng cho phần còn lại của lệnh snapzy đó.
• Các quyết định chỉ được lưu trên máy Mac này và không bao giờ được xuất ra config.toml.

Xem lại hoặc thu hồi quyết định trong Settings → Command Line → Allowed apps (Cài đặt → Dòng lệnh → Ứng dụng được cho phép) (Remove hoặc Remove All). Mở trực tiếp bằng snapzy://settings/command-line.

Trong khi một lần chụp từ dòng lệnh đang chạy, biểu tượng trên thanh menu sẽ được tô màu. Nếu biểu tượng thanh menu bị ẩn, một thông báo sẽ hiển thị tên ứng dụng thay thế.

Tắt tính năng

Công tắc Command line access (Truy cập dòng lệnh) trong Settings → Command Line (Cài đặt → Dòng lệnh) được bật theo mặc định. Khi tắt, Snapzy đóng socket và mọi lệnh đều thất bại với disabled (mã thoát 5). Thiết lập tương tự cũng có trong config.toml:

[general]
cli_enabled = true

Sử dụng snapzy với AI Agent

1. Chạy snapzy status một lần. Nếu authorization là undetermined, hộp thoại của Snapzy sẽ xuất hiện ở lần chụp tiếp theo — nhấp Always Allow hoặc Allow Once trong vòng 25 giây.
2. Tìm mục tiêu bằng list displays, list apps hoặc list windows.
3. Luôn chụp vào đường dẫn do bạn chọn bằng -o.
4. Thêm --max-dimension 1568 để ảnh đủ nhỏ cho đầu vào thị giác, sau đó đọc files[].path được trả về.

Kho mã Snapzy có sẵn một agent skill tại skills/snapzy để hướng dẫn agent quy trình này.

Khắc phục sự cố

Hãy chạy snapzy doctor trước — lệnh này giải thích từng lỗi và gợi ý cách khắc phục.

Triệu chứng	Nguyên nhân & cách khắc phục
disabled (5)	Truy cập dòng lệnh đang tắt. Bật trong Settings → Command Line (Cài đặt → Dòng lệnh).
launchTimeout (5)	Snapzy đã được khởi động nhưng không phản hồi trong thời gian --launch-timeout — thường do truy cập dòng lệnh đang tắt, hoặc ứng dụng khởi động chậm.
permissionDenied (3), “granted but not usable yet”	Quyền Ghi màn hình được cấp trong khi Snapzy đang chạy. Khởi động lại Snapzy; nếu vẫn lỗi, hãy xóa rồi thêm lại Snapzy trong Cài đặt hệ thống → Quyền riêng tư & Bảo mật → Ghi màn hình & âm thanh hệ thống (System Settings → Privacy & Security → Screen & System Audio Recording).
onboardingIncomplete (3)	Mở Snapzy và hoàn tất thiết lập.
appUnavailable (5), “The screen is locked or asleep”	macOS không cho phép chụp khi phiên làm việc đang khóa.
notAuthorized (7)	Ứng dụng gọi lệnh bị từ chối, hoặc không ai trả lời hộp thoại. Kiểm tra Settings → Command Line → Allowed apps (Cài đặt → Dòng lệnh → Ứng dụng được cho phép).
snapzy: command not found	Lệnh chưa có trong PATH. Dùng Settings → Command Line → Install (Cài đặt → Dòng lệnh → Cài đặt), brew reinstall --cask snapzy nếu cài qua Homebrew, hoặc gọi đường dẫn đầy đủ bên trong Snapzy.app.