Quick Start

Clone, build, and take your first screenshot with nano-use—then optionally add it to your PATH.

Before you start

You'll need a Mac with Git, a Rust toolchain, and Apple's build tools. Make sure these all work first: git --version, rustc --version, cargo --version, and xcode-select -p. The commands below also use macOS base64, sips, and Preview; the Agent example later on needs Python 3 as well.

This pinned version was built and produced a decodable screenshot on macOS 26.6.2 with Rust 1.88.0 and Xcode 26.6 on 2026-09-06. Its capture dependency enables macOS 14.0 and 15.2 APIs. That check doesn't establish support for every older macOS version.

Get and build the documented version

Run these commands from a directory where a new nano-use folder can be created:

git clone https://github.com/Golenspade/nano-use.git
cd nano-use
git checkout --detach c473c6176aeda7ff9c2969bb12ac36967352bfac
cargo build --locked --release
./target/release/nano-use --help

The help output should list eight action commands—including screenshot, click, and keypress—along with Clap's help command. This version doesn't have a --version flag; use git rev-parse HEAD to identify the checkout. The commands that follow assume you're still in this repository root.

Capture and open your first image

If macOS asks, enable Screen Recording for the application that launches the command. Keep in mind that a terminal session and an IDE task may have different permission contexts, so grant it to whichever one you're actually using. Restart the launching application after changing permissions if needed.

./target/release/nano-use screenshot > screenshot.b64 &&
  /usr/bin/base64 -D -i screenshot.b64 -o screenshot.png &&
  /usr/bin/sips -g pixelWidth -g pixelHeight screenshot.png &&
  open screenshot.png

When everything works, the command exits successfully, sips reports positive pixel dimensions, and the opened image shows the desktop you intended to observe. Note that the CLI writes base64 text, not raw PNG bytes—renaming screenshot.b64 to .png won't decode it. Errors go to stderr, and the && chain prevents decoding or opening a failed capture. Keep screenshots local unless you intend to share their contents.

Optional: use the short command name

The full relative path above works without installation. If you'd like a shorter command in the current shell:

mkdir -p "$HOME/.local/bin"
cp ./target/release/nano-use "$HOME/.local/bin/nano-use"
export PATH="$HOME/.local/bin:$PATH"
nano-use --help

The export only applies to this shell session. Add the same PATH entry to your shell configuration if you want it in future sessions.

Next step

Read Commands before issuing any input events, then Agent integration for an observation-only adapter. If the build, capture, or input fails, see Permissions and troubleshooting.