Skip to main content

WP-CLI Usage

Common Commands​

# Database operations
wp db export /tmp/opshell-$(date +%Y%m%d).sql
wp db import /tmp/opshell-backup.sql
wp db query "SELECT * FROM wp_options WHERE option_name LIKE '%opshell%'"

# Plugin management
wp plugin list --status=active
wp plugin update --all
wp plugin deactivate wpcodebox2 --debug

# Post operations
wp post list --post_type=page --fields=ID,post_title,post_date
wp post update 123 --post_title="New Title"
wp post create --post_type=page --post_title="Test" --post_status=draft

# Option management
wp option get opshell_reoon_api_key
wp option update opshell_smtp_host "smtp.example.com"

# Cache
wp cache flush
wp lscache-purge all

# User management
wp user list --role=administrator
wp user create editor-user editor@example.com --role=editor

WPCodeBox2 Snippet Management​

# List snippets
wp db query "SELECT id, title, enabled, hook FROM wp_wpcb_snippets"

# Get snippet code
wp db query "SELECT code FROM wp_wpcb_snippets WHERE id = 1"

# Update snippet code via file
wp eval 'file_put_contents("/tmp/code.php", $wpdb->get_var("SELECT code FROM wp_wpcb_snippets WHERE id = 1"));'
# Edit code, then:
wp eval '
$code = file_get_contents("/tmp/updated-code.php");
global $wpdb;
$wpdb->update("wp_wpcb_snippets", ["code" => $code], ["id" => 1]);
'

Aliases​

# ~/.wp-cli/config.yml
@opshell:
  path: /home/wp_opshell_dev/sites/opshell.dev
  ssh: rezriz@GC-SG-M8

Usage: wp @opshell plugin list

Importing Docusaurus-style documentation drafts​

For a one-time migration from a Docusaurus/MDX folder, convert content to serialized Gutenberg blocks before writing post_content. Do not pass raw Markdown to wp post create or wp_insert_post: WordPress will generally output it as text, so headings, pipe tables, and fenced code appear literally. Mermaid is an exception on this site: the active Mermaid plugin recognizes fenced ```mermaid code in raw content, but preserve it as a fenced Mermaid block.

Required authoring contract​

  • The WordPress post title is the H1; body headings start at H2. Remove the duplicate source H1 after extracting its frontmatter title.
  • Convert regular prose, headings, lists, tables, blockquotes, separators, and admonitions into valid serialized Gutenberg blocks.
  • Convert regular fenced code blocks to the site's supported code block format (currently a native core/code block; Code Block Pro is active but only use its block serialization when generated with the plugin's supported builder).
  • Keep Mermaid source as <pre><code class="language-mermaid">…</code></pre> or a ```mermaid fence in raw content; the active wpstrategist-mermaid-js plugin handles these formats. Its Gutenberg Mermaid block is supported in the editor, but do not synthesize its block attributes with generic JSON serialization: WordPress may escape control characters in a way that corrupts the diagram source.
  • Keep Docusaurus admonitions in supported :::note|tip|info|warning|danger syntax only when using the plugin's raw-content conversion, or serialize them as opshell/admonition blocks. Avoid Markdown punctuation inside an admonition when the raw converter would not parse inline Markdown.
  • Use the existing topic category and scp tag; keep the Authority Topics tree separate from normal categories. Assign an explicit post author (e.g. user admin) because wp_insert_post() without post_author can leave author ID zero in a CLI import.
  • Set SEOPress metadata through post meta keys _seopress_titles_title, _seopress_titles_desc, and _seopress_analysis_target_kw.

Verify before and after writing​

  1. Inventory the source tree and retain source paths, stable IDs/slugs, titles, descriptions, taxonomy path, format, and local sidebar positions in a migration manifest.
  2. List WordPress categories, tags, Authority Topics, content formats, active plugins, and candidate users with WP-CLI. Resolve IDs by slug/path; do not assume names or numeric IDs.
  3. Back up the relevant taxonomy inventory and any ordering option before mutation. Use an idempotent importer keyed by stored source-path post meta.
  4. Create as drafts, then explicitly set category, tag, Authority Topic, content-format term, author, SEO meta, and source metadata using WordPress APIs/WP-CLI. Preserve existing assignments outside the migration scope.
  5. Verify status, author, category, tag, authority path, SEO meta, and rendered the_content/block parser output for representative examples: headings, tables, lists, code, admonitions, and Mermaid. Confirm no Markdown pipes or backtick fences are emitted literally for elements expected to be Gutenberg blocks.
  6. Keep all migrated posts as drafts for editorial and frontend review. Do not publish as part of the import.

Assigning content to the Authority Sidebar​

The WebBoulder Authority Contents Sidebars plugin is active on opshell.dev (v0.2.2). Its webboulder_authority_topic taxonomy determines the Docusaurus- style reader path; normal WordPress categories remain separate. Map the source section to a top-level domain term, modules to child topic terms, and assign each post to exactly one deepest applicable term. For SCP, the map is SCP > Introduction, SCP > Core Usage, SCP > Advanced Features, SCP > Troubleshooting, and SCP > Cheatsheet.

Post assignment alone does not persist curated ordering. For exact lesson order, set webboulder_authority_sidebar_order with complete term_<term_id> arrays of post IDs, preserving all unrelated keys. The plugin supports only published posts in its frontend sidebar, so drafts remain hidden from readers until published. Keep migrated posts as drafts until editorial review.

Opshell theme typography​

Single-post body typography is scoped under .single-post .entry-content in the canonical Opshell child theme. Use the shared --ops-type-* clamp() tokens for body text, headings, and code, rather than fixed sizes or site-wide selectors. Tables need a responsive overflow wrapper and explicit cell borders/padding so they remain legible on narrow screens. See opshell/12-design-patterns/theme-css-reference.mdx.