clios-screenshot

 ██████╗██╗     ██╗ ██████╗ ███████╗
██╔════╝██║     ██║██╔═══██╗██╔════╝
██║     ██║     ██║██║   ██║███████╗
██║     ██║     ██║██║   ██║╚════██║
╚██████╗███████╗██║╚██████╔╝███████║
 ╚═════╝╚══════╝╚═╝ ╚═════╝ ╚══════╝

Screenshot your iPhone from the Mac terminal. Four capture modes cover every situation (phone on the desk, phone in your hand, cable or no cable), and the saved PNG's absolute path is always the last line on stdout, so it composes:

$ open "$(clios-screenshot)"

The core is a zero-dependency Rust binary that drives Apple's own machinery (iPhone Mirroring, screencapture, Universal Clipboard, Shortcuts) instead of reverse-engineered device protocols.

More about it: individuation.dev/projects/clios-screenshot.

Install

$ cargo install clios-screenshot
$ clios-screenshot setup

setup walks every mode interactively: it checks each prerequisite, fixes what it can (opens the right Settings pane, generates the trigger shortcut, offers to install optional tools), prints exact steps for what Apple keeps manual, and finishes each section with a live test capture.

clios-screenshot setup --check prints a pass/fail report and changes nothing. Run it first if you just want to see where you stand.

The four modes

Mode	Phone state	Taps	Cable	Resolution
(default)	locked, nearby	0	no	mirror window
--clipboard	any	2–3	no	native
--device	any	0	USB	native
--remote	any	0	no	native

--auto chains the hands-free ones: mirror → device → remote, first ready mode wins (details below).

Default: mirror capture

$ clios-screenshot

Captures the iPhone Mirroring window, launching the app first if needed. Best when the phone is sitting locked on your desk. Mirroring pauses while the phone is unlocked and in use; that's what the other three modes are for.

--clipboard: you copy, it saves

$ clios-screenshot --clipboard --wait 30

Run it, then on the phone: screenshot (side buttons) → tap the thumbnail → Copy. Universal Clipboard delivers it to the Mac and the command saves it the moment it arrives. Without --wait it saves whatever image is already on the clipboard. Requires Handoff on both devices (on by default).

--device: direct USB capture

$ clios-screenshot --device

Pulls the screenshot straight off the phone via pymobiledevice3, even mid-interaction. One-time: pipx install pymobiledevice3, Developer Mode on the phone, and on iOS 17+ a tunnel in a second terminal: sudo pymobiledevice3 remote tunneld (leave it running). Every error message names the missing piece.

--remote: wireless, zero taps

$ clios-screenshot --remote

The Mac flips a dedicated "Clios" Focus; your phone notices, screenshots itself, copies the image, and turns the Focus back off; Universal Clipboard delivers it. No messages sent, no files created, nothing left behind on the phone.

One-time setup: clios-screenshot setup remote generates the two shortcuts for you (steps 2–3) and walks the rest; the full manual version follows. Everything except the automation (step 4) happens on the Mac, and the shortcuts sync to the phone through your Shortcuts library.

1. Create the Focus. Settings → Focus → + → Custom → name it Clios. No silencing rules needed. Enable Share Across Devices at the bottom of the Focus pane. Do this first: the Set Focus action in the next steps can only pick Focus modes that already exist.
2. Mac trigger shortcut. In Shortcuts, create clios trigger with the single action Set Focus → Clios → On. This is what the CLI runs.
3. Capture shortcut. Create clios shot with these actions, in order:
   1. Set Focus → Clios → Off, first, so the Focus pill in the status bar isn't in your screenshot
   2. Wait → 2 seconds, to let the pill and any banner fade
   3. Take Screenshot
   4. Copy to Clipboard (its input should be the screenshot; that's the default chaining)
4. Phone automation. On the iPhone: Shortcuts → Automation → + → trigger When Clios turns On → Run Immediately, and turn Notify When Run OFF (otherwise a "Running your automation" banner appears in every capture) → on the next screen pick the existing clios shot.

--auto: first ready mode wins

$ clios-screenshot --auto

Probes and tries mirror → USB device → remote, skipping modes that aren't ready (no Screen Recording permission, no mirroring window on screen, no pymobiledevice3, no USB device, no trigger shortcut) and falling through ones that fail. Clipboard is never picked automatically; it needs you on the phone. Each decision is narrated on stderr, and --json reports the whole story in an attempts array. With --count, the remote leg is excluded (it can't repeat hands-free).

Reference

clios-screenshot [MODE] [OPTIONS]
clios-screenshot setup [mirror|clipboard|device|remote] [--check] [--json]
clios-screenshot devices [--json]
clios-screenshot config [dir <path>]

MODES: (default: mirror)  --auto  --clipboard  --device  --remote

