---
name: pp-crocoblock
description: "Operate Crocoblock data and review changes across your WordPress workflows. Trigger phrases: `revisa los campos de JetEngine`, `compara los datos de este CCT`, `revisa los registros de JetFormBuilder`, `busca solapamientos en las reservas`, `revisa qué filtros necesitan reindexarse`, `use crocoblock`, `run crocoblock`."
author: "bobe"
license: "Apache-2.0"
argument-hint: "<command> [args] | install cli|mcp"
allowed-tools: "Read Bash"
metadata:
  openclaw:
    requires:
      bins:
        - crocoblock-pp-cli
    install:
      - kind: go
        bins: [crocoblock-pp-cli]
        module: github.com/mvanhorn/printing-press-library/library/developer-tools/crocoblock/cmd/crocoblock-pp-cli
---
<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/developer-tools/crocoblock/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Crocoblock — Printing Press CLI

## Build from source

Use the Printing Press catalog to install the CLI and agent skill. The source-build instructions also work directly from this module. A new catalog entry becomes installable after its PR is merged and the catalog workflows finish.

### Build from source

From this CLI module directory, use Go 1.26.10:

```bash
GOTOOLCHAIN=go1.26.10 go build -o ./crocoblock-pp-cli ./cmd/crocoblock-pp-cli
GOTOOLCHAIN=go1.26.10 go install ./cmd/crocoblock-pp-cli ./cmd/crocoblock-pp-mcp
crocoblock-pp-cli --version
```

`go install` writes to `GOBIN`, or `$(go env GOPATH)/bin` when `GOBIN` is unset. Put that directory on the invoking agent's `PATH`. The local MCP binary uses the same WordPress environment variables as the CLI.


**Installation selection:** install a missing binary using **Prerequisites: Install the CLI**, or use **Build from source** when operating from a source checkout.

## Prerequisites: Install the CLI

This skill drives the `crocoblock-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install crocoblock --cli-only
   ```
2. Verify: `crocoblock-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.10 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead:

```bash
go install github.com/mvanhorn/printing-press-library/library/developer-tools/crocoblock/cmd/crocoblock-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

Inspect the installed JetPlugins, edit supported data with request previews, and compare local snapshots before a site release. Keep schemas, form observations, reservations and filter maintenance evidence tied to the site and plugin versions that produced them.

## When to Use This CLI

Use this CLI to inspect and operate supported JetEngine, JetFormBuilder, JetBooking, JetAppointment and JetSmartFilters contracts on an authorized WordPress site. Use local comparisons to review schema and data changes, relation integrity, observed form-field names, reservation overlaps and recorded filter maintenance needs. Check provenance and coverage before treating a local result as current.

## Anti-triggers

Do not use this CLI for:
- Do not use this CLI to buy or activate Crocoblock licenses or manage the vendor account.
- Do not use this CLI for universal WordPress administration, visual page design or unrelated JetPlugins.
- Do not use this CLI to submit live payment or mail forms or to assume a reservation is commercially available.
- Do not use a local audit with incomplete coverage to certify production integrity.

## Unique Capabilities

### Revisión de entregas
- **`schema diff`** — Muestra qué tipos, campos y definiciones cambiaron entre dos revisiones del sitio.

  _Úsalo antes de una entrega para revisar cambios estructurales comprobables._

  ```bash
  crocoblock-pp-cli schema diff --before baseline.db --after candidate.db --agent
  ```
- **`cct reconcile`** — Compara registros entre instantáneas por una clave única y muestra diferencias en campos seleccionados.

  _Úsalo para comprobar que dos revisiones conservan los datos esperados._

  ```bash
  crocoblock-pp-cli cct reconcile rooms --before baseline.db --after candidate.db --key external_id --fields external_id,title --agent
  ```
- **`relations audit`** — Detecta aristas duplicadas y ausencias comprobables en inventarios CCT completos sin filtros. Los extremos WordPress ausentes quedan unknown porque el inventario excluye papelera y puede omitir objetos restringidos.

  _Úsalo después de cambios de contenido para revisar relaciones, sin interpretar un permiso denegado como un huérfano._

  ```bash
  crocoblock-pp-cli relations audit --db candidate.db --agent
  ```

### Mantenimiento de formularios y filtros
- **`forms field-usage`** — Compara los campos actuales de un formulario con los nombres presentes en registros seleccionados.

  _Úsalo para encontrar nombres históricos o campos nunca observados en la muestra, sin inferir errores de validación._

  ```bash
  crocoblock-pp-cli forms field-usage 42 --db candidate.db --agent
  ```
