Permissions and Troubleshooting

Check permissions in the launching context

Screen Recording is needed for screenshots; Accessibility is needed for pointer and keyboard events. Grant these permissions to the application that actually launches the binary—not just to Terminal in general. Switching from Terminal to an IDE or another launcher can change the permission context. After toggling a permission, you may need to restart that application for it to take effect.

Build and startup

• cargo: command not found — Install or select a Rust toolchain; verify with rustc --version and cargo --version.
• Compiler, SDK, or Swift linking error — Check xcode-select -p and the selected Apple build tools. This source links macOS and Swift frameworks; it isn't a portable Linux binary.
• nano-use: command not found — Use ./target/release/nano-use --help from the checkout, or follow the optional PATH step in Quick Start.
• unexpected argument '--version' — This version has no version flag. Use git rev-parse HEAD to identify your checkout.

Capture and decoding

A successful screenshot writes one base64 PNG followed by a newline. Make sure you capture stdout separately from stderr. Follow the decoder sequence in Quick start—a file with a .png extension isn't necessarily a decoded PNG.

If stderr says 未检测到活动显示器 (no active displays detected), run in a logged-in graphical session and check the launcher's display access. A restricted or headless process may not see a display. Even when a file exists, an empty, black, or incomplete image still calls for a permission and session check. Capture availability and protected content behavior can differ by application and OS version.

Input and arguments

• unexpected argument '-480' — End option parsing with --: nano-use scroll -- 320 240 -480. The same applies to negative coordinates and text beginning with a hyphen.
• type 命令不接受空字符串 — Supply a non-empty text argument.
• 无法解析按键组合 — Use one main key with optional modifiers, like shift+a. cmd alone or a+b are invalid.
• 未知按键 — Use a supported key name. keypress isn't for arbitrary Unicode text input; use type for that.
• Exit 0 but nothing changes — Check Accessibility permission and focus in a disposable document; verify with a new screenshot. No visible effect doesn't prove successful delivery.

Parser errors exit 2. Runtime errors handled by this version print to stderr and exit 1. Other termination statuses can come from the OS or the launcher.

Coordinates and multiple displays

The tool validates points against the axis-aligned bounding rectangle that encloses all active displays. Points in gaps between displays can still pass validation. Negative origins are possible. Screenshot pixel dimensions can differ from desktop coordinate units on scaled displays—don't blindly reuse image pixels as click coordinates. Re-observe after changing display layout or scaling.