-o, --output <PATH>   Save to PATH, or into it if it's a directory
    --json            Report success/failure as one JSON object on stdout
    --label <NAME>    Slug in the filename (e.g. login-error); in --json too
    --delay <SECS>    Sleep before capturing (let the UI settle)
    --count <N>       Capture N times (mirror/device only)
    --interval <SECS> Pause between --count captures (default 1)
    --udid <UDID>     Target a specific USB device (see: devices); with
                      --auto, pins the chain to the device leg
    --wait <SECS>     --clipboard/--remote: wait for the image to arrive
    --last            Print the newest saved screenshot; capture nothing

Plain output contract: on success the saved PNG's absolute path is the last line on stdout (--count streams one path per line as each capture lands); everything else goes to stderr; exit code 0/1.

Scripting and agents: --json

Every command takes --json and prints exactly one JSON object on stdout (the devices list is usbmux's own array). Success:

{"ok":true,"mode":"device","label":"login-error",
 "path":"/Users/you/shots/clios-screenshot-login-error-20260716-140705-123-000000001-0.png",
 "width":1179,"height":2556,"bytes":482133,
 "created_at":"2026-07-16T18:07:05Z","duration_ms":412}

--count replaces the flat file fields with "count" and a "captures" array of the same per-file objects; --auto adds an "attempts" array ({"mode","outcome":"ok|skipped|failed","detail"}). Width/height are read from the PNG header; check them to catch blank or wrong-screen grabs.

Failures (exit 1) are structured too, and still echo error: ... on stderr:

{"ok":false,"code":"timeout","message":"No new clipboard image appeared within 30s...",
 "hint":"retry with a longer --wait, or check Handoff on both devices","retryable":true}

code	Meaning	Retryable
usage	Bad flags or flag combination	no
permission	Screen Recording permission missing	no
no_window	Mirroring window missing/minimized/unpaired	yes
no_device	No trusted iPhone on USB (or Developer Mode off)	no
tool_missing	pymobiledevice3 not installed	no
tunnel_required	iOS 17+ needs sudo pymobiledevice3 remote tunneld	no
shortcut_missing	--remote trigger shortcut absent	no
timeout	Waited-for image never arrived	yes
no_clipboard_image	--clipboard with nothing to save	yes
no_screenshots	--last found nothing	no
capture_failed	The capture tool itself failed	yes
io	Couldn't write/move the file	no
unknown	Anything else	no

A mid---count failure includes the completed "captures"; a failed --auto includes its "attempts".

setup --check --json reports per-mode readiness for choosing a mode before capturing:

{"ok":true,"healthy":true,"modes":[
  {"mode":"mirror","ready":true,"checks":[
    {"name":"screen_recording_permission","ok":true,"detail":""},
    {"name":"mirroring_paired","ok":true,"detail":""}],"notes":[]},
  ...]}

healthy mirrors the exit code and refers to the default (mirror) mode.

Where screenshots go

Set a permanent destination once:

$ clios-screenshot config dir ~/Pictures/clios

Precedence, highest first: the -o flag, the CLIOS_SCREENSHOT_DIR environment variable, the configured dir, the current directory. clios-screenshot config shows the current resolution. The setting lives in ~/.config/clios-screenshot/config.

Environment variable	Meaning	Default
CLIOS_SCREENSHOT_DIR	Overrides the configured directory	unset
CLIOS_SCREENSHOT_TRIGGER_SHORTCUT	Mac shortcut --remote runs	clios trigger

Claude Code skill

skills/clios-screenshot/ ships an agent skill that teaches Claude Code to capture and read your iPhone screen ("what's on my phone?", "screenshot the app"). It rides the --auto --json interface above. Install by symlinking it into your personal skills directory:

$ ln -s "$(pwd)/skills/clios-screenshot" ~/.claude/skills/clios-screenshot

Troubleshooting

Symptom	Fix
Capture is empty / "produced no image"	Grant Screen Recording to your terminal: System Settings → Privacy & Security → Screen & System Audio Recording
Mirror capture shows a paused/"Connecting" screen	Phone was in use or session was starting; use --device/--remote/--clipboard, or rerun
window exists but is not on screen	Un-minimize it: open -a "iPhone Mirroring"
--device mentions a tunnel	sudo pymobiledevice3 remote tunneld in another terminal, leave it running
--remote times out	Phone automation missing or Focus not shared across devices: run clios-screenshot setup remote
Anything else	clios-screenshot setup --check

Notes

• macOS 15+ (iPhone Mirroring). Default mode is iPhone-only; --device also works with iPads.
• Mirror captures are at the mirroring window's Retina resolution; the other three modes give native device pixels.
• Why not talk to the phone directly? The iOS 17+ USB stack (RemoteXPC/DVT) is either months of reverse-engineering or a heavyweight dependency; letting Apple's own apps do the transport keeps the binary tiny and dependency-free, with pymobiledevice3 as an optional add-on for the USB path.

License

MIT