@puckeditor/cli 0.24.0-canary.8a8fcc94 → 0.24.0-canary.8e792e2d

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.
package/dist/docs/cli.md CHANGED
@@ -15,7 +15,7 @@ npx @puckeditor/cli init
15
15
 
16
16
  With Puck AI, the only manual step is logging in to Puck Cloud and approving the connection in your browser. When it's done, the CLI starts your dev server and opens the editor.
17
17
 
18
- Puck AI, [Puck Pages](#puck-pages) and [Puck Auth](#puck-auth) are optional. Each uses Puck Cloud, so choosing any of them sets up Puck Cloud too. `init` asks which to include, with all three selected, and gives coding agents a `choose_capabilities` action to ask the developer. When the developer has already chosen, such as in the command from the Puck Cloud setup page, pass `--ai`, `--pages` or `--auth` to include only those, `--no-ai`, `--no-pages` or `--no-auth` to include all but those, or `--editor-only` for none.
18
+ Puck AI is optional. It's the editor plugin that uses Puck Cloud as its backend, so choosing it sets up Puck Cloud too. `init` asks whether to add it, and gives coding agents a `choose_ai` action to ask the developer. Pass `--ai` or `--no-ai` when the developer has already chosen, such as in the command from the Puck Cloud setup page.
19
19
 
20
20
  ## Supported projects
21
21
 
@@ -52,8 +52,6 @@ In a Hono or Express project, the CLI sets up the APIs a Puck editor in another
52
52
  - `/api/pages`: loads (`GET ?path=/about`) and saves (`POST { path, data }`) pages, in `src/puck/pages.ts`
53
53
  - `/api/puck/*`: the Puck Cloud route for Puck AI, in `src/puck/cloud.ts`, when you choose Puck AI
54
54
 
55
- With [Puck Pages](#puck-pages), `/api/pages` serves pages published in Puck Cloud instead, and only loads them.
56
-
57
55
  It mounts both on your app before it starts serving, so your own middleware runs first. Node doesn't load `.env` files, so the CLI adds `--env-file-if-exists=.env.local` to a `tsx` or `node` dev script. Bun loads `.env.local` itself. On Cloudflare Workers, put `PUCK_API_KEY` in `.dev.vars` instead.
58
56
 
59
57
  Add the Puck AI plugin in the app with the editor. If that app runs on another origin, proxy `/api` to the server in development, or pass `host` to `createAiPlugin`.
@@ -66,28 +64,7 @@ Run with `--yes --json`. The CLI never prompts, and prints exactly one JSON docu
66
64
  npx @puckeditor/cli init --yes --json
67
65
  ```
68
66
 
69
- When `status` is `action_required`, nothing has been changed yet. Show each entry in `actions` to the developer, then run its `rerun` command. Without any of those flags, the first run returns a `choose_capabilities` action, so the developer can choose which of Puck AI, Puck Pages and Puck Auth to add.
70
-
71
- Once they've chosen, the CLI sets up Puck Cloud on a new project that doesn't need an account yet, so the run completes the setup. It returns a `claim_project` action with a link for the developer:
72
-
73
- ```json
74
- {
75
- "status": "success",
76
- "cloud": { "configured": true, "verified": "remote" },
77
- "actions": [
78
- {
79
- "type": "claim_project",
80
- "required": false,
81
- "url": "https://cloud.puckeditor.com/claim#token=…",
82
- "expiresAt": "2026-11-15T12:00:00.000Z"
83
- }
84
- ]
85
- }
86
- ```
87
-
88
- Show the link to the developer. The project and its key are deleted at `expiresAt`, 72 hours later, unless the developer signs up or logs in at the link to claim it. The key keeps working once it's claimed. Puck AI only works on claimed projects.
89
-
90
- To have the developer log in first instead, pass `--login`. The first run then asks them to approve the login:
67
+ When `status` is `action_required`, nothing has been changed yet. Show each entry in `actions` to the developer, then run its `rerun` command. Without `--ai` or `--no-ai`, the first run returns a `choose_ai` action, so the developer can decide whether to add Puck AI. With `--ai`, the first run asks the developer to log in:
91
68
 
92
69
  ```json
93
70
  {
@@ -98,7 +75,7 @@ To have the developer log in first instead, pass `--login`. The first run then a
98
75
  "type": "browser_login",
99
76
  "url": "https://cloud.puckeditor.com/cli/connect#code=BCDF-GHJK",
100
77
  "userCode": "BCDF-GHJK",
101
- "rerun": "npx @puckeditor/cli init --yes --json --ai --login"
78
+ "rerun": "npx @puckeditor/cli init --yes --json --ai"
102
79
  }
103
80
  ]
104
81
  }
