CLI reference

@decocms/blocks-cli ships the command-line tools around a Deco site: migration and upgrade codemods, Fast Deploy content sync, a content pull bot, and observability configuration checks. This page lists each one with its flags, defaults and exit codes. The most-used command, generate, has its own page: Code generation.

Running the commands

The package installs as a development dependency. Its commands are TypeScript files run through tsx, so run them with npx -p, which works whether or not the package is installed locally:

npx -p @decocms/blocks-cli deco-upgrade-6-to-7 --help

Two scripts have no command name; run those by file path with tsx, as shown in their sections. Every named command accepts -h or --help.

Several commands are dry runs by default: they print what they would change and write nothing until you pass --write.

Migration and upgrade

deco-migrate

Migrates a Fresh/Preact/Deno storefront to TanStack Start, React 19 and Cloudflare Workers. It rewrites the source directory in place, so run it on a copy or a fresh branch. The phases are: analyze, scaffold, transform, cleanup, report (writes MIGRATION_REPORT.md), verify, bootstrap (installs dependencies and generates), compile, and a final cleanup audit. Migrating from Fresh and Deno explains the whole procedure.

npx -p @decocms/blocks-cli deco-migrate --source ./my-store --dry-run --verbose

An optional .deco-migrate.config.json at the source root adjusts which sections get section conventions: { "sectionConventions": { "extend": { "sync": [], "eagerSync": [], "listingCache": [], "staticCache": [] } } }, or "replace" instead of "extend".

Exit codes: 0 success; 1 unexpected error; 2 unsupported source layout, a failed verification, or (with --strict) compile or audit errors.

deco-post-cleanup

Audits a migrated site for dead code and boilerplate the framework now provides. Read-only unless you pass --fix.

npx -p @decocms/blocks-cli deco-post-cleanup --source ./my-store --json

deco-htmx-analyze

Read-only inventory of hx-* attributes in a Fresh site, so you can size the rewrite to React before migrating. v7 has no htmx runtime.

npx -p @decocms/blocks-cli deco-htmx-analyze --source ./my-store --top 10

deco-reconcile

A migration takes time, and the original site keeps changing meanwhile. deco-reconcile collects everything committed to the original repository since the migration cut and writes one patch per file, with suggested target paths, for you to port into the migrated repository. It writes nothing into the target tree except its output folder.

npx -p @decocms/blocks-cli deco-reconcile --source ../my-store-fresh --target ../my-store --snapshot <cut-sha>

Exit codes: 0 success; 2 bad arguments or a git failure. Feed the source head it reports back as --snapshot next time.

deco-upgrade-6-to-7

Upgrades a site that is already on TanStack Start from @decocms/start 6.x and @decocms/apps 5.x to the current split packages. It rewrites import paths (including renamed exports) and updates package.json. Upgrading from @decocms/start 6.x is the full procedure.

npx -p @decocms/blocks-cli deco-upgrade-6-to-7 --write

Exit codes: 0 success or dry run; 2 the source folder doesn't exist.

Fast Deploy content

Both commands write to Cloudflare KV over the REST API. With --write they need credentials in the environment: CF_ACCOUNT_ID (or CLOUDFLARE_ACCOUNT_ID), CF_API_TOKEN (or CLOUDFLARE_API_TOKEN, with permission to edit Workers KV) and CF_KV_NAMESPACE_ID (or the DECO_KV namespace id read from wrangler.jsonc). Cloudflare Workers Builds provides the account and token variables itself. Deploying and Fast Deploy shows where they go in a pipeline.

deco-sync-blocks-to-kv

Writes the content snapshot for one deployment, and can mark that deployment live.

npx -p @decocms/blocks-cli deco-sync-blocks-to-kv --write --all --deployment-id "$WORKERS_CI_COMMIT_SHA"

npx -p @decocms/blocks-cli deco-sync-blocks-to-kv --set-live --deployment-id "$WORKERS_CI_COMMIT_SHA"

