@webflow/webflow-cli 2.3.0-next.0 → 2.4.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @webflow/webflow-cli
 
+## 2.3.0
+
+### Minor Changes
+
+- 18a2d43: Site ID resolution in `webflow cloud` and `webflow auth` now follows flag > `WEBFLOW_SITE_ID` env var > `webflow.json` order. Previously, `webflow.json` `siteId` took priority over the `WEBFLOW_SITE_ID` environment variable. This makes behavior consistent with the resolver used by all new CLI commands and allows CI/CD env vars to override the checked-in manifest as expected.
+
+  Note: `WEBFLOW_SITE_ID` now also takes precedence over `cloud.workspace_id` in `webflow.json`. A project configured for standalone/workspace deploys that has `WEBFLOW_SITE_ID` set in the environment will route to site-attached instead.
+
+  `webflow cloud deploy` now also respects `WEBFLOW_APP_ID` as an environment variable override for the app ID, and `WEBFLOW_WORKSPACE_ID` when resolving the workspace for a standalone-first deploy.
+
+- 2875d7d: Two behavior changes for CI and agent callers, plus new internal path/archive safety utilities.
+
+  - **`--json` failures now go to stdout as a JSON document.** Previously a failure printed prose to stderr; it is now a single `{ "error": { "message", "context", "missingFlag" } }` document on stdout, written synchronously so a long message is not truncated when stdout is a pipe. `context` carries the operation the command was performing. The failure is also recorded, with its stack, in the session debug log. **Scripts that grep stderr for the failure message need updating.**
+  - **Non-interactive mode is auto-detected in more environments.** In addition to `CI=true` and a missing stdout TTY, `--no-input` is now enabled when stdin has no TTY or when a coding agent's execution environment is detected, so prompts no longer hang agent and CI invocations. A new `--input` flag forces interactive mode, for the case where the detection misreads a human environment.
+
+- 2d85a3e: Add the `webflow skills` namespace — install, update, list, and remove Webflow's first-party agent skills into your coding agents' skill directories.
+
+  - `webflow skills install [names...]` — fetches the skill catalog, writes each skill once into a shared canonical store, and links it into every selected agent's directory. Symlinks by default with an automatic per-target fallback to copying (`--copy` forces copies). Records what it wrote in a lockfile — `webflow-skills-lock.json` for a project, `skills-lock.json` under the CLI config directory for a `--global` install — so `install` with no names restores an existing set reproducibly. `--ref <branch|sha>` pins to a branch or commit.
+  - `webflow skills update [names...]` — re-resolves the pinned ref and updates installed skills, reporting each one as unchanged, updated, moved, reinstalled, or blocked. `--check` reports what would change and writes nothing.
+  - `webflow skills list` — shows what is installed in both scopes with a per-skill status (`up-to-date`, `modified`, `missing`, `unmanaged`) computed by re-hashing what is on disk against the lockfile. Never touches the network. Supports `--fields`, `--sort-by`, and `--order`.
+  - `webflow skills remove [names...]` — unlinks a skill from every agent and deletes its store directory once nothing references it any more.
+
+  Every command supports `--json`, every write command supports `--dry-run`, and `-a, --agent` selects specific coding agents (repeatable, comma-separated, or `all`). `-g, --global` and `-p, --project` select the scope. A skill directory is only ever replaced without `--force` when the CLI itself wrote it and it has not been edited since — and `remove` applies the same rule to deletion, so a skill directory another tool installed (or one you wrote yourself) is left alone unless you pass `--force`.
+
+  Because `--global` installs write into agent directories under your home directory, a skill directory is never replaced or deleted unless the CLI itself wrote it and it has not been edited since — anything else needs `--force`. Archives are extracted through hardened path-containment checks, and `--dry-run` prints every path before any write happens.
+
+  Also fixes a pre-existing issue affecting every command: the "New versions of the following @webflow packages are available" notice was written to stdout even under `--json`, so on any machine with a pending CLI update it appeared ahead of the JSON document and broke `JSON.parse` on the output. The update check is now skipped when `--json` is in effect.
+
+### Patch Changes
+
+- 12bcf3b: Deprecate `webflow cloud list` ahead of removal. The command still works but prints a warning — it lists scaffold templates for `init`, not the user's Cloud apps. Help text is tagged `[Deprecated]`; use `cloud`/`apps` `init --framework` / `--help` for templates (and `webflow apps list` for apps on `@next`).
+- 2dbf0ae: Update `tar` to a patched version that prevents decompression denial-of-service attacks.
+- 84dc26e: Fix the message shown when `webflow devlink sync` fails with a 404. It previously told users to apply for DevLink beta access; it now points to `webflow devlink export` and the migration guide.
+- 0f8a85f: Explain how to recover when a deploy cannot create an app. Hitting an app name that is already taken on the site, or a site that has reached its Cloud app limit, previously reported only "An unknown error occurred". Both now say what happened and how to proceed. The usual cause is `app_id` missing from `webflow.json`, for example on a fresh CI checkout.
+- f7efc3d: Pin the transitive `adm-zip` dependency (pulled in via `@module-federation/enhanced` → `dts-plugin`) to `^0.6.0` via an npm override, fixing a high-severity denial-of-service vulnerability (CVE-2026-39244) where a crafted ZIP file could trigger an unbounded ~4GB memory allocation.
+- b4e08db: Internal refactor: added a `resolveOptionalResourceId` helper to collapse repeated try/catch blocks around `resolveResourceId` in the cloud deploy/preflight code paths. No user-facing behavior change.
+- 903c4a4: Bump transitive `undici` dependency (pulled in via `@module-federation/enhanced`) to 7.28.0 to fix a WebSocket client denial-of-service vulnerability (CVE-2026-12151).
+  - @webflow/data-types@2.1.0
+
 ## 2.2.0
 
 ### Minor Changes