@@ -119,12 +96,6 @@ After the developer approves, the same command completes the setup:
119
96
 
120
97
  Start with `npx @puckeditor/cli status --json` to see what's already set up and which command to run next.
121
98
 
122
- ### Running the installed CLI
123
-
124
- When the CLI installs Puck, it adds itself to the app's `devDependencies`. From then on, run that copy rather than downloading it again, with `npm exec --no -- puck`, `pnpm exec puck` or `yarn puck`. When the CLI runs from the project, its `rerun` commands use it too.
125
-
126
- Agent sandboxes such as Claude Code's auto mode can block downloading and running a package the developer didn't ask for by name. If `npx @puckeditor/cli` is blocked, show the developer the exact command and run it once they approve.
127
-
128
99
  ### Statuses
129
100
 
130
101
  | Status | Meaning |
@@ -139,10 +110,9 @@ Agent sandboxes such as Claude Code's auto mode can block downloading and runnin
139
110
  | Type | What to do |
140
111
  | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
141
112
  | `browser_login` | Ask the developer to open `url`, confirm `userCode` and approve |
142
- | `claim_project` | Show `url` to the developer, who claims the project there before `expiresAt`, or it's deleted |
143
113
  | `provide_api_key` | Ask for a Puck API key, then re-run with `PUCK_API_KEY` set |
144
114
  | `confirm_plan` | Review `plan.steps`, then re-run with `--yes` |
145
- | `choose_capabilities` | Ask the developer which of `choices` to add, then re-run `init` with each one's flag, or `none` (`--editor-only`) for none |
115
+ | `choose_ai` | Ask the developer, then re-run `init` with `--ai` or `--no-ai` |
146
116
  | `choose_backend` | Ask the developer, then re-run with `--backend add`, `--backend external --backend-url <url>` or `--backend none` |
147
117
  | `choose_framework` | Re-run `init` with `--framework` and one of `next`, `react-router`, `tanstack-start`, `vinext`, `vite`, `astro`, `hono` or `express` |
148
118
  | `provide_app_name` | Re-run `init` with `--name <name>` |
@@ -152,21 +122,21 @@ Agent sandboxes such as Claude Code's auto mode can block downloading and runnin
152
122
 
153
123
  ### Exit codes
154
124
 
155
- | Code | Meaning |
156
- | ---- | ----------------------------------------------- |
157
- | 0 | Success |
158
- | 2 | Invalid arguments or API key |
159
- | 3 | Unsupported or ambiguous project |
160
- | 4 | File conflict |
161
- | 5 | Package manager failure |
162
- | 6 | `doctor` found problems |
163
- | 7 | Puck Cloud couldn't complete a login or request |
164
- | 10 | Action required |
165
- | 11 | Partially set up |
125
+ | Code | Meaning |
126
+ | ---- | ------------------------------------ |
127
+ | 0 | Success |
128
+ | 2 | Invalid arguments or API key |
129
+ | 3 | Unsupported or ambiguous project |
130
+ | 4 | File conflict |
131
+ | 5 | Package manager failure |
132
+ | 6 | `doctor` found problems |
133
+ | 7 | Puck Cloud couldn't complete a login |
134
+ | 10 | Action required |
135
+ | 11 | Partially set up |
166
136
 
167
137
  ### Reading the docs
168
138
 
169
- The CLI includes these docs as markdown, matching its release. Use the version of the CLI that matches the project's `@puckeditor/core`, such as the one installed in the project with `npm exec --no -- puck docs`:
139
+ The CLI includes these docs as markdown, matching its release. Use the version of the CLI that matches the project's `@puckeditor/core`:
170
140
 
