@inkly-org/cli 0.7.0 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/dist/cli.js +277 -209
  2. package/dist/skills/inkly/SKILL.md +133 -0
  3. package/package.json +2 -1
  4. package/skills/inkly/SKILL.md +133 -0
package/dist/skills/inkly/SKILL.md ADDED
@@ -0,0 +1,133 @@
1
+ ---
2
+ name: inkly
3
+ description: Index skill for the inkly CLI — authoring and locally previewing Inkly interactive demos, and capturing image/video or self-contained HTML walkthroughs of any website for an agent. Gives a brief command map and points to deeper task skills hosted on the Inkly platform (capture, HTML capture, polish, full CLI/schema reference) to load on demand. Use when the user asks to scaffold a demo hub, add a demo, run a local preview, validate/lock demo files, connect to the Inkly app, sync assets, publish a snapshot, capture or polish a demo of a site, or install/refresh this inkly skill.
4
+ compatibility: "Requires the inkly CLI (`npm install -g @inkly-org/cli`, bin `inkly`). Capture commands drive local Chrome/Chromium. `inkly login`/`sync`/`snapshot` need an Inkly account."
5
+ license: UNLICENSED
6
+ allowed-tools: Bash
7
+ metadata:
8
+ openclaw:
9
+ requires:
10
+ bins:
11
+ - inkly
12
+ install:
13
+ - kind: node
14
+ package: "@inkly-org/cli"
15
+ bins: [inkly]
16
+ homepage: https://inklyai.dev
17
+ ---
18
+
19
+ # Inkly CLI
20
+
21
+ `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`.
22
+
23
+ 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.
24
+
25
+ ## Setup Check
26
+
27
+ ```bash
28
+ which inkly || npm install -g @inkly-org/cli
29
+ inkly version
30
+ inkly help # full command index
31
+ inkly help <command> # exact flags for one command
32
+ ```
33
+
34
+ Install or refresh this skill across your installed agents:
35
+
36
+ ```bash
37
+ inkly skills install
38
+ ```
39
+
40
+ ## Command Map
41
+
42
+ Run `inkly <command> --help` for the exact flags. Commands fall into four groups:
43
+
44
+ ### Author a demo
45
+
46
+ | Command | What it does |
47
+ |---------|--------------|
48
+ | `inkly init <name> [--layout sidebar\|tabs]` | Scaffold a new demo hub. |
49
+ | `inkly add <name> [--collection <c>]` | Add a demo to the current hub (mints its id). `inkly demo` is an alias. |
50
+ | `inkly dev [<path>] [--port <n>]` | Start a local preview server for a hub or a single demo folder. |
51
+ | `inkly validate [--json] [--strict]` | Validate hub and demo files. |
52
+ | `inkly lock [--check] [--local <path>] [--json]` | Generate or verify `inkly.lock` (pins the runtime; `--check` is CI-safe). |
53
+
54
+ ### Connect & publish
55
+
56
+ | Command | What it does |
57
+ |---------|--------------|
58
+ | `inkly login [--no-open] [--token <t>]` | Connect to the hosted Inkly app. |
59
+ | `inkly logout` / `inkly status [--json]` | Remove credentials / show auth + hub status. |
60
+ | `inkly sync [--demo <slug>] [--dry-run] [--json]` | Upload local capture blobs to the CDN. |
61
+ | `inkly snapshot <demo> [--json]` | Publish a standalone, shareable `/p/<id>` snapshot of one demo. |
62
+
63
+ ### Capture — built for agents
64
+
65
+ 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.
66
+
67
+ | Command | What it does |
68
+ |---------|--------------|
69
+ | `inkly capture <cmd>` | Capture an **image/video** walkthrough of a site → exports a demo ZIP. |
70
+ | `inkly capture-html <cmd>` | Capture a **self-contained HTML** (live-DOM) walkthrough of a site. |
71
+
72
+ **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.
73
+
74
+ 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`). Prefer `nav snapshot` to find elements — it returns stable refs like `@0-5`. Run `inkly help capture` / `inkly help capture-html` for the full flag list.
75
+
76
+ ### CLI & agent setup
77
+
78
+ | Command | What it does |
79
+ |---------|--------------|
80
+ | `inkly skills install` | Install/refresh this Inkly CLI skill into your installed agents. |
81
+ | `inkly doctor [--json]` | Local environment diagnostics. |
82
+ | `inkly version` / `inkly update [--dry-run]` | Print version / update the global install. |
83
+
84
+ ## Task Skills (load on demand)
85
+
86
+ 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 browse them at https://inklyai.dev/skills.
87
+
88
+ | If the task is… | Load this skill | URL |
89
+ |-----------------|-----------------|-----|
90
+ | "Capture a demo of `<url>`" (image/video steps) | **agent-capture** | https://inklyai.dev/__inkly/skills/agent-capture.md |
91
+ | "Capture an HTML demo of `<url>`" (live-DOM steps) | **agent-html-capture** | https://inklyai.dev/__inkly/skills/agent-html-capture.md |
92
+ | "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://inklyai.dev/__inkly/skills/agent-demo-polish.md |
93
+ | Exact `demo.config.json` / `inkly.json` field shapes and schema | **inkly-cli-reference** | https://inklyai.dev/__inkly/skills/inkly-cli-reference.md |
94
+
95
+ Rules of thumb:
96
+
97
+ - **Capturing vs. polishing are separate jobs.** Use a capture skill to record clean steps; switch to **agent-demo-polish** to make the result shippable. Don't re-record to fix something editable in `demo.config.json`.
98
+ - **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.
99
+ - 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).
100
+ - These platform skills are versioned and may be newer than this bundled index; when they disagree on specifics, trust the fetched task skill.
101
+
102
+ ## Publish to the Inkly platform
103
+
104
+ Two ways to get demos onto the hosted platform. Both need `inkly login` first.
105
+
106
+ ### 1. Snapshot one demo (quick, one-off)
107
+
108
+ Freeze a single local demo to a standalone, shareable URL — no GitHub needed:
109
+
110
+ ```bash
111
+ inkly login
112
+ inkly snapshot demos/<slug> # publishes a standalone /p/<id> URL
113
+ ```
114
+
115
+ `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.
116
+
117
+ ### 2. GitHub-synced hub (ongoing, auto-updating)
118
+
119
+ Host a whole hub that the platform re-syncs on every commit:
120
+
121
+ 1. Build the hub locally: `inkly init <hub>`, `inkly add <demo>`, edit, `inkly validate`.
122
+ 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.
123
+ 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.)
124
+ 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.
125
+
126
+ 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.
127
+
128
+ ## Diagnostics
129
+
130
+ ```bash
131
+ inkly doctor # run before debugging a broken capture or preview
132
+ inkly doctor --json # structured output for CI/agents
133
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@inkly-org/cli",
3
- "version": "0.7.0",
3
+ "version": "0.7.2",
4
4
  "description": "Inkly CLI — scaffold and locally preview demo configs.",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",
@@ -11,6 +11,7 @@
11
11
  "dist",
12
12
  "vendor",
13
13
  "template",
14
+ "skills",
14
15
  "README.md",
15
16
  "!dist/**/*.map"
16
17
  ],
package/skills/inkly/SKILL.md ADDED
@@ -0,0 +1,133 @@
1
+ ---
2
+ name: inkly
3
+ description: Index skill for the inkly CLI — authoring and locally previewing Inkly interactive demos, and capturing image/video or self-contained HTML walkthroughs of any website for an agent. Gives a brief command map and points to deeper task skills hosted on the Inkly platform (capture, HTML capture, polish, full CLI/schema reference) to load on demand. Use when the user asks to scaffold a demo hub, add a demo, run a local preview, validate/lock demo files, connect to the Inkly app, sync assets, publish a snapshot, capture or polish a demo of a site, or install/refresh this inkly skill.
4
+ compatibility: "Requires the inkly CLI (`npm install -g @inkly-org/cli`, bin `inkly`). Capture commands drive local Chrome/Chromium. `inkly login`/`sync`/`snapshot` need an Inkly account."
5
+ license: UNLICENSED
6
+ allowed-tools: Bash
7
+ metadata:
8
+ openclaw:
9
+ requires:
10
+ bins:
11
+ - inkly
12
+ install:
13
+ - kind: node
14
+ package: "@inkly-org/cli"
15
+ bins: [inkly]
16
+ homepage: https://inklyai.dev
17
+ ---
18
+
19
+ # Inkly CLI
20
+
21
+ `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`.
22
+
23
+ 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.
24
+
25
+ ## Setup Check
26
+
27
+ ```bash
28
+ which inkly || npm install -g @inkly-org/cli
29
+ inkly version
30
+ inkly help # full command index
31
+ inkly help <command> # exact flags for one command
32
+ ```
33
+
34
+ Install or refresh this skill across your installed agents:
35
+
36
+ ```bash
37
+ inkly skills install
38
+ ```
39
+
40
+ ## Command Map
41
+
42
+ Run `inkly <command> --help` for the exact flags. Commands fall into four groups:
43
+
44
+ ### Author a demo
45
+
46
+ | Command | What it does |
47
+ |---------|--------------|
48
+ | `inkly init <name> [--layout sidebar\|tabs]` | Scaffold a new demo hub. |
49
+ | `inkly add <name> [--collection <c>]` | Add a demo to the current hub (mints its id). `inkly demo` is an alias. |
50
+ | `inkly dev [<path>] [--port <n>]` | Start a local preview server for a hub or a single demo folder. |
51
+ | `inkly validate [--json] [--strict]` | Validate hub and demo files. |
52
+ | `inkly lock [--check] [--local <path>] [--json]` | Generate or verify `inkly.lock` (pins the runtime; `--check` is CI-safe). |
53
+
54
+ ### Connect & publish
55
+
56
+ | Command | What it does |
57
+ |---------|--------------|
58
+ | `inkly login [--no-open] [--token <t>]` | Connect to the hosted Inkly app. |
59
+ | `inkly logout` / `inkly status [--json]` | Remove credentials / show auth + hub status. |
60
+ | `inkly sync [--demo <slug>] [--dry-run] [--json]` | Upload local capture blobs to the CDN. |
61
+ | `inkly snapshot <demo> [--json]` | Publish a standalone, shareable `/p/<id>` snapshot of one demo. |
62
+
63
+ ### Capture — built for agents
64
+
65
+ 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.
66
+
67
+ | Command | What it does |
68
+ |---------|--------------|
69
+ | `inkly capture <cmd>` | Capture an **image/video** walkthrough of a site → exports a demo ZIP. |
70
+ | `inkly capture-html <cmd>` | Capture a **self-contained HTML** (live-DOM) walkthrough of a site. |
71
+
72
+ **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.
73
+
74
+ 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`). Prefer `nav snapshot` to find elements — it returns stable refs like `@0-5`. Run `inkly help capture` / `inkly help capture-html` for the full flag list.
75
+
76
+ ### CLI & agent setup
77
+
78
+ | Command | What it does |
79
+ |---------|--------------|
80
+ | `inkly skills install` | Install/refresh this Inkly CLI skill into your installed agents. |
81
+ | `inkly doctor [--json]` | Local environment diagnostics. |
82
+ | `inkly version` / `inkly update [--dry-run]` | Print version / update the global install. |
83
+
84
+ ## Task Skills (load on demand)
85
+
86
+ 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 browse them at https://inklyai.dev/skills.
87
+
88
+ | If the task is… | Load this skill | URL |
89
+ |-----------------|-----------------|-----|
90
+ | "Capture a demo of `<url>`" (image/video steps) | **agent-capture** | https://inklyai.dev/__inkly/skills/agent-capture.md |
91
+ | "Capture an HTML demo of `<url>`" (live-DOM steps) | **agent-html-capture** | https://inklyai.dev/__inkly/skills/agent-html-capture.md |
92
+ | "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://inklyai.dev/__inkly/skills/agent-demo-polish.md |
93
+ | Exact `demo.config.json` / `inkly.json` field shapes and schema | **inkly-cli-reference** | https://inklyai.dev/__inkly/skills/inkly-cli-reference.md |
94
+
95
+ Rules of thumb:
96
+
97
+ - **Capturing vs. polishing are separate jobs.** Use a capture skill to record clean steps; switch to **agent-demo-polish** to make the result shippable. Don't re-record to fix something editable in `demo.config.json`.
98
+ - **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.
99
+ - 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).
100
+ - These platform skills are versioned and may be newer than this bundled index; when they disagree on specifics, trust the fetched task skill.
101
+
102
+ ## Publish to the Inkly platform
103
+
104
+ Two ways to get demos onto the hosted platform. Both need `inkly login` first.
105
+
106
+ ### 1. Snapshot one demo (quick, one-off)
107
+
108
+ Freeze a single local demo to a standalone, shareable URL — no GitHub needed:
109
+
110
+ ```bash
111
+ inkly login
112
+ inkly snapshot demos/<slug> # publishes a standalone /p/<id> URL
113
+ ```
114
+
115
+ `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.
116
+
117
+ ### 2. GitHub-synced hub (ongoing, auto-updating)
118
+
119
+ Host a whole hub that the platform re-syncs on every commit:
120
+
121
+ 1. Build the hub locally: `inkly init <hub>`, `inkly add <demo>`, edit, `inkly validate`.
122
+ 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.
123
+ 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.)
124
+ 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.
125
+
126
+ 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.
127
+
128
+ ## Diagnostics
129
+
130
+ ```bash
131
+ inkly doctor # run before debugging a broken capture or preview
132
+ inkly doctor --json # structured output for CI/agents
133
+ ```