# IAS S3 Storage — CLI Reference - **Plugin slug:** `ias-s3-storage` - **Version:** 1.1.16 - **CLI namespace:** `wp ias s3-storage` - **Tier:** Commercial (licence required) - **Summary:** S3-backed downloads: verify, inspect, regenerate links, offload, migrate back and purge orphans. This reference is generated from the WP-CLI command docblocks (do not edit by hand). Every command accepts `--format=`. Every mutating command supports `--dry-run` (resolve + audit, no writes) and `--yes` (skip the confirmation prompt); destructive commands additionally prompt unless `--yes` is given, and any bulk-delete command refuses to run without an explicit scope argument — a required `--filter` on the record-deletion commands, or another mandatory bound such as `--max-age-days` — rather than defaulting to delete-all. **Authentication / trust model:** these commands run under WP-CLI, whose trust boundary is shell access — there is no separate capability check. Irreversible commands (flagged below) are guarded by `--dry-run`, a confirmation prompt (or `--yes`), a required scope argument on any bulk delete (a `--filter`, or another mandatory bound such as `--max-age-days`), and a before-state entry in the suite-wide CLI audit log. ## Commands ### `wp ias s3-storage audit-log` Read the plugin's admin audit log (settings, licence and upload events). Reads back the entries the plugin records to its non-autoloaded `ias_s3_audit_log` option — the plugin-level admin action log (distinct from the suite-wide CLI audit log). Each entry carries a timestamp, the acting user, the action name, the client IP and an action-specific details blob. Newest first; filter to a single action with --action, page with --page/--per-page. **Synopsis:** `wp ias s3-storage audit-log [--action=] [--page=] [--per-page=] [--format=]` **Options:** - `[--action=]` — Only entries for this action (e.g. settings_changed, license_activated, license_deactivated, file_uploaded, connection_tested, cache_cleared). - `[--page=]` — Page of results (1-based). - `[--per-page=]` — Results per page (capped at 1000). - `[--format=]` — Output format. **Examples:** ```bash wp ias s3-storage audit-log --format=json wp ias s3-storage audit-log --action=file_uploaded --per-page=100 ``` **Related:** `wp ias s3-storage download-logs`, `wp ias s3-storage inspect`, `wp ias s3-storage inspect-bucket`, `wp ias s3-storage list-products`, `wp ias s3-storage migrate-from-s3`, `wp ias s3-storage offload`, `wp ias s3-storage purge-orphans`, `wp ias s3-storage regenerate-link` --- ### `wp ias s3-storage download-logs` Read recent S3 download-delivery log lines (WooCommerce file logs). The plugin writes download events to the WooCommerce logger (source `ias-s3-storage`) when logging is enabled. This best-effort reader parses those log files; with logging off or no log files present it returns empty. **Synopsis:** `wp ias s3-storage download-logs [--since=] [--customer=] [--page=] [--per-page=] [--format=]` **Options:** - `[--since=]` — Only lines on/after this date (anything strtotime understands). - `[--customer=]` — Substring-match log lines for this customer reference (email fragment). - `[--page=]` — Page of results (1-based). - `[--per-page=]` — Results per page (capped at 1000). - `[--format=]` — Output format. **Examples:** ```bash wp ias s3-storage download-logs --since="-7 days" --format=json ``` **Related:** `wp ias s3-storage audit-log`, `wp ias s3-storage inspect`, `wp ias s3-storage inspect-bucket`, `wp ias s3-storage list-products`, `wp ias s3-storage migrate-from-s3`, `wp ias s3-storage offload`, `wp ias s3-storage purge-orphans`, `wp ias s3-storage regenerate-link` --- ### `wp ias s3-storage inspect` Report the plugin slug, version and CLI environment. **Synopsis:** `wp ias s3-storage inspect [--format=]` **Options:** - `[--format=]` — Output format. **Examples:** ```bash wp ias s3-storage inspect ``` **Related:** `wp ias s3-storage audit-log`, `wp ias s3-storage download-logs`, `wp ias s3-storage inspect-bucket`, `wp ias s3-storage list-products`, `wp ias s3-storage migrate-from-s3`, `wp ias s3-storage offload`, `wp ias s3-storage purge-orphans`, `wp ias s3-storage regenerate-link` --- ### `wp ias s3-storage inspect-bucket` Inspect a bucket: region plus a sample of its objects. **Synopsis:** `wp ias s3-storage inspect-bucket [--prefix=] [--max=] [--format=]` **Options:** - `` — Bucket name. - `[--prefix=]` — Restrict the object sample to this key prefix. - `[--max=]` — Maximum sample objects to list (capped at 1000). - `[--format=]` — Output format. **Examples:** ```bash wp ias s3-storage inspect-bucket my-bucket --prefix=downloads/ ``` **Related:** `wp ias s3-storage audit-log`, `wp ias s3-storage download-logs`, `wp ias s3-storage inspect`, `wp ias s3-storage list-products`, `wp ias s3-storage migrate-from-s3`, `wp ias s3-storage offload`, `wp ias s3-storage purge-orphans`, `wp ias s3-storage regenerate-link` --- ### `wp ias s3-storage list-products` List products that have S3-backed downloadable files. **Synopsis:** `wp ias s3-storage list-products [--format=]` **Options:** - `[--format=]` — Output format. **Examples:** ```bash wp ias s3-storage list-products --format=json ``` **Related:** `wp ias s3-storage audit-log`, `wp ias s3-storage download-logs`, `wp ias s3-storage inspect`, `wp ias s3-storage inspect-bucket`, `wp ias s3-storage migrate-from-s3`, `wp ias s3-storage offload`, `wp ias s3-storage purge-orphans`, `wp ias s3-storage regenerate-link` --- ### `wp ias s3-storage migrate-from-s3` Pull a product's S3-backed download back to local storage (reverse offload). Finds the product's first S3-backed download, downloads the object into the site's woocommerce_uploads directory, and repoints the product download at the local copy. The S3 object is NOT deleted — it remains in the bucket, but is no longer the source of truth, so the file is duplicated (local + S3). Use `purge-orphans` afterwards if you want to reclaim the now-unmapped object. **Synopsis:** `wp ias s3-storage migrate-from-s3 [--bucket=] [--dry-run] [--yes] [--format=]` **Options:** - `` — Product reference — numeric ID or SKU. - `[--bucket=]` — Override the source bucket (defaults to the shortcode/option bucket). - `[--dry-run]` — Report the object key, source bucket and planned local path without contacting S3. - `[--yes]` — Skip the confirmation prompt. - `[--format=]` — Output format. **Returns:** The product ID, object key and the local path the download now points at. **Examples:** ```bash wp ias s3-storage migrate-from-s3 42 --dry-run wp ias s3-storage migrate-from-s3 42 --yes ``` **Related:** `wp ias s3-storage audit-log`, `wp ias s3-storage download-logs`, `wp ias s3-storage inspect`, `wp ias s3-storage inspect-bucket`, `wp ias s3-storage list-products`, `wp ias s3-storage offload`, `wp ias s3-storage purge-orphans`, `wp ias s3-storage regenerate-link` --- ### `wp ias s3-storage offload` Offload a single product's local download file to S3 (manual trigger). Drives the same primitives the auto-offload flow uses: uploads the local file via S3_Handler::upload_file(), then rewrites the product download to an S3 shortcode via Shortcode::generate_shortcode(). Idempotent — a download that is already an S3 shortcode is reported as already_applied. **Synopsis:** `wp ias s3-storage offload [--source=] [--dry-run] [--yes] [--format=]` **Options:** - `` — Product reference — numeric ID or SKU. - `[--source=]` — Explicit local file to upload (defaults to the first local download file on the product). - `[--dry-run]` — Resolve the source and target and report what would be uploaded. - `[--yes]` — Skip the confirmation prompt. - `[--format=]` — Output format. **Examples:** ```bash wp ias s3-storage offload 42 wp ias s3-storage offload 42 --source=/var/www/uploads/big.zip --dry-run ``` **Related:** `wp ias s3-storage audit-log`, `wp ias s3-storage download-logs`, `wp ias s3-storage inspect`, `wp ias s3-storage inspect-bucket`, `wp ias s3-storage list-products`, `wp ias s3-storage migrate-from-s3`, `wp ias s3-storage purge-orphans`, `wp ias s3-storage regenerate-link` --- ### `wp ias s3-storage purge-orphans` > **⚠ Irreversible — `--dry-run` first.** This command permanently destroys data or applies a terminal state that cannot be undone from the CLI. Preview the exact effect with `--dry-run`, then re-run with `--yes` once you are certain. Permanently delete S3 objects that no product maps to and that are old enough. An orphan is a bucket object whose key is referenced by NO product download shortcode AND whose LastModified is older than --max-age-days. This is a foot-gun: a mis-set age or a partial product import can sweep live files. For that reason the real (non-dry-run) path REFUSES to run unless BOTH --max-age-days (explicit) and --yes are supplied. Always preview with --dry-run first. **Synopsis:** `wp ias s3-storage purge-orphans [--filter=] [--max-age-days=] [--bucket=] [--dry-run] [--yes] [--format=]` **Options:** - `[--filter=]` — Reserved JSON filter blob, recorded in the audit context for traceability. - `[--max-age-days=]` — Only objects older than this many days are eligible. REQUIRED on the real path; defaults to 30 for the dry-run preview only. - `[--bucket=]` — Bucket to scan (defaults to the configured ias_s3_default_bucket). - `[--dry-run]` — List the orphans that would be deleted without contacting S3 for deletes. - `[--yes]` — Skip the confirmation prompt. - `[--format=]` — Output format. **Returns:** The bucket, age threshold, number of objects scanned (and whether the scan hit the per-run cap), orphan count and — on the real path — every deleted key, the deleted count and the total bytes reclaimed. **Examples:** ```bash wp ias s3-storage purge-orphans --max-age-days=90 --dry-run wp ias s3-storage purge-orphans --max-age-days=90 --yes ``` **Related:** `wp ias s3-storage audit-log`, `wp ias s3-storage download-logs`, `wp ias s3-storage inspect`, `wp ias s3-storage inspect-bucket`, `wp ias s3-storage list-products`, `wp ias s3-storage migrate-from-s3`, `wp ias s3-storage offload`, `wp ias s3-storage regenerate-link` --- ### `wp ias s3-storage regenerate-link` Regenerate a fresh presigned download URL for an order item (support tool). Resolves the order item to its product, reads the product's S3-backed downloads, and presigns a fresh URL for each via S3_Handler::generate_presigned_url() — the same presign the Download_Handler serves to customers. Nothing is stored; this only mints time-limited URLs. **Synopsis:** `wp ias s3-storage regenerate-link [--dry-run] [--yes] [--format=]` **Options:** - `` — The WooCommerce order line-item ID. - `[--dry-run]` — Report which files would be presigned without contacting S3. - `[--yes]` — Skip the confirmation prompt. - `[--format=]` — Output format. **Examples:** ```bash wp ias s3-storage regenerate-link 1234 ``` **Related:** `wp ias s3-storage audit-log`, `wp ias s3-storage download-logs`, `wp ias s3-storage inspect`, `wp ias s3-storage inspect-bucket`, `wp ias s3-storage list-products`, `wp ias s3-storage migrate-from-s3`, `wp ias s3-storage offload`, `wp ias s3-storage purge-orphans` --- ### `wp ias s3-storage show` Show the S3 file mapping and presign config for a product. **Synopsis:** `wp ias s3-storage show [--format=]` **Options:** - `` — Product reference — numeric ID or SKU. - `[--format=]` — Output format. **Examples:** ```bash wp ias s3-storage show 42 --format=json ``` **Related:** `wp ias s3-storage audit-log`, `wp ias s3-storage download-logs`, `wp ias s3-storage inspect`, `wp ias s3-storage inspect-bucket`, `wp ias s3-storage list-products`, `wp ias s3-storage migrate-from-s3`, `wp ias s3-storage offload`, `wp ias s3-storage purge-orphans` --- ### `wp ias s3-storage verify-credentials` Test connectivity with the current S3 credentials. **Synopsis:** `wp ias s3-storage verify-credentials [--format=]` **Options:** - `[--format=]` — Output format. **Examples:** ```bash wp ias s3-storage verify-credentials ``` **Related:** `wp ias s3-storage audit-log`, `wp ias s3-storage download-logs`, `wp ias s3-storage inspect`, `wp ias s3-storage inspect-bucket`, `wp ias s3-storage list-products`, `wp ias s3-storage migrate-from-s3`, `wp ias s3-storage offload`, `wp ias s3-storage purge-orphans` ---