171
141
  ```sh
172
142
  npx @puckeditor/cli docs ls # every page
@@ -183,45 +153,39 @@ npx skills add puckeditor/skills --skill puck
183
153
 
184
154
  ## Commands
185
155
 
186
- | Command | Description |
187
- | --------------------- | ------------------------------------------------------------------------------ |
188
- | `init` | Set up Puck, optionally with Puck AI, creating an app if needed |
189
- | `add editor` | Add the Puck editor |
190
- | `add cloud` | Connect Puck Cloud (adds the editor first if needed) |
191
- | `add ai` | Add the Puck AI plugin (adds Puck Cloud first if needed) |
192
- | `add pages` | Store and publish pages in Puck Cloud (adds Puck Cloud first if needed) |
193
- | `add auth` | Require Sign in with Puck to edit (adds Puck Cloud first if needed) |
194
- | `pages import <file>` | Publish pages from a JSON file to Puck Cloud |
195
- | `connect [branch]` | Log in to Puck Cloud again and replace `PUCK_API_KEY`, optionally for a branch |
196
- | `status` | Show what's installed and configured |
197
- | `doctor` | Diagnose problems and suggest fixes. Never makes changes |
198
- | `frameworks` | Show the supported frameworks and versions |
199
- | `docs` | Read these docs: `ls`, `cat <page>`, `find <query>`, `grep <text>` |
200
- | `telemetry` | Show or change anonymous usage data collection |
156
+ | Command | Description |
157
+ | ------------ | ------------------------------------------------------------------ |
158
+ | `init` | Set up Puck, optionally with Puck AI, creating an app if needed |
159
+ | `add editor` | Add the Puck editor |
160
+ | `add cloud` | Connect Puck Cloud (adds the editor first if needed) |
161
+ | `add ai` | Add the Puck AI plugin (adds Puck Cloud first if needed) |
162
+ | `connect` | Log in to Puck Cloud again and replace `PUCK_API_KEY` |
163
+ | `status` | Show what's installed and configured |
164
+ | `doctor` | Diagnose problems and suggest fixes. Never makes changes |
165
+ | `frameworks` | Show the supported frameworks and versions |
166
+ | `docs` | Read these docs: `ls`, `cat <page>`, `find <query>`, `grep <text>` |
167
+ | `telemetry` | Show or change anonymous usage data collection |
201
168
 
202
169
  ## Flags
203
170
 
204
- | Flag | Description |
205
- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
206
- | `--json` | Machine-readable output |
207
- | `--yes`, `-y` | Apply the plan without prompting |
208
- | `--dry-run` | Show the plan without changing anything or logging in |
209
- | `--cwd <path>` | Run against another directory |
210
- | `--workspace <name\|dir>` | Choose an app when running from a monorepo root |
211
- | `--api-key <key>` | Use an existing API key instead of logging in |
212
- | `--no-env-write` | Don't write `PUCK_API_KEY` to a file |
213
- | `--ai`, `--pages`, `--auth` | Include only these of Puck AI, [Puck Pages](#puck-pages) and [Puck Auth](#puck-auth) (`init`) |
214
- | `--no-ai`, `--no-pages`, `--no-auth` | Include all of them except these (`init`) |
215
- | `--editor-only` | Include none of them (`init`) |
216
- | `--canary` | Install the latest canaries of `@puckeditor/core`, `cloud-client` and the plugins, pinned to exact versions (`init` and `add`). `PUCK_CANARY=1` does the same. Private packages are read with your npm login |
217
- | `--backend <choice>` | Where a Vite app's server comes from: `add`, `external` or `none` |
218
- | `--backend-url <url>` | The server for `--backend external` |
219
- | `--wait` | Wait for login approval instead of returning `action_required` |
220
- | `--login` | Log in to Puck Cloud instead of starting on a project without an account (`init` and `add`) |
221
- | `--framework <name>` | Framework for a new app: `next`, `react-router`, `tanstack-start`, `vinext`, `vite`, `astro`, `hono` or `express` |
222
- | `--name <name>` | Directory for a new app |
223
- | `--package-manager <name>` | Override the detected package manager |
224
- | `--offline` | Skip the Puck Cloud connection check (`doctor`) |
171
+ | Flag | Description |
172
+ | -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
173
+ | `--json` | Machine-readable output |
174
+ | `--yes`, `-y` | Apply the plan without prompting |
175
+ | `--dry-run` | Show the plan without changing anything or logging in |
176
+ | `--cwd <path>` | Run against another directory |
177
+ | `--workspace <name\|dir>` | Choose an app when running from a monorepo root |
178
+ | `--api-key <key>` | Use an existing API key instead of logging in |
179
+ | `--no-env-write` | Don't write `PUCK_API_KEY` to a file |
180
+ | `--ai` | Also set up Puck AI and Puck Cloud (`init`) |
181
+ | `--no-ai` | Set up the editor only, without asking about Puck AI (`init`) |
182
+ | `--backend <choice>` | Where a Vite app's server comes from: `add`, `external` or `none` |
183
+ | `--backend-url <url>` | The server for `--backend external` |
184
+ | `--wait` | Wait for login approval instead of returning `action_required` |
185
+ | `--framework <name>` | Framework for a new app: `next`, `react-router`, `tanstack-start`, `vinext`, `vite`, `astro`, `hono` or `express` |
186
+ | `--name <name>` | Directory for a new app |
187
+ | `--package-manager <name>` | Override the detected package manager |
188
+ | `--offline` | Skip the Puck Cloud connection check (`doctor`) |
225
189
 
226
190
  ## API keys
227
191
 
@@ -233,64 +197,20 @@ To use an existing key, prefer the environment over `--api-key`, which is visibl
233
197
  PUCK_API_KEY=your-key npx @puckeditor/cli add cloud --yes
234
198
  ```