- **`filters impact`** — Identifica candidatos de reindexación por cambios registrados para filtros custom_fields de JetSmartFilters 3.8.6.2 con _query_var y _source_custom_field válidos; otros proveedores o versiones quedan unknown.

  _Úsalo después de una edición para decidir qué mantenimiento del índice requiere revisión._

  ```bash
  crocoblock-pp-cli filters impact --db candidate.db --since-event 1 --agent
  ```

### Revisión de reservas
- **`reservations overlaps`** — Señala solapamientos por recurso y evalúa capacidad con una política explícita y ambas capturas completas de JetBooking 4.1.3.1 y JetAppointment 2.5.3. Sólo admite citas slot/range registradas; no expande recurrencias.

  _Úsalo para revisar posibles choques sin confundir un solapamiento con una reserva inválida._

  ```bash
  crocoblock-pp-cli reservations overlaps --db candidate.db --policy policy.json --agent
  ```

## Command Reference

The adapter exposes **61 service commands: 55 base operations and six local analyses**. The tables list actual command paths and positional arguments; prepend `crocoblock-pp-cli`. Framework utilities such as `doctor`, `agent-context`, `which`, profiles and the learning loop are additional commands.

Run a concrete command's help, such as `crocoblock-pp-cli engine configuration --help`, for current defaults and constraints. Common flags include `--agent`, `--json`, `--select`, `--dry-run` and `--data-source`. Wherever `--input FILE` is shown, the command also accepts `--input -` or `--data JSON`; supply exactly one payload source. Read-only native JetEngine commands accept argument objects, not arbitrary writes. Relation read limits trim an upstream unpaginated collection; they do not reduce the upstream fetch.

### Discovery and capture

| Command | Arguments and behavior |
| --- | --- |
| `discover` | Inspect plugin versions, registered routes and permission gaps. |
| `sync` | `--db FILE --resources CSV --full --strict`; optional `--cct TYPE --fields CSV`, `--record-form ID`, `--object-types CSV`, `--max-pages N`. |

### JetEngine

| Command | Arguments and behavior |
| --- | --- |
| `engine configuration` | Optional `--input FILE` to select native configuration parts. |
| `engine website` | Optional `--input FILE` to select native website configuration parts. |
| `engine macros` | Optional `--exclude CSV` or native argument object via `--input FILE`. |
| `engine modules` | `--operation list / activate / deactivate`; use `--modules CSV` for changes, or `--input FILE`. |
| `engine create-cct` | `--input FILE` with the native CCT definition. |
| `engine create-cpt` | `--input FILE` with the native custom post type definition. |
| `engine create-taxonomy` | `--input FILE` with the native taxonomy definition. |
| `engine create-meta-box` | `--input FILE` with the native metadata box definition. |
| `engine create-query` | `--input FILE` with the native query definition. |
| `engine create-listing` | `--input FILE` with the native listing definition. |
| `engine create-glossary` | `--input FILE` with the native glossary definition. |

### CCT data

| Command | Arguments and behavior |
| --- | --- |
| `cct list <type>` | `--limit N` (1–500), `--offset N`, `--order asc / desc`, `--order-by FIELD`, `--search TEXT`, `--search-by CSV`, repeatable `--where field=value`. |
| `cct get <type> <id>` | Read one item. |
| `cct create <type>` | `--input FILE` with declared CCT fields. |
| `cct update <type> <id>` | `--input FILE` with fields to update. |
| `cct delete <type> <id>` | Delete the selected item. |

### Relations

| Command | Arguments and behavior |
| --- | --- |
| `relations definitions` | `--limit N` (1–500), `--offset N`. |
| `relations list <relation-id>` | `--limit N` (1–500), `--offset N`. |
| `relations parents <relation-id> <object-id>` | `--limit N` (1–500), `--offset N`. |
| `relations children <relation-id> <object-id>` | `--limit N` (1–500), `--offset N`. |
| `relations update <relation-id>` | `--context child / parent --mode append / replace / disconnect --input FILE`. |

### Forms and submitted records

| Command | Arguments and behavior |
| --- | --- |
| `forms list` | `--limit N` (1–100), `--page N`, `--status STATUS` (default `any`). |
| `forms get ID` | Read one form with sensitive metadata redacted. |
| `forms create` | `--input FILE`; draft by default. |
| `forms update ID` | `--input FILE`; preserve unrelated content and metadata. |
| `forms trash ID` | Move the selected form to trash. |
| `forms fields ID` | Read declared fields; use `--select fields` to project the field list. |
| `records list` | `--form ID`, `--limit N` (1–100), `--page N`, `--sort ASC / DESC`. Use `--form` for a verified form association. |
| `records fields ID` | `--fields CSV`, `--limit N` (1–10000); opt-in `--include-values` requires selected fields. |

