@whop/cli 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whop/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The Whop CLI — build and manage Whop apps from your terminal. Human and agent friendly.",
   "keywords": [
     "agent",
@@ -45,7 +45,7 @@
   "devDependencies": {
     "@types/node": "25.3.5",
     "fflate": "0.8.2",
-    "incur": "github:whopio/incur#4b9ca91dc02472db944fb103984ffc4a13251b6f",
+    "incur": "github:whopio/incur#fbe3f4dbf48f1bc780cb1bca476f7dade1fe12d3",
     "tsup": "8.5.0",
     "tsx": "4.19.4",
     "typescript": "5.9.3",

package/skills/whop-accounts/SKILL.md

@@ -5,9 +5,9 @@ requires_bin: whop
 command: whop accounts
 ---
 
-An Account represents a person or business in Whop. Each account has its own profile, wallet, and settings, so you can create one for every customer, creator, merchant, or seller your integration supports.
+An Account represents a person or business on Whop that can have its own profile, wallet, and account-scoped settings. Use accounts for customers, creators, merchants, sellers, or connected businesses your integration supports.
 
-Create an account when someone needs to hold funds, receive payments, send money, or use account-scoped API features. Save the returned `id` and `wallet` details, and use `metadata` to store your own stable identifier, like a user ID from your system.
+Use the Accounts API to create accounts, list accounts visible to your credentials, retrieve or update an account, and retrieve the account associated with the current API key.
 
 ## Commands
 
@@ -18,5 +18,7 @@ Create an account when someone needs to hold funds, receive payments, send money
 | `whop accounts me` | Retrieve Requesting Account |
 | `whop accounts get` | Retrieve Account |
 | `whop accounts update` | Update Account |
+| `whop accounts preferences` | Retrieve Account Preferences |
+| `whop accounts update-preferences` | Update Account Preferences |
 
 Run `whop accounts <command> --help` for options, or `whop accounts <command> --schema` for full argument details.

package/skills/whop-ads/SKILL.md

@@ -22,3 +22,79 @@ Use the Ads API to list ads for an account, create ads inside ad groups, retriev
 | `whop ads unpause` | Unpause an Ad |
 
 Run `whop ads <command> --help` for options, or `whop ads <command> --schema` for full argument details.
+
+## Launch playbook — from nothing to a live ad
+
+Three commands take you from nothing to a launchable ad: generate a creative, create the campaign + ad group + ad in one request, then flip the campaign to active. Structured flags (`--ad_group`, `--creatives`, `--ads_payment_methods`) take JSON strings.
+
+### One-time setup
+
+1. **Auth** — `whop login` (OAuth). First-time billing setup requires a user login; an API key can only reorder already-configured payment methods. If a command fails with a scope error saying your login predates the scope, run `whop login` again.
+2. **Facebook page** — `whop social-accounts list` must show a `"platform": "facebook"` entry. Three ways to get one:
+   - **Already connected** — use its `sacc_` id as-is.
+   - **Link a Meta Business account** — `whop social-accounts connect --platform meta_business --scopes '["advertise"]' --redirect_url <url>`, then send the user to the returned `authorize_url`.
+   - **No page at all** — have Whop create one for the account: `whop social-accounts create --platform facebook`.
+3. **Ads payment method** — check with `whop accounts preferences <account_id>` (your `biz_` ID, from `whop accounts me`). If `ads_payment_methods` is null, configure balance billing:
+
+   ```sh
+   whop accounts update-preferences <account_id> --ads_payment_methods '{"primary": {"type": "platform_balance"}}'
+   ```
+
+   Only launching needs this — drafts work without. Fund the balance with `whop deposits create --amount 50` (returns a hosted deposit page URL).
+
+### 1. Generate a creative
+
+```sh
+whop media generate --type image --prompt "A running club jogging across a bridge at sunrise, warm light" --wait
+```
+
+`--wait` blocks until the asset is terminal and returns `file.id` — use that as the creative. Billed from the balance (`amount_charged`); a failed generation auto-refunds, so adjust the prompt and retry. Video: `--type video` plus optional `--duration_seconds` (5/10/15), `--resolution` (480p–4k), and up to 4 `--reference_media` file IDs (first one seeds the opening frame).
+
+### 2. Create the whole tree as a draft — one request
+
+```sh
+whop ads create \
+  --title "Run club launch ad" \
+  --primary_texts "Join 10,000 runners chasing their next PR together." \
+  --headlines "Find your stride" \
+  --call_to_action sign_up \
+  --url "https://whop.com/your-store-page" \
+  --creatives '[{"id": "file_XXXXXXXX"}]' \
+  --social_accounts '[{"id": "sacc_XXXXXXXX"}]' \
+  --ad_group '{
+    "title": "US broad",
+    "conversion_location": "website",
+    "regions": {"include": {"countries": ["US"]}},
+    "ad_campaign": {"title": "Run club growth", "platform": "meta", "objective": "sales", "status": "draft", "budget_amount": 25, "budget_optimization": "ad_campaign"}
+  }'
+```
+
+Field rules:
+
+| Field | Rule |
+|-------|------|
+| `creatives` | One entry with no `format` is required (the base asset). `square`/`vertical`/`horizontal` are optional crops on top. |
+| `url` | Required for website ads. A whop.com store page works as-is; an external page needs the Whop pixel installed. |
+| Budget | Default to CBO: `budget_amount` on the campaign with `budget_optimization: "ad_campaign"` (the network shifts spend to the best ad group). Per-ad-group `budget_amount` (ABO) is the manual alternative. One level owns it — never both. |
+| Targeting | Omit `demographics`/`placements`/`devices` for automatic optimization. `regions` uses ISO 3166 (`"US"`, `"US-CA"`). |
+| `lead_form` | Only with an instant-form `conversion_location`. |
+
+Reuse existing containers by passing `--ad_group_id adgrp_x` instead of `--ad_group`, or `"ad_campaign_id": "adcamp_x"` inside `--ad_group` instead of the inline `ad_campaign`.
+
+### 3. Launch
+
+`"status": "draft"` above kept money out of it. Review, then launch — this is when spend starts and the payment method is enforced:
+
+```sh
+whop ad-campaigns update adcamp_XXXXXXXX --status active
+```
+
+(Ready to spend immediately? Omit `"status": "draft"` and the one-shot create launches directly.)
+
+### 4. Monitor
+
+```sh
+whop ads get ad_XXXXXXXX
+```
+
+`delivery_status` is the live state (a brief `in_review` for moderation is normal); `issues[]` carries a human-readable `message` for anything the network rejected asynchronously. Control delivery with `pause`/`unpause` on ads, ad groups, or campaigns. Edit copy or creatives with `whop ads update` — sending `creatives` replaces the whole set, so include the base entry.

package/skills/whop-apps/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: whop-apps
+description: "Apps you build on Whop: metadata, hosted builds, runtime logs. Run `whop apps --help` for usage details."
+requires_bin: whop
+command: whop apps
+---
+
+An App is software you build on the Whop platform — from a fully-hosted web app served at `<route>.whop.app` to an API integration installed into whops as experiences. Apps belong to an account and hold their own credentials and settings.
+
+Use the Apps API to create and configure apps, and — for hosted apps — read their server runtime logs: every console line, uncaught exception, and failed request is captured for 7 days and queryable by build, level, time window, and message text.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `whop apps logs` | List App Logs |
+
+Run `whop apps <command> --help` for options, or `whop apps <command> --schema` for full argument details.

package/skills/whop-events/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: whop-events
+description: Conversion and engagement events tracked for attribution. Run `whop events --help` for usage details.
+requires_bin: whop
+command: whop events
+---
+
+An Event records conversion or engagement activity for an account, such as page views, purchases, or leads. Each event ties the action to the [person](https://docs.whop.com/api-reference/beta/people/person) who took it, so activity can be attributed to the ads and links that drove it.
+
+Use the Events API to send new tracking events and list the events recorded for a person.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `whop events list` | List Events |
+| `whop events create` | Create Event |
+
+Run `whop events <command> --help` for options, or `whop events <command> --schema` for full argument details.

package/skills/whop-media/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: whop-media
+description: AI-generated assets, billed from a balance, attachable wherever files are accepted. Run `whop media --help` for usage details.
+requires_bin: whop
+command: whop media
+---
+
+A Media Asset is an AI-generated image or video created from a prompt and billed from an account balance. When generation finishes, the asset includes a file that can be attached anywhere Whop accepts files.
+
+Use the Media API to start a generation job and retrieve the asset while it processes or after it is ready.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `whop media generate` | Generate Media Asset |
+| `whop media get` | Retrieve Media Asset |
+
+Run `whop media <command> --help` for options, or `whop media <command> --schema` for full argument details.
+
+## Steps that finish in the browser
+
+Some commands respond with a URL the user must open in a browser to finish the flow (`authorize_url`, `session_url`, `deposit_url`) — the CLI cannot complete that step itself. When a response contains one of these fields, or the CLI prints "Action required: open this link in the user's browser", open that link in the user's browser for them, tell them what to complete there, then re-run the matching `get`/`list` command to confirm the step finished.

package/skills/whop-payouts/SKILL.md

@@ -14,6 +14,7 @@ Use the Payouts API to list payout history, monitor payout statuses, and show ex
 | Command | Description |
 |---------|-------------|
 | `whop payouts list` | List Payouts |
+| `whop payouts create` | Create Payout |
 | `whop payouts methods` | List Payout Methods |
 
 Run `whop payouts <command> --help` for options, or `whop payouts <command> --schema` for full argument details.

package/skills/whop-people/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: whop-people
+description: Visitors and customers of an account, aggregated from pixel events. Run `whop people --help` for usage details.
+requires_bin: whop
+command: whop people
+---
+
+A Person represents a visitor or customer of an account, assembled from [pixel events](https://docs.whop.com/api-reference/beta/events/event) and purchase activity — ad clicks, storefront visits, and checkouts.
+
+Use the People API to list the people of an account and retrieve a single person.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `whop people list` | List People |
+| `whop people get` | Retrieve Person |
+
+Run `whop people <command> --help` for options, or `whop people <command> --schema` for full argument details.

package/skills/whop-referrals/SKILL.md

@@ -5,7 +5,7 @@ requires_bin: whop
 command: whop referrals
 ---
 
-Referrals track businesses referred to Whop and the earnings generated from their processing volume. They help you see much volume your referred businesses have processed and how much you've earned from them.
+Referrals track businesses referred to Whop and the earnings generated from their processing volume. They help you see how much volume your referred businesses have processed and how much you've earned from them.
 
 Use the Referrals API to list referred businesses, retrieve one referral, and review earnings across all referrals or for a single referred business.
 

package/skills/whop-social-accounts/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: whop-social-accounts
+description: Connected Facebook and Instagram accounts that run ads. Run `whop social-accounts --help` for usage details.
+requires_bin: whop
+command: whop social-accounts
+---
+
+A Social Account represents an external profile connected to a Whop account or user, such as a Facebook page or Instagram account. Connecting a social account lets Whop run [ads](https://docs.whop.com/api-reference/beta/ads/ad) under that profile's identity and promote its existing posts.
+
+Use the Social Accounts API to list connected accounts, create a Whop-managed Facebook page, start an OAuth connection, disconnect a social account, and list a connected profile's posts.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `whop social-accounts list` | List Social Accounts |
+| `whop social-accounts create` | Create a Social Account |
+| `whop social-accounts connect` | Connect a Social Account |
+| `whop social-accounts delete` | Delete a Social Account |
+| `whop social-accounts posts` | List Social Account Posts |
+
+Run `whop social-accounts <command> --help` for options, or `whop social-accounts <command> --schema` for full argument details.
+
+## Steps that finish in the browser
+
+Some commands respond with a URL the user must open in a browser to finish the flow (`authorize_url`, `session_url`, `deposit_url`) — the CLI cannot complete that step itself. When a response contains one of these fields, or the CLI prints "Action required: open this link in the user's browser", open that link in the user's browser for them, tell them what to complete there, then re-run the matching `get`/`list` command to confirm the step finished.

package/skills/whop-verifications/SKILL.md

@@ -19,3 +19,7 @@ Use the Verifications API to start or resume a hosted verification session, chec
 | `whop verifications update` | Update Verification |
 
 Run `whop verifications <command> --help` for options, or `whop verifications <command> --schema` for full argument details.
+
+## Steps that finish in the browser
+
+Some commands respond with a URL the user must open in a browser to finish the flow (`authorize_url`, `session_url`, `deposit_url`) — the CLI cannot complete that step itself. When a response contains one of these fields, or the CLI prints "Action required: open this link in the user's browser", open that link in the user's browser for them, tell them what to complete there, then re-run the matching `get`/`list` command to confirm the step finished.