235
199
 
236
- Coding agents start on a Puck Cloud project without an account, and get a link for the developer to claim it within 72 hours. When you run the CLI yourself, you can choose to do the same. To log in instead, pass `--login`.
237
-
238
200
  To log in again, for example to replace a revoked key, run `connect`. It always starts a new login and replaces the existing key, without changing any code:
239
201
 
240
202
  ```sh
241
203
  npx @puckeditor/cli connect
242
204
  ```
243
205
 
244
- Each key is for one branch of a Puck Cloud project. When you approve the login, you choose the project and branch, which defaults to the project's default branch. To connect to another branch, for example for a preview deployment, name it:
245
-
246
- ```sh
247
- npx @puckeditor/cli connect feature/new-hero
248
- ```
249
-
250
- Puck Cloud preselects that branch, or offers to create it from the default branch.
251
-
252
206
  Remember to set `PUCK_API_KEY` in your production environment too. `react-router-serve` and Cloudflare Workers don't load `.env` files; on Workers, use `wrangler secret put PUCK_API_KEY`.
253
207
 
254
- The `/api/puck` route and the editor are public by default. Add [Puck Auth](#puck-auth), or your own authentication, before deploying.
208
+ The `/api/puck` route and the editor are public by default. Add authentication before deploying.
255
209
 
256
210
  ## Puck AI
257
211
 
258
212
  `init` and `add ai` add the Puck AI plugin to the editor, allow design mode in the `/api/puck` route, and wrap your config with `withDynamicConfig` so components designed by Puck AI render on your pages. If your editor has been customised, the CLI leaves it alone and prints the code to add.
259
213
 
260
- ## Puck Pages
261
-
262
- `add pages`, or `init --pages`, stores pages in Puck Cloud with the [Pages plugin](https://puckeditor.com/docs/pages/overview), which adds page management, drafts, publishing and version history to the editor:
263
-
264
- - The editor opens at `/puck`, with the page to edit in the `path` query parameter, e.g. `/puck?path=/about`. URLs ending in `/edit` redirect there
265
- - Published pages are rendered from Puck Cloud with `puckCloud().pages.getPublished()` from `@puckeditor/cloud-client`. In Vite apps and on [servers](#servers), `/api/pages` serves them read-only
266
- - `@puckeditor/cloud-client` is updated to a version with Puck Pages, which the `/api/puck` route serves as it is
267
-
268
- Pages in `database.json`, or wherever your app saved them, aren't moved automatically. Import them with `pages import`, then delete the old routes.
269
-
270
- Until you add [Puck Auth](#puck-auth), anyone who can reach `/api/puck` can edit, publish and delete pages using your API key.
271
-
272
- ### Importing pages
273
-
274
- ```sh
275
- npx @puckeditor/cli pages import database.json
276
- ```
277
-
278
- `pages import` publishes a JSON object of Puck data keyed by route, like a recipe's `database.json`. Pages that already exist in Puck Cloud are kept. It uses `--api-key`, `PUCK_API_KEY` in the environment, or the key in the env files where it runs, so run it from your app. The API key decides which project and branch the pages go to.
279
-
280
- Agents pass `--yes --json`. If Puck Cloud fails part way, the status is `partial` and `pagesImport.notImported` lists the routes left. Run the command again to import them.
281
-
282
- ## Puck Auth
283
-
284
- `add auth`, or `init --auth`, requires [Sign in with Puck](https://puckeditor.com/docs/auth/overview) to edit:
285
-
286
- - The `/api/puck` route passes `auth: { provider: "puck" }` to `puckHandler`, which serves the sign-in routes under `/api/puck/auth` and rejects requests from anyone not signed in to your Puck Cloud organization
287
- - The editor sends signed-out visitors to sign in. Server-rendered apps check with `getPuckIdentity` from `@puckeditor/cloud-client` before rendering it. Vite apps, and Astro sites without a server, check in the browser with `<RequireSession>`
288
- - The Puck Auth plugin adds an account menu to the editor
289
-
290
- Without Puck Pages, the editor still saves pages through your own route, which Sign in with Puck doesn't protect. On a Hono or Express server, `add auth` only changes the Cloud route, so run it in the editor's app too.
291
-
292
- Members sign in to the API key's project and edit its branch. Set `PUCK_API_KEY` on each deployment to a key for the branch it should edit, so a preview deployment can't edit production.
293
-
294
214
  ## Telemetry
295
215
 
296
216
  The CLI collects anonymous usage data to help us improve it. The first time it runs without `--json`, it prints a notice.
@@ -305,7 +225,7 @@ Each command sends one event to Puck Cloud with:
305
225
  - The framework and its major version, the package manager, the `--backend` choice, whether the project is in a monorepo, and whether the Puck editor, Puck Cloud and Puck AI are set up
306
226
  - A random ID, stored in `~/.config/puck/telemetry.json`
307
227
 
308
- It never sends code, file paths, project or package names, hostnames, error messages, flag values or API keys, other than a word typed in place of a command. When you log in to Puck Cloud with `connect`, the random ID is linked to your account. Logging in isn't telemetry: `connect` also sends your project's name and your computer's hostname, so the approval page can show what's connecting and name a new Puck Cloud project after your app. Starting a project without an account sends the same, and links the random ID to whoever claims it.
228
+ It never sends code, file paths, project or package names, hostnames, error messages, flag values or API keys, other than a word typed in place of a command. When you log in to Puck Cloud with `connect`, the random ID is linked to your account. Logging in isn't telemetry: `connect` also sends your project's name and your computer's hostname, so the approval page can show what's connecting and name a new Puck Cloud project after your app.
309
229
 
310
230
  To turn telemetry off, run:
311
231
 
@@ -14,8 +14,6 @@ Or set up Puck and Puck Cloud in a new or existing Next.js, React Router, TanSta
14
14
  npx @puckeditor/cli init
15
15
  ```
16
16
 
17
- With a coding agent, ask it to "Set up Puck by running `npx @puckeditor/cli init`". Naming the command lets agents in sandboxes such as Claude Code's auto mode run it.
18
-
19
17
  Or generate a Puck application using a [recipe](https://github.com/puckeditor/puck#recipes)
20
18
 
21
19
  ```sh
@@ -1,7 +1,4 @@
1
1
  {
2
2
  "cloudClientRange": "^0",
3
- "pluginAiRange": "^0",
4
- "cloudClientPagesRange": "^0.9.0-0",
5
- "pluginPagesRange": "^0.9.0-0",
6
- "pluginAuthRange": "^0.9.0-0"
3
+ "pluginAiRange": "^0"
7
4
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@puckeditor/cli",
3
- "version": "0.24.0-canary.8a8fcc94",
3
+ "version": "0.24.0-canary.8e792e2d",
4
4
  "description": "Set up Puck and Puck Cloud from the command line. Built for coding agents, friendly for humans.",
5
5
  "author": "Chris Villa <chris@puckeditor.com>",
6
6
  "repository": {
@@ -22,7 +22,6 @@
22
22
  },
23
23
  "dependencies": {
24
24
  "@babel/parser": "^7.29.3",
25
- "@inquirer/checkbox": "^4.3.2",
26
25
  "@inquirer/confirm": "^5.1.21",
27
26
  "@inquirer/input": "^4.3.1",
28
27
  "@inquirer/password": "^4.0.23",