package/README.md

@@ -19,6 +19,7 @@ npm install -g @webflow/webflow-cli
 - [DevLink Export](#devlink-export)
 - [Designer Extensions](#designer-extensions)
 - [Apps (Webflow Cloud)](#apps-webflow-cloud)
+- [Skills (agent skills)](#skills-agent-skills)
 - [Global Options](#global-options)
 
 ---
@@ -36,15 +37,48 @@ webflow auth login --force  # Re-authenticate even if credentials exist
 
 ## Sites
 
-Manage Webflow sites from the CLI.
+Manage Webflow sites from the CLI, and keep a project directory's local source files (page bodies, styles, variables) in sync with the Designer.
 
 ```shell
 webflow sites list                           # List all sites in your workspace
 webflow sites get <siteId>                   # Get details for a specific site
 webflow sites domains --site <siteId>        # List custom domains for a site
 webflow sites publish --site <siteId>        # Publish a site
+webflow sites init                              # Bind this project to an existing site, or create a new one
+webflow sites init --site-id <siteId>            # Bind without the interactive picker (CI/scripted setup)
+webflow sites init --create --name "My Site"     # Create a new site and bind to it
+webflow sites pull                                # Write the site's source files locally
+webflow sites push                                # Push local changes back to the site
+webflow sites push --dry-run                      # Preview what push would send
 ```
 
+> `sites init`, `sites pull` and `sites push` are in beta and ship only in `@next` builds (`npm i -g @webflow/webflow-cli@next`). They aren't registered in the stable release yet.
+
+By default, pages materialize under `src/pages/<slug>.tsw` (the default page as `index.tsw`), components under `src/components/<name>.tsw`, and design-system theme modules under `src/theme/`. Styles and variables have no framework convention to follow, so they land at `site/styles/` and `site/variables/`. A `.webflow/wfs/` lockfile (one file per tracked path, plus an `index.json`) records which site the project is synced with and each file's last-synced hash, so `push` can detect conflicting Designer edits.
+
+Set `site.layout` in `webflow.json` to use a different framework's layout:
+
+```json
+{
+  "siteId": "...",
+  "site": {
+    "layout": { "preset": "nextjs" }
+  }
+}
+```
+
+| Preset            | Shape                                                                                                                        |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `library`/`astro` | Flat `src/pages/<slug>.tsw` + `src/components/<name>.tsw` (the default)                                                      |
+| `nextjs`          | Next.js App Router — one folder per route segment, nested `page.tsw` (`src/app/<slug>/page.tsw`, home at `src/app/page.tsw`) |
+| `nextjs-pages`    | Next.js Pages Router — flat `pages/<slug>.tsw`                                                                               |
+
+A page nested under a Designer Page Folder (e.g. `/blog/en/about`) mirrors that subpath locally (`<pagesRoot>/blog/en/about.tsw`, or `.../blog/en/about/page.tsw` under the `nextjs` shape). A component's Designer group maps to a local subfolder under `componentsRoot` — `src/components/ui/Card.tsw` and a flat `src/components/Card.tsw` are distinct components. Explicit `pagesRoot`/`componentsRoot`/`pagesShape` (`"flat"` or `"nested"`) override a preset's defaults, or can be set without a preset at all. The theme root isn't configured directly — it's derived as a sibling of whatever `pagesRoot` and `componentsRoot` have in common, so `src/pages` + `src/components` puts theme modules at `src/theme`.
+
+Pulled `.tsw` files are formatted with Prettier, honoring the project's own Prettier config when it has one.
+
+A project is bound to one site: the lockfile records which site it was pulled from, and both commands refuse to run against a different one. Use `sites pull --site-id <other> --reset` to repoint a project at another site — it discards the existing sync state and pulls from scratch.
+
 ### `sites list` options
 
 | Flag                | Description                                                                                                      |
@@ -61,6 +95,34 @@ webflow sites publish --site <siteId>        # Publish a site
 | `--page <pageId>`     | Publish a single page instead of the full site             |
 | `--dry-run`           | Preview what would be published without triggering a build |
 
+### `sites init` options
+
+| Flag                  | Description                                                     |
+| --------------------- | --------------------------------------------------------------- |
+| `--site-id <siteId>`  | Skip the interactive picker and bind to this site ID            |
+| `--create`            | Create a new Webflow site instead of binding to an existing one |
+| `--name <name>`       | Name for the new site (implies `--create`; skips the prompt)    |
+| `--api-token <token>` | Use this token instead of the stored session                    |
+
+### `sites pull` options
+
+| Flag                  | Description                                                                                                                                            |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--site-id <siteId>`  | Pull this site instead of the one in `webflow.json`, without rebinding the project. Needs `--reset` if the project is already synced with another site |
+| `--force`             | Overwrite local files that changed both locally and in the Designer since the last sync (they're left alone by default)                                |
+| `--reset`             | Discard the existing local sync state and pull from scratch                                                                                            |
+| `--json`              | Output the pulled manifest and file list as JSON                                                                                                       |
+| `--api-token <token>` | Use this token instead of the stored session                                                                                                           |
+
+### `sites push` options
+
+| Flag                  | Description                                                                                          |
+| --------------------- | ---------------------------------------------------------------------------------------------------- |
+| `--dry-run`           | List the files that would be pushed without sending them                                             |
+| `--force`             | Skip upstream conflict checks and re-push every tracked file, not just the ones that changed locally |
+| `--json`              | Output the push results as JSON                                                                      |
+| `--api-token <token>` | Use this token instead of the stored session                                                         |
+
 ---
 
 ## CMS
@@ -286,6 +348,124 @@ created/updated/skipped/errors breakdown and exits non-zero if any key fails
 
 ---
 
+## Skills (agent skills)
+
+Install Webflow's first-party agent skills into your coding agents, so an agent
+working in your repo knows how to use Webflow without being told each time.
+
+> **These commands write outside the current project.** A `--global` install
+> writes into your coding agents' skill directories under your home directory. Two
+> rules bound that: nothing is replaced or deleted unless the CLI wrote it and it
+> has not been edited since (anything else needs `--force`), and `--dry-run` prints
+> every path before a single byte is written. Run it first if you are unsure.
+
+```shell
+webflow skills install                          # Restore from a lockfile, or pick interactively
+webflow skills install webflow-cms --dry-run    # Preview every path that would be written
+webflow skills install webflow-cms --agent claude-code,cursor
+webflow skills install --all-skills --all-agents --global
+webflow skills list                             # What is installed, and where
+webflow skills update --check                   # Report what would change; write nothing
+webflow skills update
+webflow skills remove webflow-cms --dry-run     # Preview exactly what is deleted
+```
+
+### Scope: project or global
+
+| Scope               | Where skills go                             | Lockfile                                 |
+| ------------------- | ------------------------------------------- | ---------------------------------------- |
+| Project (default)   | Agent directories under the current project | `webflow-skills-lock.json` (commit this) |
+| Global (`--global`) | Agent directories under your home directory | `skills-lock.json` in the CLI config dir |
+
+The project lockfile is meant to be committed: a teammate (or CI) runs
+`webflow skills install` with no arguments and gets the same skills at the same
+commit. `list` shows **both** scopes by default so a global install is never
+invisible.
+
+Each skill's files are written once into a shared canonical store and linked into
+every selected agent's directory, so installing for twenty agents costs one copy.
+Symlinks are used by default, with an automatic per-target fallback to copying
+when the filesystem or platform refuses them; `--copy` forces copies everywhere.
+
+### Safety
+
+`install` and `update` refuse to overwrite a skill directory unless the CLI
+wrote it and it has not been edited since — anything locally modified, or
+anything that exists without a matching lockfile entry, is reported as blocked
+and needs `--force`. `--dry-run` prints the exact absolute paths that would be
+written or deleted and makes no changes, which is the flag to reach for first
+when an agent chose the arguments.
+
+### `skills install` options
+
+| Flag                  | Description                                                            |
+| --------------------- | ---------------------------------------------------------------------- |
+| `-a, --agent <ids>`   | Target agent; repeatable, comma-separated, or `all`                    |
+| `--all-agents`        | Install for every supported agent                                      |
+| `--all-skills`        | Install every skill in the catalog                                     |
+| `-g, --global`        | Install into your home directory instead of the current project        |
+| `-p, --project`       | Install into the current project (the default)                         |
+| `--copy`              | Copy files instead of symlinking from the shared store                 |
+| `--ref <branch\|sha>` | Pin to a branch or 40-character commit SHA (default: `main`)           |
+| `--force`             | Replace destinations that were modified locally or installed elsewhere |
+| `-y, --yes`           | Skip the confirmation prompt                                           |
+| `--dry-run`           | Print every path that would be written; change nothing                 |
+| `--json`              | Output as JSON                                                         |
+
+### `skills update` options
+
+| Flag                  | Description                                       |
+| --------------------- | ------------------------------------------------- |
+| `--check`             | Report what would change without writing anything |
+| `-g, --global`        | Update the home-directory install                 |
+| `-p, --project`       | Update the current project's install              |
+| `--ref <branch\|sha>` | Re-pin to a different branch or commit SHA        |
+| `--force`             | Overwrite skills that were modified locally       |
+| `-y, --yes`           | Skip the confirmation prompt                      |
+| `--dry-run`           | Preview without writing                           |
+| `--json`              | Output as JSON                                    |
+
+### `skills list` options
+
+| Flag                | Description                                                                   |
+| ------------------- | ----------------------------------------------------------------------------- |
+| `-g, --global`      | Only the home-directory install                                               |
+| `-p, --project`     | Only the current project's install                                            |
+| `-a, --agent <ids>` | Only skills linked into these agents; repeatable and comma-separated          |
+| `--fields <fields>` | Comma-separated columns (name, dir, description, status, mode, agents, scope) |
+| `--sort-by <field>` | Sort by name, dir, status, or scope (default: name)                           |
+| `--order <dir>`     | `asc` or `desc` (default: `asc`)                                              |
+| `--json`            | Output as JSON                                                                |
+
+`status` is computed offline by re-hashing what is on disk against what the
+lockfile recorded: `up-to-date`, `modified` (edited since install), `missing`
+(recorded but gone), or `unmanaged` (present with no lockfile entry). Checking
+for _upstream_ changes needs the network and is `skills update --check`'s job.
+
+### `skills remove` options
+
+| Flag                | Description                                                   |
+| ------------------- | ------------------------------------------------------------- |
+| `-a, --agent <ids>` | Only unlink from these agents; repeatable and comma-separated |
+| `--all`             | Remove every installed skill for the scope                    |
+| `-g, --global`      | Remove from the home-directory install                        |
+| `-p, --project`     | Remove from the current project's install                     |
+| `--force`           | Also remove skill directories that have no lockfile entry     |
+| `-y, --yes`         | Skip the confirmation prompt                                  |
+| `--dry-run`         | Print exactly what would be deleted; change nothing           |
+| `--json`            | Output as JSON                                                |
+
+Removing a skill from one agent unlinks it there and keeps the shared store as
+long as another agent still references it; the store directory is deleted once
+nothing does.
+
+`remove` only deletes what the lockfile records. A skill directory with no
+lockfile entry was not installed by this CLI — it may belong to another tool, or
+be hand-written — so `--all` leaves it alone and names it in a warning, and
+naming it directly is refused. `--force` opts in to removing those too.
+
+---
+
 ## Global Options
 
 Available on all commands:

package/dist/cloud-scaffolds/astro/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

package/dist/cloud-scaffolds/astro/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

package/dist/cloud-scaffolds/astro/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+	"files.associations": {
+		"wrangler.json": "jsonc"
+	}
+}

package/dist/cloud-scaffolds/astro/public/.assetsignore

@@ -0,0 +1,2 @@
+_worker.js
+_routes.json

package/dist/cloud-scaffolds/nextjs/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+	"files.associations": {
+		"wrangler.json": "jsonc"
+	}
+}

package/dist/extension-scaffolds/default/.eslintrc

@@ -0,0 +1,25 @@
+{
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "./tsconfig.json"
+  },
+  "plugins": ["@typescript-eslint", "promise"],
+  "rules": {
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/no-floating-promises": "error",
+    "@typescript-eslint/no-misused-promises": [
+      "error",
+      { "checksVoidReturn": false }
+    ],
+    "@typescript-eslint/no-unused-vars": "error",
+    "no-async-promise-executor": "error",
+    "require-await": "error",
+    "promise/catch-or-return": "error"
+  }
+}

package/dist/extension-scaffolds/react/.eslintrc

@@ -0,0 +1,25 @@
+{
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "./tsconfig.json"
+  },
+  "plugins": ["@typescript-eslint", "promise"],
+  "rules": {
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/no-floating-promises": "error",
+    "@typescript-eslint/no-misused-promises": [
+      "error",
+      { "checksVoidReturn": false }
+    ],
+    "@typescript-eslint/no-unused-vars": "error",
+    "no-async-promise-executor": "error",
+    "require-await": "error",
+    "promise/catch-or-return": "error"
+  }
+}

package/dist/extension-scaffolds/typescript-alt/.eslintrc

@@ -0,0 +1,25 @@
+{
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "./tsconfig.json"
+  },
+  "plugins": ["@typescript-eslint", "promise"],
+  "rules": {
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/no-floating-promises": "error",
+    "@typescript-eslint/no-misused-promises": [
+      "error",
+      { "checksVoidReturn": false }
+    ],
+    "@typescript-eslint/no-unused-vars": "error",
+    "no-async-promise-executor": "error",
+    "require-await": "error",
+    "promise/catch-or-return": "error"
+  }
+}