@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/README.md +1 -5
- package/dist/bin.mjs +593 -3054
- package/dist/docs/cli.md +48 -128
- package/dist/docs/getting-started.md +0 -2
- package/dist/templates/manifest.json +1 -4
- package/package.json +1 -2
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
|
|
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
|
|
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
|
|
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
|
-
| `
|
|
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
|
|
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
|
|
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
|
|
187
|
-
|
|
|
188
|
-
| `init`
|
|
189
|
-
| `add editor`
|
|
190
|
-
| `add cloud`
|
|
191
|
-
| `add ai`
|
|
192
|
-
| `
|
|
193
|
-
| `
|
|
194
|
-
| `
|
|
195
|
-
| `
|
|
196
|
-
| `
|
|
197
|
-
| `
|
|
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
|
|
205
|
-
|
|
|
206
|
-
| `--json`
|
|
207
|
-
| `--yes`, `-y`
|
|
208
|
-
| `--dry-run`
|
|
209
|
-
| `--cwd <path>`
|
|
210
|
-
| `--workspace <name\|dir>`
|
|
211
|
-
| `--api-key <key>`
|
|
212
|
-
| `--no-env-write`
|
|
213
|
-
| `--ai
|
|
214
|
-
| `--no-ai
|
|
215
|
-
| `--
|
|
216
|
-
| `--
|
|
217
|
-
| `--
|
|
218
|
-
| `--
|
|
219
|
-
| `--
|
|
220
|
-
| `--
|
|
221
|
-
| `--
|
|
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
|
|
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.
|
|
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
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@puckeditor/cli",
|
|
3
|
-
"version": "0.24.0-canary.
|
|
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",
|