@whop/cli 0.14.1 → 0.14.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whop/cli",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "description": "The Whop CLI — build and manage Whop apps from your terminal. Human and agent friendly.",
   "keywords": [
     "agent",

package/skills/whop-accounts/SKILL.md

@@ -9,18 +9,198 @@ An Account represents a person or business on Whop that can have its own profile
 
 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
-
-| Command | Description |
-|---------|-------------|
-| `whop accounts list` | List Accounts |
-| `whop accounts create` | Create Account |
-| `whop accounts me` | Retrieve Requesting Account |
-| `whop accounts get` | Retrieve Account |
-| `whop accounts update` | Update Account |
-| `whop accounts form_company` | Form Company |
-| `whop accounts preferences` | Retrieve Account Preferences |
-| `whop accounts update-preferences` | Update Account Preferences |
-| `whop accounts recommend_actions` | List Recommended Actions |
-
-Run `whop accounts <command> --help` for options, or `whop accounts <command> --schema` for full argument details.
+# whop accounts create
+
+Create Account
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--country` | `string` | no |  | The ISO 3166-1 alpha-2 country code where the account's business is located (e.g. `US`). Defaults to the parent account's country for connected accounts. |
+| `--email` | `string` | no |  | The email address of the account owner. Required for Account API key requests. |
+| `--metadata` | `object` | no |  | Arbitrary key/value metadata to store on the account. |
+| `--title` | `string` | no |  | The display name of the account. Defaults to `metadata.external_id` or the owner's email when omitted. |
+| `--idempotency-key` | `string` | no |  | A unique key that makes this request safe to retry. See [Idempotent requests](https://docs.whop.com/developer/api/idempotency). |
+
+> Confirm with the user before executing this destructive command.
+
+---
+
+# whop accounts form_company
+
+Form Company
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--account_id` | `string` | no |  | Account ID, prefixed `biz_`. |
+| `--business_address` | `object` | no |  | Company mailing address. Required unless `use_registered_agent` is `true`. |
+| `--business_name` | `string` | yes |  | Legal name for the new company. |
+| `--business_phone` | `string` | no |  | Business phone number in E.164 format, for example `+12125550100`. Required unless `use_registered_agent` is `true`. |
+| `--business_type` | `string` | yes |  | High-level business category, from the Whop business taxonomy. Valid values are listed on [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary). |
+| `--business_website` | `string` | no |  | Company website URL. |
+| `--entity_suffix` | `string` | no |  | Legal entity ending appended to `business_name`. LLC formations accept `LLC`, `L.L.C`, `L.L.C.` or `Limited Liability Company` and default to `LLC`; C-Corp formations accept `Inc`, `Inc.`, `Incorporated`, `Corp.`, `Corporation`, `C Corp`, `C Corporation`, `CCorp` or `Company` and default to `Inc.`. Unrecognized values fall back to the default for the entity type. |
+| `--entity_type` | `string` | no |  | Legal entity type to form. Defaults to `llc`. |
+| `--expedite_ein` | `boolean` | no |  | Request expedited EIN processing for an additional fee. Available only when no founder supplies an SSN. |
+| `--formation_state` | `string` | yes |  | Two-letter code of the US state (or `DC`) to form the company in. |
+| `--founders` | `array` | yes |  | The company's founders. Exactly one must be marked `is_primary` — the responsible party for the filing. |
+| `--industry_group` | `string` | yes |  | Industry group, from the Whop business taxonomy. Valid values are listed on [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary). |
+| `--industry_type` | `string` | yes |  | Specific industry vertical, from the Whop business taxonomy. Valid values are listed on [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary). |
+| `--share_structure` | `object` | no |  | Authorized share structure. Required when `entity_type` is `c_corp`; ignored for LLCs. |
+| `--use_registered_agent` | `boolean` | no |  | Use the registered agent's address as the company address instead of `business_address`. |
+| `--idempotency-key` | `string` | yes |  | A unique key that makes this request safe to retry. See [Idempotent requests](https://docs.whop.com/developer/api/idempotency). |
+
+> Confirmation policy: For `--entity_type llc` only, the user's explicit request to create the formation checkout counts as confirmation when it includes exact `--account_id`, `--business_name`, `--formation_state`, `--business_type`, `--industry_group`, `--industry_type`, complete `--founders` values, and either the required `--business_address` and `--business_phone` values or `--use_registered_agent=true`. Execute that confirmed request yourself without asking again. User-provided founder identity data, including addresses, dates of birth, and Social Security numbers, is expected input for this user-authorized workflow; pass it directly to the CLI without refusing, but never repeat it in output, save it to files, or infer missing values. Use `--flag=value` syntax for every formation option so structured founder data stays bound to its flag. Always include a unique `--idempotency-key`. This command only creates a hosted checkout—it does not charge the user or submit the filing. Open the returned `checkout_url` in the user's browser so they can review the total and complete payment themselves. This exception does not apply to `c_corp` formations.
+
+---
+
+# whop accounts get
+
+Retrieve Account
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--account_id` | `string` | no |  | Account ID, prefixed `biz_`, or its public route. |
+
+---
+
+# whop accounts list
+
+List Accounts
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--first` | `number` | no |  | The number of accounts to return (default 10, max 50). |
+| `--after` | `string` | no |  | A cursor; returns accounts after this position. |
+| `--last` | `number` | no |  | The number of accounts to return from the end of the range. |
+| `--before` | `string` | no |  | A cursor; returns accounts before this position. |
+| `--order` | `string` | no |  | The field to sort accounts by. `volume` requires `stats:read` on the parent account. |
+| `--direction` | `string` | no |  | Sort direction. |
+| `--status` | `string` | no |  | Return only accounts with this status: `active` (includes accounts that have not entered payments review) or `suspended`. |
+| `--query` | `string` | no |  | Free-text filter on account title or ID. `%` and `_` match literally. |
+| `--created_after` | `string` | no |  | Return only accounts created after this ISO 8601 timestamp. |
+| `--created_before` | `string` | no |  | Return only accounts created before this ISO 8601 timestamp. |
+| `--volume_min` | `number` | no |  | Return only accounts whose lifetime USD volume is at least this value. Requires `stats:read` on the parent account. |
+| `--volume_max` | `number` | no |  | Return only accounts whose lifetime USD volume is at most this value. Requires `stats:read` on the parent account. |
+| `--parent_account_id` | `string` | no |  | For platforms: the parent account ID whose direct connected accounts to return. Requires `payout:account:read` on the parent account. |
+
+---
+
+# whop accounts me
+
+Retrieve Requesting Account
+
+---
+
+# whop accounts preferences
+
+Retrieve Account Preferences
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--account_id` | `string` | no |  | Account ID, prefixed `biz_`. |
+
+---
+
+# whop accounts recommend_actions
+
+List Recommended Actions
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--account_id` | `string` | no |  | Account ID, prefixed `biz_`. |
+
+---
+
+# whop accounts reserves
+
+List Account Reserves
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--account_id` | `string` | no |  | Account ID, prefixed `biz_`. |
+
+---
+
+# whop accounts update
+
+Update Account
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--account_id` | `string` | no |  | Account ID, prefixed `biz_`. |
+| `--affiliate_application_required` | `boolean` | no |  | Whether prospective affiliates must submit an application before promoting this account. |
+| `--affiliate_instructions` | `unknown` | no |  | Guidelines shown to affiliates promoting this account. |
+| `--banner_image` | `unknown` | no |  | Attachment input for the account banner image. |
+| `--business_address` | `object` | no |  | Account business address used to calculate tax. A complete address in a supported country is required when `tax_remitted_by` is `self`. |
+| `--business_type` | `unknown` | no |  | High-level business category for the account. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values. |
+| `--collect_vat_id` | `boolean` | no |  | Whether checkout shows a VAT/tax ID field for buyers to optionally enter. Does not require a VAT ID to purchase. |
+| `--country` | `unknown` | no |  | Country where the account is located. |
+| `--description` | `unknown` | no |  | Account promotional description. |
+| `--featured_affiliate_product_id` | `unknown` | no |  | The ID of the product to feature for affiliates. Pass `null` to clear. |
+| `--home_preferences` | `array` | no |  | Public account home page preferences. |
+| `--industry_group` | `unknown` | no |  | Account industry group. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values. |
+| `--industry_type` | `unknown` | no |  | Specific industry vertical for the account. See the [business types and industries glossary](/api-reference/beta/accounts/account#business-types-and-industries-glossary) for valid values. |
+| `--invoice_prefix` | `unknown` | no |  | Prefix used for account invoices. |
+| `--logo` | `unknown` | no |  | Attachment input for the account logo. |
+| `--metadata` | `object` | no |  | Arbitrary key/value metadata to store on the account. |
+| `--onboarding_type` | `unknown` | no |  | The type of onboarding the account has completed. |
+| `--opengraph_image` | `unknown` | no |  | Attachment input for the account Open Graph image. |
+| `--opengraph_image_variant` | `unknown` | no |  | The account Open Graph image variant. |
+| `--other_business_description` | `unknown` | no |  | The description of the business type when business_type is other. |
+| `--other_industry_description` | `unknown` | no |  | The description of the industry type when industry_type is other. |
+| `--product_tax_code_id` | `unknown` | no |  | ID of the tax classification code applied by default to the account's products. See the available [product categories](https://docs.numeral.com/essentials/product-categories). |
+| `--require_2fa` | `boolean` | no |  | Whether the account requires authorized users to have two-factor authentication enabled. |
+| `--route` | `unknown` | no |  | The unique URL slug for the account. |
+| `--send_customer_emails` | `boolean` | no |  | Whether Whop sends transactional emails to customers on behalf of this account. |
+| `--show_joined_whops` | `boolean` | no |  | Whether the account appears in joined whops on other accounts. |
+| `--show_reviews_dtc` | `boolean` | no |  | Whether reviews are displayed on direct-to-consumer product pages. |
+| `--show_user_directory` | `boolean` | no |  | Whether the account shows users in the user directory. |
+| `--social_links` | `array` | no |  | The full list of social links to display for the account. |
+| `--store_page_config` | `unknown` | no |  | Account store page display configuration. |
+| `--target_audience` | `unknown` | no |  | The target audience for this account. |
+| `--tax_collection_enabled_states` | `array` | no |  | US state codes (50 states plus `DC`) where the account collects tax. Replaces the full set on update. Only settable when `tax_remitted_by` is `self`. |
+| `--tax_identifiers` | `array` | no |  | Account tax/VAT registrations to add or update. When `tax_remitted_by` is `self`, tax is calculated and collected only in the countries where the account holds a registration. |
+| `--tax_remitted_by` | `string` | no |  | Determines whether Whop or the account calculates and remits tax. The account must provide a supported-country business address when it self-remits. |
+| `--tax_type` | `string` | no |  | Determines whether tax is included in the listed price or added at checkout. |
+| `--title` | `unknown` | no |  | The display name of the account. |
+| `--use_logo_as_opengraph_image_fallback` | `boolean` | no |  | Whether the account uses its logo as the fallback Open Graph image. |
+
+> Confirm with the user before executing this destructive command.
+
+---
+
+# whop accounts update-preferences
+
+Update Account Preferences
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--account_id` | `string` | no |  | Account ID, prefixed `biz_`. |
+| `--ads_payment_methods` | `object` | no |  | How the account pays for Whop Ads spend. `primary` is charged first; `backup` covers the charge when the primary fails. |
+| `--ads_reporting_currency` | `string` | no |  | Lowercase ISO currency code, such as `usd` or `eur`, used to display ad spend and stats. Defaults to `usd`. |
+| `--ads_scheduling_timezone` | `string` | no |  | IANA timezone (e.g. `America/New_York`) used to interpret campaign start/end times and to bucket reports. Cannot be cleared once set — pass a new value to change it. |
+| `--ads_triple_whale_integration` | `object` | no |  | Connects or disconnects the Triple Whale integration. Requires a connected Shopify store, since Triple Whale keys spend records by Shopify shop. |
+| `--cards_auto_top_up` | `boolean` | no |  | Whether incoming funds are automatically moved to the account's cards balance. Requires a cards balance on the account. |
+
+> Confirm with the user before executing this destructive command.
+
+## 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`, `checkout_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-ad-campaigns/SKILL.md

@@ -9,18 +9,196 @@ An Ad Campaign is the top-level container for paid ads on an ad network. It sets
 
 Use the Ad Campaigns API to create campaigns, list campaigns for an account, retrieve or update campaign settings, and pause or resume campaign delivery.
 
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `whop ad-campaigns list` | List Ad Campaigns |
-| `whop ad-campaigns create` | Create an Ad Campaign |
-| `whop ad-campaigns delete` | Delete an Ad Campaign |
-| `whop ad-campaigns get` | Retrieve an Ad Campaign |
-| `whop ad-campaigns update` | Update an Ad Campaign |
-| `whop ad-campaigns duplicate` | Duplicate an Ad Campaign |
-| `whop ad-campaigns pause` | Pause an Ad Campaign |
-| `whop ad-campaigns retry_payment` | Retry a Failed Ad Campaign Payment |
-| `whop ad-campaigns unpause` | Unpause an Ad Campaign |
-
-Run `whop ad-campaigns <command> --help` for options, or `whop ad-campaigns <command> --schema` for full argument details.
+# whop ad-campaigns create
+
+Create an Ad Campaign
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--account_id` | `string` | no |  | The account to create the campaign under. Defaults to the account-scoped key's own account. |
+| `--bid_type` | `string` | no |  | How delivery bids in the ad auction: `minimum_cost` gets the most results for the budget, `average_target` holds an average cost per result, `maximum_target` never bids above a cap. Only for campaigns that own the budget. |
+| `--budget_amount` | `number` | no |  | The campaign's budget, in the ad account's currency. Required when budget_optimization is `ad_campaign`; omit when each ad group sets its own budget. |
+| `--budget_optimization` | `string` | no |  | Which level owns the budget: the whole campaign (`ad_campaign`) or each ad group individually (`ad_group`). Defaults to `ad_group`. |
+| `--budget_type` | `string` | no |  | Whether the budget is spent per day (`daily`) or over the campaign's full run (`lifetime`). Defaults to `daily`. |
+| `--desired_cost_per_result` | `number` | no |  | Cost per result to aim for (`average_target`) or never exceed (`maximum_target`). Only for campaigns that own the budget. |
+| `--ends_at` | `string` | no |  | When the campaign stops delivering, as an ISO 8601 timestamp. Only for campaigns that own the budget. |
+| `--objective` | `string` | yes |  | The goal the campaign optimizes toward. |
+| `--platform` | `string` | yes |  | The ad network the campaign runs on. |
+| `--special_ad_categories` | `array` | no |  | Regulated categories the campaign falls under. Ads in these categories are subject to extra targeting restrictions. |
+| `--starts_at` | `string` | no |  | When the campaign starts delivering, as an ISO 8601 timestamp. Only for campaigns that own the budget. |
+| `--title` | `string` | yes |  | The title of the campaign. |
+| `--idempotency-key` | `string` | no |  | A unique key that makes this request safe to retry. See [Idempotent requests](https://docs.whop.com/developer/api/idempotency). |
+
+> Confirm with the user before executing this destructive command.
+
+---
+
+# whop ad-campaigns delete
+
+Delete an Ad Campaign
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | yes | The ad campaign ID. |
+
+> Confirm with the user before executing this destructive command.
+
+---
+
+# whop ad-campaigns duplicate
+
+Duplicate an Ad Campaign
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | yes | The ad campaign ID. |
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--count` | `number` | no |  | Number of copies to create (1-10). Defaults to 1. |
+| `--preserve_engagement` | `boolean` | no |  | Whether the copied ads keep the original posts' engagement (likes, comments, shares). Defaults to false. |
+| `--idempotency-key` | `string` | no |  | A unique key that makes this request safe to retry. See [Idempotent requests](https://docs.whop.com/developer/api/idempotency). |
+
+> Confirm with the user before executing this destructive command.
+
+---
+
+# whop ad-campaigns get
+
+Retrieve an Ad Campaign
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | yes | The ad campaign ID. |
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--stats_from` | `string` | no |  | Start of the stats window. |
+| `--stats_to` | `string` | no |  | End of the stats window. |
+| `--time_zone` | `string` | no |  | IANA timezone the stats window is interpreted in. Defaults to UTC. |
+| `--attribution_model` | `string` | no |  | Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise. |
+
+---
+
+# whop ad-campaigns list
+
+List Ad Campaigns
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--account_id` | `string` | no |  | The account the campaigns belong to. Defaults to the account-scoped key's own account. |
+| `--status` | `string` | no |  | Only return campaigns with this status. |
+| `--query` | `string` | no |  | Filter campaigns by a title or ID substring. |
+| `--order` | `string` | no |  | The field to sort by. Defaults to created_at. Stat columns (spend, impressions, …) rank over the stats_from/stats_to window across the whole list, not just the current page. results, cost_per_result and return_on_ad_spend rank by the same Whop pixel-attributed values the response reports. |
+| `--direction` | `string` | no |  | The sort direction. Defaults to desc. |
+| `--created_before` | `string` | no |  | Only return campaigns created before this timestamp. |
+| `--created_after` | `string` | no |  | Only return campaigns created after this timestamp. |
+| `--stats_from` | `string` | no |  | Start of the stats window. Defaults to all-time. |
+| `--stats_to` | `string` | no |  | End of the stats window. Defaults to now. |
+| `--time_zone` | `string` | no |  | IANA timezone (e.g. America/New_York) the stats window is interpreted in. Bare stats_from/stats_to dates resolve to day boundaries on this clock. Defaults to UTC. |
+| `--attribution_model` | `string` | no |  | Attribution model the conversion stats count under (defaults to last_touch). Under both models a journey with any whop ad touch attributes to whop; the model picks which whop touch credits the entity and which non-whop source wins otherwise. |
+| `--first` | `number` | no | `20` | The number of campaigns to return. |
+| `--after` | `string` | no |  | Cursor to fetch the page after (from page_info.end_cursor). |
+| `--last` | `number` | no |  | The number of campaigns to return from the end of the range. |
+| `--before` | `string` | no |  | Cursor to fetch the page before (from page_info.start_cursor). |
+
+---
+
+# whop ad-campaigns pause
+
+Pause an Ad Campaign
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | yes | The ad campaign ID. |
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--idempotency-key` | `string` | no |  | A unique key that makes this request safe to retry. See [Idempotent requests](https://docs.whop.com/developer/api/idempotency). |
+
+> Confirm with the user before executing this destructive command.
+
+---
+
+# whop ad-campaigns retry_payment
+
+Retry a Failed Ad Campaign Payment
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | yes | The ad campaign ID. |
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--idempotency-key` | `string` | no |  | A unique key that makes this request safe to retry. See [Idempotent requests](https://docs.whop.com/developer/api/idempotency). |
+
+> Confirm with the user before executing this destructive command.
+
+---
+
+# whop ad-campaigns unpause
+
+Unpause an Ad Campaign
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | yes | The ad campaign ID. |
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--idempotency-key` | `string` | no |  | A unique key that makes this request safe to retry. See [Idempotent requests](https://docs.whop.com/developer/api/idempotency). |
+
+> Confirm with the user before executing this destructive command.
+
+---
+
+# whop ad-campaigns update
+
+Update an Ad Campaign
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | yes | The ad campaign ID. |
+
+## Options
+
+| Flag | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `--bid_type` | `string` | no |  | How delivery bids in the ad auction: `minimum_cost` gets the most results for the budget, `average_target` holds an average cost per result, `maximum_target` never bids above a cap. Switching to `minimum_cost` clears the cap amounts stored on the campaign's ad groups. Only for campaigns that own the budget. |
+| `--budget_amount` | `number` | no |  | The campaign budget, in the account's currency. Interpreted as daily or lifetime per the campaign's existing budget type. |
+| `--budget_optimization` | `string` | no |  | Which level owns the budget: the whole campaign (`ad_campaign`) or each ad group individually (`ad_group`). Only changeable before the campaign is live on the ad network; switching to `ad_campaign` requires budget_amount in the same request, and switching to `ad_group` clears the campaign budget. |
+| `--ends_at` | `string` | no |  | When the campaign stops delivering, as an ISO 8601 timestamp. Only for campaigns that own the budget. |
+| `--special_ad_categories` | `array` | no |  | Regulated categories the campaign falls under. Editable on any campaign, draft or launched; pass an empty array to clear. |
+| `--starts_at` | `string` | no |  | When the campaign starts delivering, as an ISO 8601 timestamp. Only for campaigns that own the budget. |
+| `--status` | `string` | no |  | Set to active to launch a draft campaign (moderates and pushes it live). Live-campaign pause and resume use the pause and unpause actions. |
+| `--title` | `string` | no |  | The name of the campaign. |
+
+> Confirm with the user before executing this destructive command.