---
name: iris-screenshots
title: Iris screenshots
description: Use when capturing website screenshots with the iris CLI — flags, authenticated captures, viewports, element capture, batching, and what to do when a capture comes out wrong.
version: 1
---

`iris` (github.com/brijr/iris) renders a URL in a real Chrome-family browser over the DevTools protocol
and writes an image. It waits for fonts, images and animations before capturing, so the output is what a
person would see, not a half-loaded page.

## The basic loop

```
iris https://example.com -o /tmp/shot.png
```

Then **Read the file** — that is the whole point. Write captures somewhere disposable (`/tmp`) unless the
user asks to keep them.

## Authenticated captures

```
iris https://site.example/private -o /tmp/private.png --chrome ~/.local/bin/iris-browser
```

`iris-browser` picks whichever Chrome-family browser is installed (Brave first, then Chromium, then
Chrome) and seeds the capture with a copy of the cookies from `~/.config/officer/browser-profile` — the
profile the desktop plugin's browser signs into. The copy is read-only with respect to that profile:
captures cannot corrupt or lock it.

Three rules:

- **Never ask the user for credentials.** If a capture shows a login page, ask them to sign in to that
  site once through the desktop app, then capture again.
- **Whose sessions ride along is decided by `$HOME`** — each Linux user has their own profile, so you can
  only ever capture with the sessions of the account you run as.
- **Officer's own UI is behind its login too**, so capturing it needs the same wrapper and a signed-in
  desktop session, exactly like any other site.

## Flags that matter

| Flag | What it does |
| --- | --- |
| `-o, --out <path>` | output file (or directory for batches) |
| `-s, --size <preset>` | `desktop`, `iphone`, `ipad`, or `WxH` |
| `--full` | full page height, not just the viewport |
| `--selector <css>` | capture the first matching element only |
| `--padding <px>` | breathing room around a selected element |
| `--dark` | emulate `prefers-color-scheme: dark` |
| `--format <fmt>` | `png`, `jpg`, `webp` |
| `--wait <ms>` | extra settle time before capture |
| `--wait-for <css>` | wait until a selector exists |
| `--scale <n>` | device pixel ratio |
| `--timeout <secs>` | per-page limit |
| `--jobs <n>` | concurrency for multiple URLs |
| `--chrome <path>` | which browser binary — for sessions, always `~/.local/bin/iris-browser` |
| `--json` | structured result on stdout |

Verify a UI change in both themes by capturing twice, once with `--dark`. Verify responsive work with
`-s iphone` beside the desktop shot.

## When it goes wrong

- **`iris: command not found`** — the sidecar builds it on first start; `pm2 logs officer-iris` shows
  progress or says exactly what is missing (usually Rust older than 1.88, with the fix printed).
- **Capture shows a login page** — the site has no session in the profile. Ask the user to sign in via
  the desktop app; do not work around it.
- **`iris-browser: no Chrome-family browser found`** — the machine has no browser; the desktop plugin
  provides one.
- **Blank or half-rendered output** — add `--wait-for` on a selector that only exists when the page is
  really ready, or raise `--wait`.