v1.0.0

docs/WP-CLI.md

@@ -0,0 +1,103 @@
+# WP-CLI Command Reference
+
+The plugin registers WP-CLI commands under the `og-fallback` namespace.
+
+## Commands
+
+### `wp og-fallback resolve`
+
+Resolves (or re-resolves) the OG fallback image for one or all posts with featured images.
+
+**Usage:**
+
+```bash
+wp og-fallback resolve [<post_id>] [--all] [--dry-run] [--post-type=<type>]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<post_id>` | (optional) Single post ID to resolve. |
+| `--all` | Process all posts that have a featured image. |
+| `--dry-run` | Preview without making any changes. |
+| `--post-type=<type>` | Limit `--all` to a specific post type (default: `any`). |
+
+**Examples:**
+
+```bash
+# Resolve fallback for a single post
+wp og-fallback resolve 123
+
+# Preview for a single post without saving
+wp og-fallback resolve 123 --dry-run
+
+# Re-resolve all posts (clears cache first)
+wp og-fallback resolve --all
+
+# Re-resolve only 'product' post type posts
+wp og-fallback resolve --all --post-type=product
+
+# Dry-run all (shows count, no changes)
+wp og-fallback resolve --all --dry-run
+```
+
+**Output examples:**
+
+```
+Success: Post 123 resolved to https://example.com/uploads/image.jpg
+Warning: Post 456: no compatible image found.
+Success: Resolved 47 posts. Failed: 2.
+Found 49 posts with featured images. (dry-run, no changes made)
+```
+
+---
+
+### `wp og-fallback clear-cache`
+
+Deletes cached fallback URLs from postmeta.
+
+**Usage:**
+
+```bash
+wp og-fallback clear-cache [<post_id>] [--all] [--dry-run]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<post_id>` | (optional) Single post ID to clear cache for. |
+| `--all` | Clear all cached fallback URLs. |
+| `--dry-run` | Preview without making any changes. |
+
+**Examples:**
+
+```bash
+# Clear cache for a single post
+wp og-fallback clear-cache 123
+
+# Clear all cached fallback URLs
+wp og-fallback clear-cache --all
+
+# Preview how many entries would be cleared
+wp og-fallback clear-cache --all --dry-run
+```
+
+**Output examples:**
+
+```
+Success: Cleared cached fallback URL for post 123.
+Warning: Post 456 has no cached fallback URL.
+Success: Cleared 47 cached fallback URLs.
+Found 47 cached fallback URLs. (dry-run, no changes made)
+```
+
+---
+
+## Notes
+
+- Both commands require WP-CLI 2.x.
+- No capability check is enforced at the CLI level (WP-CLI access implies server-level trust).
+- The `--all` flag with `resolve` is equivalent to clicking **Re-resolve All Images** in the admin Tools tab.
+- The `--all` flag with `clear-cache` is equivalent to clicking **Clear All Cached URLs** in the admin Tools tab.