# Inkly CLI

`inkly` is the command-line interface for **Inkly** — build an interactive product demo once, then iterate on it with AI. A *hub* is a folder with an `inkly.json`; each *demo* is a subfolder with a `demo.config.json` and a permanent opaque `id`.

This is an **index skill**: it gives you the command map and the setup check, then points you to a focused task skill when you have a specific job (capture, HTML capture, polish). Read the brief map first; load a deeper skill only when the task calls for it.

## Setup Check

```bash
which inkly || npm install -g @inkly-org/cli
inkly version
inkly help                 # full command index
inkly help <command>       # exact flags for one command
```

Install or refresh this skill across your installed agents:

```bash
inkly skills install
```

## Command Map

Run `inkly <command> --help` for the exact flags. Commands fall into four groups:

### Author a demo

| Command | What it does |
|---------|--------------|
| `inkly init <name> [--layout sidebar\|tabs]` | Scaffold a new demo hub. |
| `inkly add <name> [--collection <c>]` | Add a demo to the current hub (mints its id). |
| `inkly dev [<path>] [--port <n>]` | Start a local preview server for a hub or a single demo folder. |
| `inkly validate [--json] [--strict]` | Validate hub and demo files. |
| `inkly lock [--check] [--local <path>] [--json]` | Generate or verify `inkly.lock` (pins the runtime; `--check` is CI-safe). |

### Connect & publish

| Command | What it does |
|---------|--------------|
| `inkly login [--no-open] [--token <t>]` | Connect to the hosted Inkly app. |
| `inkly logout` / `inkly status [--json]` | Remove credentials / show auth + hub status. |
| `inkly sync [--demo <slug>] [--dry-run] [--json]` | Upload local capture blobs to the CDN. |
| `inkly snapshot <demo> [--json]` | Publish a standalone, shareable `/p/<id>` snapshot of one demo. Accepts a demo inside a hub or a bare exported demo folder (no `inkly.json` required). |

### Capture — built for agents

These two are **designed to be driven by an external coding agent, not used interactively**. Each prints JSON, refuses prompts, and does no planning of its own — you own the story and drive the page with `nav`. Load the matching task skill below before running them.

| Command | What it does |
|---------|--------------|
| `inkly capture <cmd>` | Capture an **image/video** walkthrough of a site → exports a demo ZIP. |
| `inkly capture-html <cmd>` | Capture a **self-contained HTML** (live-DOM) walkthrough of a site. |

**Default to `inkly capture` (image/video) for demos** — it is simpler, supports motion/video steps, and is the right choice for the large majority of demos. Use `inkly capture-html` ONLY when the user explicitly asks for HTML or needs live, reflowable DOM (crisp text at any size, selectable/responsive content); HTML steps cannot include video.

Both share one lifecycle — `start → status → nav <verb> → stop` (`cancel`, `undo`, `profiles` too) — and take the SAME subcommands. Drive the page with `inkly capture[-html] nav <verb> --session <id>` (verbs: `snapshot | click | fill | type | press | select | upload | get | is | wait | back | forward | reload | refs | mouse | screenshot`). Prefer `nav snapshot` to find elements — it returns stable refs like `@0-5`; `screenshot` is a debug-only escape hatch for when the tree isn't enough. Run `inkly help capture` / `inkly help capture-html` for the full flag list.

For OAuth/SSO or any user-only sign-in, run `inkly capture ask-user-to-log-in --url <login-url> [--profile <name>]` before capture. `--url` is required so the user sees the actual login page; when `--profile` is omitted, the CLI derives a reusable `profile.name` from the URL host and returns it in JSON. Reuse that exact name with `capture start --profile <profile.name>`.

### CLI & agent setup

| Command | What it does |
|---------|--------------|
| `inkly skills install` | Install/refresh this Inkly CLI skill into your installed agents. |
| `inkly doctor [--json]` | Local environment diagnostics. |
| `inkly version` / `inkly update [--dry-run]` | Print version / update the global install. |

## Task Skills (load on demand)

For a specific job, fetch the matching focused skill from the Inkly platform and follow it — each is a complete, step-by-step playbook with contracts, recovery, and gotchas that this index intentionally omits. Fetch the markdown (WebFetch, `curl`, or `skills use <url>`); humans can discover skills at https://www.app.inklyai.dev.

| If the task is… | Load this skill | URL |
|-----------------|-----------------|-----|
| "Capture a demo of `<url>`" (image/video steps) | **agent-capture** | https://www.app.inklyai.dev/__inkly/skills/agent-capture.md |
| "Capture an HTML demo of `<url>`" (live-DOM steps) | **agent-html-capture** | https://www.app.inklyai.dev/__inkly/skills/agent-html-capture.md |
| "Polish / finish a demo", or assemble one from existing screenshots/recordings (edit steps, labels, chapters, covers, TTS voiceover; mind the player aspect ratio) | **agent-demo-polish** | https://www.app.inklyai.dev/__inkly/skills/agent-demo-polish.md |
| Exact `demo.config.json` / `inkly.json` field shapes and schema | **inkly-cli-reference** | https://www.app.inklyai.dev/__inkly/skills/inkly-cli-reference.md |

Rules of thumb:

- **Capture is not the finish line.** Use a capture skill to record clean steps, then switch to **agent-demo-polish** and make the result shippable unless the user explicitly requested a raw export only. Don't re-record to fix something editable in `demo.config.json`.
- **Image/video vs. HTML** is the output choice: image/video supports motion segments; HTML steps are live DOM that reflow and stay crisp at any size but have no video. Pick the matching capture skill.
- When you need precise schema/field details while polishing, pull **inkly-cli-reference** (or read `packages/inkly-runtime/src/schema/src` — the code is the source of truth, the doc is versioned).
- These platform skills are versioned and may be newer than this bundled index; when they disagree on specifics, trust the fetched task skill.

## Publish to the Inkly platform

Two ways to get demos onto the hosted platform. Both need `inkly login` first.

### 1. Snapshot one demo (quick, one-off)

Freeze a single local demo to a standalone, shareable URL — no GitHub needed:

```bash
inkly login
inkly snapshot demos/<slug>      # publishes a standalone /p/<id> URL
```

`snapshot` uploads any missing binary assets to the CDN WITHOUT changing your local files. Best for sharing one demo fast, off the git substrate. Re-run it to push an updated snapshot.

### 2. GitHub-synced hub (ongoing, auto-updating)

Host a whole hub that the platform re-syncs on every commit:

1. Build the hub locally: `inkly init <hub>`, `inkly add <demo>`, edit, `inkly validate`.
2. Put the hub in a Git repo (the hub root — the folder with `inkly.json` — at the repo root) and push it to GitHub.
3. On the Inkly platform, open **Settings → GitHub**, authorize the Inkly GitHub App, and connect that repo. (First-time users get a one-click "create my repo" path in onboarding.)
4. Done — the platform hosts the hub at `/hub/<slug>` (each demo at `/hub/<slug>/<demoId>`) and **re-syncs automatically after every commit/push**. Edit locally, commit, push; the hosted hub updates itself.

Use a snapshot for a quick one-off; use the GitHub-synced hub for a living set of demos that stays in step with your repo.

## Diagnostics

```bash
inkly doctor            # run before debugging a broken capture or preview
inkly doctor --json     # structured output for CI/agents
```