### Bookings and appointments

| Command | Arguments and behavior |
| --- | --- |
| `bookings list` | `--filters JSON`, `--limit N` (1–1000), `--offset N`, `--mode all / upcoming / past`. |
| `bookings config RESOURCE_ID` | Read configuration for one booking resource. |
| `bookings create` | `--input FILE`. |
| `bookings update ID` | `--input FILE`. |
| `bookings delete ID` | Delete the selected booking. |
| `appointments list` | `--filters JSON`, `--limit N` (1–1000), `--offset N`, `--mode all / upcoming / past`. |
| `appointments get ID` | Read one appointment. |
| `appointments create` | `--input FILE --timezone IANA_OR_UTC`. |
| `appointments update ID` | `--input FILE --timezone IANA_OR_UTC`. |
| `appointments delete ID [ID...]` | Delete the explicitly selected appointment IDs. |
| `appointments providers SERVICE_ID` | Read providers for one service. |
| `appointments slots SERVICE_ID` | `--date YYYY-MM-DD --timezone IANA_OR_UTC`; optional `--provider ID`. May persist excluded days. |

### Filters and REST-exposed metadata

| Command | Arguments and behavior |
| --- | --- |
| `filters list` | `--limit N` (1–100), `--page N`, `--search TEXT`, `--status publish / draft / trash`. |
| `filters get <id>` | Read one filter. |
| `filters create` | `--input FILE`. |
| `filters update <id>` | `--input FILE`. |
| `filters duplicate <id>` | Duplicate the selected filter. |
| `filters trash <id>` | Move the selected filter to trash. |
| `filters restore <id>` | Restore the selected trashed filter. |
| `filters reindex` | `--ssh user@host --wp-path /absolute/path`; optional `--ssh-key FILE`. Site check and local receipt required. |
| `fields list` | `--post-type SLUG` (default `post`); compare declared metadata with the REST schema. |
| `fields get ID` | `--fields CSV` required; optional `--post-type SLUG`. |
| `fields update ID` | `--input FILE --snapshot PRIVATE_FILE`; optional `--post-type SLUG`. |
| `fields restore` | `--snapshot PRIVATE_FILE`; checks current selected values before restore. |

### Six local analyses

| Command | Arguments and behavior |
| --- | --- |
| `schema diff` | `--before FILE --after FILE`; optional `--resources CSV`, repeatable `--identity resource=FIELD_PATH`, `--limit N` (default 500). |
| `cct reconcile <type>` | `--before FILE --after FILE --key FIELD --fields CSV`; `--limit N` (1–500, default 100). |
| `relations audit [relation-id]` | `--db FILE`; `--limit N` (1–500, default 100). |
| `forms field-usage ID` | `--db FILE`; `--limit N` (1–10000, default 100); totals cover the full captured sample. |
| `reservations overlaps` | `--db FILE --policy FILE`; `--limit N` (default 1000); all captured rows are analyzed. |
| `filters impact` | `--db FILE`; `--since-event N` is exclusive; `--limit N` (default 500). |

### Data sources and operational limits

| Surface | Source | What the result establishes |
| --- | --- | --- |
| `discover`, `engine`, CCT CRUD, relation reads/updates, forms CRUD/fields, `records`, `bookings`, `appointments`, filter CRUD/reindex, `fields` | Live WordPress or explicitly configured SSH; use `--data-source live` | The response from the selected site at execution time, subject to permissions and plugin contracts |
| `sync` | Live reads saved to local SQLite; use `--data-source live` | Captured resources with site, plugin versions, scope, timestamp and completeness |
| `schema diff`, `cct reconcile`, `relations audit`, `forms field-usage`, `reservations overlaps`, `filters impact` | Existing SQLite captures; use `--data-source local` | Analysis of the captured sample and journal; never an automatic live refresh |

The six analyses reject `--data-source live`. Missing, denied, capped, incompatible or incomplete coverage is unknown/error, not a clean result or an empty collection. Check capture timestamps, site, scope and plugin versions. Collection limits can truncate a response; inspect totals and coverage rather than interpreting the displayed rows as the full site.