Use this command rather than writing KV yourself: the revision it stores must match the one the Worker computes byte for byte.

Exit codes: 0 success, nothing to do, or dry run; 2 bad folder, missing credentials or arguments, or a failed verification.

deco-migrate-blocks-to-kv

One-time seed of a deployment's content into KV, for turning Fast Deploy on for an existing site.

npx -p @decocms/blocks-cli deco-migrate-blocks-to-kv --deployment-id <commit-sha> --write

Exit codes match deco-sync-blocks-to-kv.

Content sync

deco-sync-blocks-bot

Pulls the production content (GET <origin>/.decofile) into .deco/blocks/, one file per block, so a scheduled job can open a pull request with what editors published. It protects some blocks by default: blocks matching --deny, and blocks holding encrypted secret references, are never overwritten or deleted.

npx -p @decocms/blocks-cli deco-sync-blocks-bot --origin https://www.example.com --dry-run

Exit codes: 0 done, with or without changes; 1 the plaintext-secret check failed; 2 usage, network or payload error (nothing written).

Observability configuration

deco-cf-observability

Writes Cloudflare's observability block (logs and traces) into wrangler.jsonc. Without --write it prints a diff.

npx -p @decocms/blocks-cli deco-cf-observability --write --traces-rate 0.01

Pass --traces-rate 0.01. The default of 0.1 is above the rate deco-audit-observability accepts, so the audit flags a file written with it.

Exit codes: 0 nothing to change (or written); 1 a change is needed and --write wasn't passed; 2 the file is missing or invalid.

deco-audit-observability

Checks the observability block in wrangler.jsonc: that observability, logs and traces are on, that the trace sampling rate is at most 0.01, that logs aren't under-sampled, and that data is kept somewhere. It also checks the rest of the telemetry wiring the migration scaffold sets up, such as the version_metadata binding, the tail consumer and the telemetry endpoint variables, so a wrangler.jsonc written by hand can get findings for those too.

npx -p @decocms/blocks-cli deco-audit-observability --mode block --github

Exit codes: 0 no findings, or any findings in warn mode; 1 error findings in block mode; 2 the file is missing or can't be parsed. Use --mode block to make it a CI gate.

Eitri

deco-eitri

Ships with @decocms/eitri, not @decocms/blocks-cli. See Eitri apps.

npx deco-eitri init

npx deco-eitri generate --root apps/mobile

• deco-eitri init [--root <dir>] creates tsconfig.json and src/eitri-env.d.ts, never overwriting existing files.
• deco-eitri generate [flags] runs generate with --platform eitri, forwarding every flag.

Exit codes: 0 success; 1 no command, an unknown command, or a generation failure.

Scripts without a command name

These ship in @decocms/blocks-cli and run by path.

audit-secrets.ts

Scans source for credentials written into loaders and actions, and for the secrets SDK (@decocms/blocks/sdk/crypto) imported from a "use client" file.

npx tsx node_modules/@decocms/blocks-cli/scripts/audit-secrets.ts --source ./src --mode block

Flags: --source <dir> (default .), --json, --mode warn|block (default warn), --github. Exit codes: 0 no findings or warn mode; 1 error findings in block mode; 2 the source folder is missing.

tailwind-lint.ts

Finds class issues when moving from Tailwind v3 to v4 and DaisyUI v4 to v5: renamed classes, arbitrary values that have a built-in equivalent (px-[16px] becomes px-4), and responsive variants written in an order that v4's cascade gets wrong. It reports by default; --fix rewrites the files. It scans src/ unless you pass a folder.

npx tsx node_modules/@decocms/blocks-cli/scripts/tailwind-lint.ts src/sections --fix

Related

• Code generation covers generate.
• Migrating from Fresh and Deno and Upgrading from @decocms/start 6.x walk through the migration commands in order.
• Observability explains what the observability settings control.