# StoreAgent CLI Commands

## Prerequisites

StoreAgent CLI commands run via [WP-CLI](https://wp-cli.org/). On LocalWP sites, you must source the SSH entry script and `cd` to the WordPress install path before running `wp` commands.

### acfw.local (client plugin)

```bash
cd "<local-sites-path>/acfw/app/public" && \
  source <(grep -E '^export ' "<local-ssh-entry-path>/<acfw-entry-id>.sh") && \
  wp storeagent <command> --url=acfw.local
```

### saworker.local (server plugins)

```bash
cd "<local-sites-path>/saworker/app/public" && \
  source <(grep -E '^export ' "<local-ssh-entry-path>/<saworker-entry-id>.sh") && \
  wp <command> --url=saworker.local
```

> **Note:** Replace `<local-sites-path>` with your LocalWP sites directory (e.g., `~/Local Sites`) and `<local-ssh-entry-path>` with `~/Library/Application Support/Local/ssh-entry`. The SSH entry script IDs may change if sites are recreated — find yours by grepping for the site path in the `ssh-entry` directory.

---

## Commands

### `wp storeagent <agent-name> <product-id>...`

Run an AI agent in bulk against one or more products. Uses the `Bulk_Run_Agent` class, which processes products sequentially with a progress bar.

Only agents that implement `Bulk_Run_Agent_Interface` can be run this way:

| Agent Name | Description |
|---|---|
| `product-description` | Generate AI product descriptions |
| `product-tags-generator` | Generate product tags from product data |
| `product-summaries` | Generate short product summaries |
| `review-summaries` | Generate review summaries (requires 3+ reviews) |
| `product-upsells` | Generate upsell/cross-sell recommendations |

**Examples:**

```bash
# Generate description for a single product
wp storeagent product-description 123

# Generate tags for multiple products
wp storeagent product-tags-generator 123 456 789

# Show help for a specific agent
wp storeagent product-description help
```

---

### `wp storeagent test-agents`

Test AI agent workflows end-to-end. Calls each agent against real WooCommerce objects and reports pass/fail with timing.

**Usage:**

```
wp storeagent test-agents [<agent>] [--product-id=<id>] [--coupon-id=<id>]
    [--comment-id=<id>] [--attachment-id=<id>] [--category-id=<id>]
    [--dry-run] [--skip-save]
```

**Options:**

| Option | Description |
|---|---|
| `<agent>` | Optional. Run only this agent (e.g., `coupon-description`). |
| `--product-id=<id>` | Use this product instead of auto-discovering one. |
| `--coupon-id=<id>` | Use this coupon instead of auto-discovering one. |
| `--comment-id=<id>` | Use this review comment instead of auto-discovering one. |
| `--attachment-id=<id>` | Use this image attachment instead of auto-discovering one. |
| `--category-id=<id>` | Use this product category instead of auto-discovering one. |
| `--dry-run` | Only discover and display test objects, don't call AI. |
| `--skip-save` | Call AI but don't save results to the database. |

**Auto-discovery:** When IDs are not provided, the command automatically finds the first available object of each type from the database (first published product, first coupon, first approved review, first image, first product category).

**Testable agents:**

| Agent | Object Type | Notes |
|---|---|---|
| `product-description` | Product | |
| `product-tags-generator` | Product | |
| `product-summaries` | Product | |
| `review-summaries` | Product | Needs product with 3+ reviews |
| `product-upsells` | Product | |
| `vendors-product-moderator` | Product | Skipped if WC Vendors not active |
| `image-alt-tags` | Attachment | |
| `coupon-description` | Coupon | |
| `review-moderation` | Comment | Needs an approved review |
| `category-description` | Category | |

**Examples:**

```bash
# Dry run - just show what objects would be used
wp storeagent test-agents --dry-run

# Test all agents without saving results
wp storeagent test-agents --skip-save

# Test a single agent with a specific coupon
wp storeagent test-agents coupon-description --skip-save --coupon-id=1087

# Test product agents with a specific product
wp storeagent test-agents --skip-save --product-id=123
```

**Sample output:**

```
=== StoreAgent AI Agent Test Suite ===

Test objects:
  Product   : #1098 - Medium product
  Coupon    : #1087 - coupon-force-apply-enabled
  Review    : #376 - I bought these Killshot 2 sneakers...
  Image     : #835 - Nike Gray Hoodie Ensemble
  Category  : #17 - Clothing Accessories

Testing product-description...
  * product-description            - 3.0s (OK)
Testing coupon-description...
  * coupon-description             - 12.6s (OK)
Testing review-moderation...
  x review-moderation              - 14.6s (AI response was not valid JSON)

--------------------------------------------------
Summary: 2/3 passed, 1 failed
```

---

### `wp storeagent reset-data`

Reset all StoreAgent plugin data to its initial state. Useful for testing the onboarding wizard and first-time experiences.

**Usage:**

```
wp storeagent reset-data [--yes] [--include-notifications]
```

**Options:**

| Option | Description |
|---|---|
| `--yes` | Skip the confirmation prompt. |
| `--include-notifications` | Also clear all records from the notifications database table. |

**What gets deleted:**

- Onboarding wizard status
- Chat widget and post types settings
- All AI agent settings (product-description, product-tags, etc.)
- Notification retention settings
- Tool execution time records
- Rate limiting transients
- Product summary post meta
- AI memory flag post meta
- All other `saai_*` options

**Examples:**

```bash
# Interactive - will ask for confirmation
wp storeagent reset-data

# Skip confirmation
wp storeagent reset-data --yes

# Reset everything including notifications
wp storeagent reset-data --yes --include-notifications
```

---

### `wp storeagent upload-data`

Upload post data (products, posts, pages, etc.) to AI memory for use by the StoreAgent chat assistant. Processes posts in batches with progress reporting.

**Usage:**

```
wp storeagent upload-data [--post-type=<post_type>]
```

**Options:**

| Option | Description |
|---|---|
| `--post-type=<post_type>` | Upload only this post type. Must be enabled for AI memory in settings. If omitted, uploads all enabled post types. |

**Examples:**

```bash
# Upload all enabled post types
wp storeagent upload-data

# Upload products only
wp storeagent upload-data --post-type=product
```

---

### `wp storeagent help`

Display the WP-CLI help page for the `storeagent` command.

```bash
wp storeagent help
```
