Hosted WordPress and WP-CLI

CWP Snippets includes native WP-CLI commands for working with snippets on any hosted WordPress installation that provides SSH access and WP-CLI. The commands ship inside the plugin and do not depend on Docker, a repository checkout, or a particular hosting provider.

Requirements

  • CWP Snippets 2.x is installed and active on the hosted site.
  • The host permits SSH access and provides WP-CLI.
  • The SSH account can run WP-CLI for the applicable WordPress installation.
  • Mutations identify a WordPress administrator with WP-CLI's global --user argument so immutable revisions have meaningful attribution.

Keep SSH hosts, ports, usernames, private-key locations, and WordPress paths in the operator's SSH or WP-CLI configuration. Do not store credentials in CWP Snippets or in a project repository.

Reading snippets

Start every new site connection with discovery and read-only health checks:

wp cwp-snippets capabilities
wp cwp-snippets schema all
wp cwp-snippets doctor
wp cwp-snippets smoke-test

capabilities identifies supported features and safety guarantees. schema returns the accepted snippet, candidate, revision, audit, and command contracts. doctor checks the installed database schema and revision coverage. smoke-test exercises list, get, validation, and diff behavior while confirming that it did not create a revision. Both health commands emit structured JSON; they return a nonzero exit status when a required check fails.

Use numeric IDs for convenience or durable UUIDs for automation:

wp cwp-snippets list --format=json
wp cwp-snippets list --type=Function --status=active --format=json
wp cwp-snippets get <uuid>
wp cwp-snippets get <uuid> --field=code
wp cwp-snippets revisions list <uuid> --format=json
wp cwp-snippets revisions get <uuid> 7

The database managed by CWP Snippets remains authoritative. Files used by an automation are temporary candidate inputs, not a second snippet store.

Candidate input

Validation, diff, and update accept a partial JSON object. Omitted fields retain their current values. Supported fields are name, type, description, code, css, location, priority, suppress_cache, and version.

{
  "description": "Revised contact list",
  "code": "<?php\n// Proposed snippet code.\n"
}

The input path is resolved on the hosted WordPress server. Use a uniquely named temporary remote file, or use --input=- when the SSH/WP-CLI transport has been verified to forward stdin correctly.

wp cwp-snippets validate <uuid> --input=/tmp/cwp-candidate.json
wp cwp-snippets diff <uuid> --input=/tmp/cwp-candidate.json

Both commands are read-only and return structured JSON. Validation exits with status 1 when the candidate is invalid.

Guarded updates

Read the current revision immediately before every mutation. A stale --expected-revision is rejected without changing the snippet.

wp cwp-snippets update <uuid> \
  --input=/tmp/cwp-candidate.json \
  --expected-revision=7 \
  --dry-run

wp cwp-snippets update <uuid> \
  --input=/tmp/cwp-candidate.json \
  --expected-revision=7 \
  --user=administrator

Changing code or CSS while a snippet is active is rejected unless --allow-active-update is explicit. The safer workflow is to deactivate, update, validate, and reactivate.

wp cwp-snippets deactivate <uuid> --expected-revision=7 --user=administrator
wp cwp-snippets update <uuid> --input=/tmp/cwp-candidate.json --expected-revision=8 --user=administrator
wp cwp-snippets activate <uuid> --expected-revision=9 --user=administrator

Each successful change creates an immutable CWP revision.

Audit attribution

Mutation commands can attach bounded, non-secret context to the immutable revision. WordPress already records the administrator supplied through --user; these optional fields identify the automation project or session:

wp cwp-snippets update <uuid> \
  --input=/tmp/cwp-candidate.json \
  --expected-revision=7 \
  --user=administrator \
  --audit-agent=codex \
  --audit-project=client-site \
  --audit-session=task-123 \
  --audit-note="Update requested during page build"

The same --audit-* options work with activate, deactivate, and restore. An optional --audit-correlation-id can connect a revision to an external job. Audit context is returned by revision reads and displayed in the History timeline. Never put credentials, access tokens, private keys, or personal data in audit fields.

Restoration

Restoring never erases later history. It copies an old snapshot into a new head revision:

wp cwp-snippets restore <uuid> 6 --expected-revision=10 --user=administrator

Function snippets restore inactive by default. Add --activate only when the old Function should be activated immediately after syntax and conflict checks.

Remote execution

Commands can be invoked through a configured WP-CLI alias:

wp @client-staging cwp-snippets list --format=json

They can also be invoked through ordinary SSH when an alias is not appropriate:

ssh client-staging 'cd /path/to/wordpress && wp cwp-snippets list --format=json'

Connection profiles are an operator concern and intentionally remain outside the plugin. Standard WordPress page development continues to use core WP-CLI commands such as wp post get and wp post update; browser QA operates against the hosted site's URL as a separate verification surface.