Use `--input private.json` or `--input -` for JSON payloads when the command exposes it. These avoid placing personal data or secrets in command arguments and shell history. `--data` is available but has that exposure. Form action secrets are redacted. `records fields` reports names and presence by default; values require both `--fields` and `--include-values`, and secret keys remain redacted. CCT capture values are restricted to explicitly selected `--fields`; treat the resulting database as private.

A dry run performs no network or payload-file access. It verifies command/flag routing and previews the operation; it does not validate a fixture, permission, payload schema or current remote state. Inspect help, preview, execute once, and verify the result. Never automatically repeat a write after a timeout, ambiguous transport response, or a `mutation_applied`/receipt failure: the remote mutation may already have succeeded. Shared retry-related flags do not make plugin writes replay-safe.

`forms create` defaults to a draft. Updates preserve unrelated raw blocks and metadata; `forms trash` moves the form to trash. `forms fields` can extract declared fields from stored draft blocks without publishing. `fields` handles only JetEngine-declared post metadata that WordPress exposes in its REST schema; unknown or unregistered keys are rejected. `fields update --snapshot private.json` saves a private before/after file separate from SQLite. Restore compares fresh selected values with the recorded after-state before writing. This is a concurrency check, not atomic compare-and-swap (CAS); another writer can still race the check.

`appointments slots` can cause the provider plugin to persist excluded days while calculating availability. Treat it as potentially mutating, and supply the explicit date and timezone. Availability output is not a commercial guarantee. `filters reindex` checks the remote WordPress site URL against the configured site before executing the native indexer over SSH/WP-CLI, then records a verified receipt locally. A successful index rebuild with a failed receipt must not be blindly repeated.

### MCP surface and local file workflows

The CLI retains all 61 Crocoblock capabilities. In normal mode the MCP server exposes 56 of them plus 19 framework tools (75 tools total); read-only server mode exposes a smaller set. MCP callers cannot choose server-side input files or output destinations. Five Crocoblock commands therefore remain CLI-only: `schema diff`, `cct reconcile`, `reservations overlaps`, `fields update` and `fields restore`. The framework `import` command is also CLI-only because it has no inline payload alternative.

Use the local CLI for snapshot comparisons, reservation policy files and field backup/restore. Through MCP, `forms field-usage`, `filters impact` and `relations audit` read the database selected by the server's `CROCOBLOCK_DB`; `sync` populates that same configured store. File input is omitted from MCP mutation tools; pass a JSON object inline through their data parameter. Filter reindexing can use the SSH identity already configured for the server account. No file-path bypass is supported.

### Capture workflow

`sync --full --strict` captures the selected collections. Both flags default to true; this adapter has no incremental cursor mode. `--strict` returns a nonzero result if any selected resource fails. `--max-pages` defaults to 10; hitting the cap leaves coverage incomplete. Disabling strict failure reporting does not make incomplete data complete.

Set `CROCOBLOCK_DB` before both mutations and captures when they must share a journal. Passing `--db` to `sync` or an analysis only selects that invocation's SQLite file; it does not redirect later write commands. This distinction is necessary for `filters impact` to see the same site's captured filters, write events and reindex receipts.

```bash
export CROCOBLOCK_DB="$PWD/candidate.db"

# Default resources: schema, forms, filters, bookings, appointments, relations.
crocoblock-pp-cli sync --db "$CROCOBLOCK_DB" --full --strict --agent

# Capture selected CCT values, including the reconciliation business key.
crocoblock-pp-cli sync --resources cct --cct rooms --fields external_id,title --db "$CROCOBLOCK_DB" --full --strict --agent

# Capture declared fields and record presence for one explicit form; no submitted values.
crocoblock-pp-cli sync --resources forms,records --record-form 42 --db "$CROCOBLOCK_DB" --full --strict --agent

# Capture accessible WordPress IDs needed for relation endpoint checks.
crocoblock-pp-cli sync --resources relations,objects --object-types post --db "$CROCOBLOCK_DB" --full --strict --agent
```

Replace `rooms`, field names, form ID and object types with identifiers discovered on the authorized site. `--resources` accepts `schema,forms,filters,bookings,appointments,relations,cct,records,objects`. CCT rows require `--cct` and explicit `--fields`; records require `--record-form`; object inventories require `--object-types`. Relation audits need complete inventories for the endpoint types in their definitions; a `post` inventory cannot establish the existence of a CCT or another object type.

The default `schema diff` compares relations as well as configuration, CCT definitions, post types, taxonomies, meta boxes, queries, forms and filters.