> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inklyai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic capture

> Use the Inkly CLI capture harness to let agents record screenshot/video or HTML demos.

Inkly turns a product session into a demo by **capturing** what a browser shows. The CLI opens Chrome, gives an agent a navigation harness, records each committed step, and writes a demo folder.

There are two capture commands. They share the same `start` / `stop` / `cancel` surface and differ in what each step records.

| Command              | Records each step as                                      | Best for                                                                 |
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------ |
| `inkly capture`      | A screenshot, or a short video clip for steps with motion | Pixel-faithful walkthroughs, animations, and pages you only need to show |
| `inkly capture-html` | A self-contained, replayable HTML snapshot                | Crisp text, resizable layouts, and snapshots that stay sharp at any zoom |

<Note>
  Both commands print JSON for every subcommand. Neither command plans the demo story for you. An external agent drives the page through `inkly capture nav`.
</Note>

## How a capture session works

Each command exposes the same session lifecycle:

* `start` — launch Chrome, open `--url`, and arm recording. Returns immediately with a session id.
* `status` — inspect a running session and see recorded steps.
* `nav <verb>` — drive the captured browser from an agent.
* `undo` — drop the last recorded step before you stop.
* `stop` — finish the session, build the demo, and write it to `--out`.
* `cancel` — abandon the session and clean up.
* `profiles` — list the persistent Chrome profiles the CLI knows about.
* `ask-user-to-log-in` — open a headed login flow for a persistent profile.

`start` returns right away while recording continues in the background until you `stop`.

## Agent navigation

Agents drive the browser with `inkly capture nav` or `inkly capture-html nav`.

```bash theme={null}
inkly capture nav snapshot --session <id>
inkly capture nav click @0-5 --session <id>
inkly capture nav fill @0-8 "Acme" --session <id>
inkly capture nav wait load --session <id>
```

Use `nav snapshot` first. It returns an accessibility tree with stable refs like `@0-5`, which agents can use for clicks, fills, selections, uploads, and assertions.

Common verbs include `snapshot`, `refs`, `click`, `fill`, `type`, `press`, `select`, `upload`, `get`, `is`, `wait`, `back`, `forward`, `reload`, `scroll`, and `mouse`.

## inkly capture (screenshots and video)

Use `inkly capture` when you want to show exactly what the page renders. Still steps become screenshots. Scrolls and other motion become short `webm` clips with poster frames. Click zoom and pan are applied to screenshot steps by default.

```bash theme={null}
# Start a session against a URL.
inkly capture start --url https://app.example.com --name "Onboarding tour"

# ... drive the page (or let an agent drive it) ...

# Finish and write the demo folder to ./out.
inkly capture stop --session <id> --out ./out

# Abandon a session instead of finishing it.
inkly capture cancel --session <id>
```

### Key flags

| Flag                         | Default        | Purpose                                                                |
| ---------------------------- | -------------- | ---------------------------------------------------------------------- |
| `--url <url>`                | —              | URL to open and arm for recording (`start`).                           |
| `--name <name>`              | —              | Demo name written into the exported demo (`start`).                    |
| `--session <id>`             | —              | Session id from `start` (`stop` / `cancel`).                           |
| `--out <dir>`                | —              | Output directory for `stop`. Writes the ZIP and unpacks the demo.      |
| `--video`, `--record-video`  | on             | Record motion segments. Use `--no-video` to disable.                   |
| `--zoom`                     | on             | Apply click zoom/pan to screenshot steps. Use `--no-zoom` to disable.  |
| `--width <n>`                | `1440`         | Browser viewport width.                                                |
| `--height <n>`               | `900`          | Browser viewport height.                                               |
| `--window-size <w>x<h>`      | —              | Shortcut for `--width <w> --height <h>`.                               |
| `--headed`                   | off (headless) | Use a visible Chrome window. Headless is the default.                  |
| `--browser <path>`           | local Chrome   | Chrome/Chromium binary to drive.                                       |
| `--connect-to-browser <url>` | —              | Attach to an existing Chrome DevTools endpoint.                        |
| `--profile <name>`           | —              | Reuse a persistent Chrome profile so a login survives across captures. |
| `--keep-profile`             | off            | Leave the temporary Chrome profile in place after `stop`/`cancel`.     |
| `--timeout <ms>`             | `120000`       | Page wait timeout.                                                     |
| `--no-unpack`                | off            | On `stop`, write only the ZIP without unpacking the demo.              |

<Note>
  Inkly prefers real installed Google Chrome over Chrome for Testing, because bot-gated sites (Cloudflare, SSO providers) pass headed real Chrome but block the automation build. For an interactive login you need to watch, run the first capture with `--headed`.
</Note>

## inkly capture-html (self-contained HTML)

Use `inkly capture-html` when text crispness and layout matter. Each step is a self-contained HTML snapshot with the markup, styles, inlined assets, and scroll position needed to replay that screen. Because it is real HTML, it stays sharp at any zoom.

```bash theme={null}
# Start an HTML capture session.
inkly capture-html start --url https://app.example.com --name "Dashboard walkthrough"

# Finish and write the demo to ./out, compacting media.
inkly capture-html stop --session <id> --out ./out

# Cancel a session.
inkly capture-html cancel --session <id>
```

`inkly capture-html` accepts every common capture flag, plus one HTML-specific flag:

| Flag             | Default | Purpose                                                                     |
| ---------------- | ------- | --------------------------------------------------------------------------- |
| `--block-videos` | off     | Replace each `<video>` with its poster frame instead of inlining the video. |

<Note>
  `inkly capture` is for screenshot and video steps. `inkly capture-html` is for HTML snapshots. Keep the two capture formats separate and choose the one you want before starting the session.
</Note>

## What a capture produces

`stop --out <dir>` writes a `.zip` and unpacks a demo folder beside it unless you pass `--no-unpack`. The folder is a standard Inkly demo:

```text theme={null}
<slug>/
  demo.config.json     the demo definition and its steps
  assets.json          maps each asset id to a file under public/
  public/<file>        captured image/video bytes, content-addressed by hash
  snapshots/snap-NNN/  captured HTML snapshots, when present
```

You can preview a bare exported demo folder directly:

```bash theme={null}
inkly dev <slug>/
```

To add it to a hub, run `inkly add --from` from inside that hub:

```bash theme={null}
inkly add <slug> --from ../captures/<slug>
```

### How captures become assets

Captured media is stored as managed assets. Each binary lands in `assets.json` with a stable `id`, content type, and size.

Inside `demo.config.json`, steps reference those entries with the `asset:<id>` URI scheme, such as `asset:cap-001` for a screenshot. Video steps can also reference a poster asset. The runtime resolves each `asset:<id>` through `assets.json`.

When you preview a hub locally, `inkly dev` serves the captured files from your machine. `inkly sync` is optional and helps keep large captured assets out of GitHub. `inkly snapshot` can publish one demo as a standalone link. See [Publish a demo](/cli/publish-a-snapshot).

For the manifest shape and the resolution rules, see [Assets](/schema/assets) and [Demo config](/schema/demo).