@thenavidm/fourthwall-mcp-cli

v3.0.0

Published

a month ago

Fourthwall shared CLI and local MCP: isolated shop profiles, reviewed operational batches, mandatory effect approval, bounded metadata exports and private upload receipts.

Fourthwall MCP Server & CLI

Fourthwall MCP server and CLI for Codex and AI agents. 86 shared tasks for shop operations, isolated private profiles, reviewed batches, bounded metadata exports and private uploads.

One install, the same tools and guard on both surfaces. Fourthwall's official hosted OAuth MCP already provides broader coverage. This companion adds specific local workflows; read the comparison before choosing.

Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI.

Two ways to use it

Command line

fourthwall-cli tools
fourthwall-cli list-products --page 0 --size 25 --agent
fourthwall-cli get-operation-schema --operation toggle_product_availability --agent
fourthwall-cli <command> --help

Use it directly or let your shell agent call it. Configure the intended private shop first. Every effect requires --confirm; output flags never grant approval.

MCP server, for your AI app

codex mcp add fourthwall -- npx -y @thenavidm/fourthwall-mcp-cli@latest

An MCP client launches the local stdio server and discovers the same tasks. Forward private credential settings through your client runtime. The full client/OS setup is in INSTALL.md.

Which one

| Where you work | Surface | | --- | --- | | Codex or another agent with shell access | CLI, local MCP, or both | | A supported local MCP app | Local MCP; desktop extension where supported | | A script or CI task | CLI with private secrets supplied by the runtime | | A URL-only hosted MCP client | Fourthwall's official hosted MCP is an alternative |

Features

| Capability | CLI command | MCP tool | | --- | --- | --- | | Get a webhook | fourthwall-cli get-webhook | get_webhook | | Update a webhook | fourthwall-cli update-webhook | update_webhook | | Delete a webhook | fourthwall-cli delete-webhook | delete_webhook | | Set streaming status to started | fourthwall-cli start-streaming | start_streaming | | Set streaming status to ended | fourthwall-cli end-streaming | end_streaming | | Get or create a public token | fourthwall-cli get-public-token | get_public_token | | Get a promotion by id | fourthwall-cli get-promotion | get_promotion | | Update a promotion | fourthwall-cli update-promotion | update_promotion | | Update product (offer) lifecycle state | fourthwall-cli update-product-state | update_product_state | | Update product (offer) availability by id | fourthwall-cli toggle-product-availability | toggle_product_availability | | Mark digital download as downloaded | fourthwall-cli mark-download-complete | mark_download_complete | | Finish giveaway | fourthwall-cli finish-giveaway | finish_giveaway | | Create or update giveaway | fourthwall-cli create-giveaway-checkout | create_giveaway_checkout | | Disable giveaway config | fourthwall-cli disable-giveaway-checkout | disable_giveaway_checkout | | Finish draw | fourthwall-cli finish-giveaway-draw | finish_giveaway_draw | | Get gifting config | fourthwall-cli get-gifting-config | get_gifting_config | | Update gifting config | fourthwall-cli update-gifting-config | update_gifting_config | | Update a collection | fourthwall-cli update-collection | update_collection | | Get products in a collection | fourthwall-cli get-collection-products | get_collection_products | | Set collection products | fourthwall-cli update-collection-products | update_collection_products | | Update collection availability | fourthwall-cli update-collection-availability | update_collection_availability | | Get webhooks | fourthwall-cli list-webhooks | list_webhooks | | Create a webhook | fourthwall-cli create-webhook | create_webhook | | Get all promotions | fourthwall-cli list-promotions | list_promotions | | Create a promotion | fourthwall-cli create-promotion | create_promotion | | Get all products (offers) | fourthwall-cli list-products | list_products | | Create a product | fourthwall-cli create-product | create_product | | Attach images to a product | fourthwall-cli attach-product-images | attach_product_images | | Remove images from a product | fourthwall-cli remove-product-images | remove_product_images | | Confirm and link an uploaded digital file | fourthwall-cli confirm-digital-file-upload | confirm_digital_file_upload | | Remove a digital file from a product | fourthwall-cli remove-digital-file | remove_digital_file | | Request a presigned upload URL for a digital file | fourthwall-cli request-digital-file-upload-url | request_digital_file_upload_url | | Request a pre-signed upload URL | fourthwall-cli request-media-upload-url | request_media_upload_url | | List media library images | fourthwall-cli list-media-images | list_media_images | | Save an uploaded image to the media library | fourthwall-cli save-media-image | save_media_image | | Create a new giveaway | fourthwall-cli create-giveaway | create_giveaway | | Create giveaway links | fourthwall-cli create-giveaway-links | create_giveaway_links | | Create a gifting checkout | fourthwall-cli create-gifting-checkout | create_gifting_checkout | | Create a fulfillment for an order | fourthwall-cli create-fulfillment | create_fulfillment | | Validate DNS records | fourthwall-cli validate-dns | validate_dns | | Get all collections | fourthwall-cli list-collections | list_collections | | Create a new collection | fourthwall-cli create-collection | create_collection | | Get webhook events | fourthwall-cli list-webhook-events | list_webhook_events | | Get a webhook event | fourthwall-cli get-webhook-event | get_webhook_event | | Get Thank You by id | fourthwall-cli get-thank-you | get_thank_you | | Get contributions awaiting thank you | fourthwall-cli list-contributions | list_contributions | | Get streaming status | fourthwall-cli get-streaming-status | get_streaming_status | | Get current shop | fourthwall-cli get-shop | get_shop | | Get current shop contact info | fourthwall-cli get-shop-contact | get_shop_contact | | Get sample credit balance | fourthwall-cli get-sample-balance | get_sample_balance | | List available reports | fourthwall-cli list-reports | list_reports | | Get a report | fourthwall-cli get-report | get_report | | Get product (offer) by id | fourthwall-cli get-product | get_product | | Archive a product (offer) | fourthwall-cli archive-product | archive_product | | Get product (offer) inventory by id | fourthwall-cli get-product-inventory | get_product_inventory | | List product templates | fourthwall-cli list-product-templates | list_product_templates | | Get product template details | fourthwall-cli get-product-template | get_product_template | | Search product templates | fourthwall-cli search-product-templates | search_product_templates | | Search product templates by page | fourthwall-cli search-product-templates-paged | search_product_templates_paged | | Search product templates grouped by product family | fourthwall-cli search-product-templates-grouped | search_product_templates_grouped | | Search product templates grouped by product family by page | fourthwall-cli search-product-templates-grouped-paged | search_product_templates_grouped_paged | | List product templates by page | fourthwall-cli list-product-templates-paged | list_product_templates_paged | | Browse product templates by category | fourthwall-cli list-product-templates-by-category | list_product_templates_by_category | | Browse product templates by category by page | fourthwall-cli list-product-templates-by-category-paged | list_product_templates_by_category_paged | | Get Pro subscription status | fourthwall-cli get-pro-subscription | get_pro_subscription | | Get all orders | fourthwall-cli list-orders | list_orders | | Get order by id | fourthwall-cli get-order | get_order | | Get order by friendly id | fourthwall-cli get-order-by-friendly-id | get_order_by_friendly_id | | List membership tiers | fourthwall-cli list-membership-tiers | list_membership_tiers | | List members | fourthwall-cli list-members | list_members | | Get member | fourthwall-cli get-member | get_member | | Get all mailing list entries | fourthwall-cli list-mailing-list | list_mailing_list | | Get all giveaway packages | fourthwall-cli list-giveaway-packages | list_giveaway_packages | | Get giveaway links | fourthwall-cli get-giveaway-package | get_giveaway_package | | Get draw | fourthwall-cli get-giveaway-draw | get_giveaway_draw | | Get gift purchase by id | fourthwall-cli get-gift-purchase | get_gift_purchase | | Get all donations | fourthwall-cli list-donations | list_donations | | Get donation by id | fourthwall-cli get-donation | get_donation | | Get DNS configuration status | fourthwall-cli get-dns-status | get_dns_status | | Get collection by ID or slug | fourthwall-cli get-collection | get_collection | | List private shop profiles | fourthwall-cli list-accounts | list_accounts | | Inspect native contract | fourthwall-cli get-operation-schema | get_operation_schema | | Review ordered shop effects | fourthwall-cli preview-shop-batch | preview_shop_batch | | Execute reviewed shop effects | fourthwall-cli submit-shop-batch | submit_shop_batch | | Export bounded private metadata | fourthwall-cli export-resources | export_resources | | Upload exact bytes from a private receipt | fourthwall-cli upload-file | upload_file |

1. What you can ask it

Ask for a bounded shop task, then review any change before execution:

List the first 25 products in the intended shop and report their state and availability separately.
Read this order and check the native fulfillment contract before preparing a tracking update.
Review these exact product availability changes, then execute only the batch I approve.
Export up to ten pages of order metadata into a new private file and report continuation.
Prepare a hidden digital product from this reviewed native payload. Do not publish it implicitly.
Upload this local image from a private receipt, then show the separate registration step.

These prompts name implemented operations. The terminal animation illustrates a reviewed workflow, rather than an authenticated shop recording.

2. Set up your account

A Fourthwall SUPER ADMIN can create shop API credentials in Settings > For Developers. Follow Fourthwall authentication. Shop Basic credentials grant full shop access; never describe them as a read-only key.

Choose exactly one private source: FOURTHWALL_USERNAME and FOURTHWALL_PASSWORD, an existing FOURTHWALL_ACCESS_TOKEN, or FOURTHWALL_CREDENTIALS_FILE. OAuth permission comes from the provider. This package does not implement consent, exchange or refresh.

The credential file is a JSON object containing either username/password or access_token. It must be an absolute regular non-symlink file, at most 64 KiB, outside repositories. On POSIX the process user must own it and permissions must be owner-only, normally 0600; restrict Windows ACLs separately. Never paste credentials into chat, command transcripts, issues, payloads or project configuration.

fourthwall-cli login
fourthwall-cli list-accounts --agent
fourthwall-cli doctor
fourthwall-cli doctor --network

Login prints instructions. Doctor checks local profiles and policy; the deliberate network option reads the current shop and validates its id. One successful read does not prove every permission, every task or resource ownership. File credentials are cached for the process: restart clients after rotating or revoking them.

Settings

| Variable | Default | Meaning | | --- | --- | --- | | FOURTHWALL_USERNAME, FOURTHWALL_PASSWORD | None | Shop API Basic credentials | | FOURTHWALL_ACCESS_TOKEN | None | An existing scoped access token, in place of a username and password | | FOURTHWALL_CREDENTIALS_FILE | None | Absolute owner-only JSON file holding a username and password or an access token | | FOURTHWALL_ACCOUNTS | None | Named isolated profiles, each with one credential source | | FOURTHWALL_DEFAULT_ACCOUNT | First profile | The profile a call uses when it names none | | FOURTHWALL_READ_ONLY | 0 | 1 hides and refuses every effect | | FOURTHWALL_ALLOW_DESTRUCTIVE | 1 | 0 refuses every effect, even confirmed | | FOURTHWALL_CONFIRM | human | model lets confirm:true alone approve over MCP, for an agent with no person to ask | | FOURTHWALL_AUDIT_LOG | None | File that records every attempted effect, without payloads or credentials | | FOURTHWALL_REQUEST_TIMEOUT_MS | 30000 | Each request's deadline; no retries | | FOURTHWALL_MIN_REQUEST_INTERVAL_MS | 1000 | Pacing between requests; Fourthwall's tighter limits are paced too | | FOURTHWALL_SURFACE | full | search lists three tools that find, describe and run the rest | | FOURTHWALL_TOOL_TIMEOUT_MS | None | Give up on any tool after this long | | FOURTHWALL_HTTP_PORT, FOURTHWALL_HTTP_HOST, FOURTHWALL_HTTP_TOKEN | 8787, 127.0.0.1, none | For --http; any host but 127.0.0.1 needs the bearer token | | FOURTHWALL_HTTP_ALLOWED_ORIGINS | None | Comma-separated browser origins allowed to call --http; a page from any other site is refused | | FOURTHWALL_DEBUG | 0 | 1 prints debug lines on stderr |

3. Install

Install Node 22+ in the runtime that launches the server. Use the complete INSTALL.md for Codex, Claude Code, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Docker and all three desktop OSes.

npm install -g @thenavidm/fourthwall-mcp-cli@latest
fourthwall-cli --version
fourthwall-cli tools
fourthwall-cli schema list-products

After configuring credentials privately, register the local server in Codex:

codex mcp add fourthwall -- npx -y @thenavidm/fourthwall-mcp-cli@latest
codex mcp list

The MCP executable speaks stdio; it is not a hosted URL. The desktop extension is fourthwall-3.0.0.mcpb. Manual installation and updates use the host's supported extension screen. Choose one auth source, leave unused inputs empty and reconnect. GUI installation and authenticated provider tasks require their own validation.

4. Output and exit codes

Both binaries use the same schemas, handlers, validation and confirmation guard. --json prints JSON, --compact prints a single line, and --agent gives compact JSON with no prompts and never confirms a write. fourthwall-cli which <words> finds the command for a task. --select projects requested output fields. Errors go to stderr. --yes suppresses interactive presentation; it never replaces --confirm.

| Exit | Meaning | | --- | --- | | 0 | Successful command | | 1 | Unexpected error | | 2 | Usage, invalid arguments, a refused effect, an unknown command or a hidden write | | 3 | Not found | | 4 | Provider authentication/permission failure | | 5 | Other API/network failure | | 7 | Provider quota/rate limit | | 10 | Missing/invalid local configuration |

fourthwall-cli list-products --page 0 --size 25 --agent
fourthwall-cli get-shop --account intended-shop --json
fourthwall-cli schema create-promotion

Tool path/query snake_case arguments become dash flags. Native body fields retain their exact camelCase flags, such as --fileName and --contentType; inspect --help instead of guessing a spelling. Objects and arrays use JSON. Use a private --payload-file for larger native bodies. Do not mix payload, payload-file and flat body fields.

5. Which surface and what each costs

Use CLI for scripts, shell agents and selected tasks. Use MCP where your app discovers tools and calls them directly. Both surfaces reach the same 86 tasks and enforce the same approval policy.

| Surface | Context and task considerations | | --- | --- | | CLI | Command help and results enter context on demand; agent shell access is needed | | MCP | Tool schemas may be loaded or deferred depending on the client; result content still costs context | | Read-only MCP | Exposes 49 reads and excludes 37 effects locally | | Official hosted MCP | Broad OAuth tooling with its own schemas, previews and confirmation flow |

Measured on 2026-10-05 against 2.0.1, with Claude Code 2.1.286 on Claude Opus 5.5 (one short prompt with and without the server connected, the difference read from the API's own usage figures) and Codex 0.159.3 on gpt-6.1-sol:

| Cost | 2.0.1 | 3.0.0 | | --- | --- | --- | | Claude Code, every tool loaded, every message | 43,696 | 39,922 | | Claude Code's default, tool search, every message | 1,610 | 1,608 | | SKILL.md, read once | 518 | 662 | | Codex over the CLI, one task, median of five | 130,541 | 108,648 | | Codex over MCP, the same task, median of five | 77,214 | 77,915 |

The task was "find the command that creates a promotion, and the flags it requires". Every tool loaded costs less because parts that several tools repeated are written once. Over the CLI, every 3.0.0 run asked which, whose answer carries the command's help, where three 2.0.1 runs tried schema without a command and then read the whole command list; the schema both versions read next is half the size on 3.0.0. Over MCP, Codex now prints create_promotion's payload with every promotion type and its fields, where it printed 2.0.1's as unknown, about 700 tokens more. SKILL.md costs 144 more because it says how approval works over MCP and how which finds a command, and lists every exit code.

Tool-list bytes or characters divided by four are not API usage, and no other offering was measured.

6. Tools

49 reads and 37 confirmed effects. All 86 tasks follow below; nested native JSON fields come from the selected reviewed schema.

get_webhook

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get a webhook

CLI: fourthwall-cli get-webhook. Policy: read.

Native: GET /open-api/v1.0/webhooks/{webhookConfigurationId}. Current source.

update_webhook

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Update a webhook

CLI: fourthwall-cli update-webhook. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/webhooks/{webhookConfigurationId}. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | webhook_configuration_id | string (minLength=1, maxLength=256) | Required | Native webhookConfigurationId | | url | string | Optional | Native field | | allowedTypes | array | Optional | Native field | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | url | string | Required | Native field | | allowedTypes | array | Required | Native field |

delete_webhook

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Delete a webhook

CLI: fourthwall-cli delete-webhook. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/webhooks/{webhookConfigurationId}. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | webhook_configuration_id | string (minLength=1, maxLength=256) | Required | Native webhookConfigurationId | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. |

start_streaming

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets streaming status to started for specified services

CLI: fourthwall-cli start-streaming. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/streaming/start. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | services | array | Optional | Native field | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | services | array | Required | Native field | | services.[].variant 1 | value | Choose one | Native oneOf | | services.[].variant1.type | string | Required | Native field | | services.[].variant1.broadcasterId | string | Optional | Native field | | services.[].variant1.broadcasterLogin | string | Optional | Native field | | services.[].variant1.thumbnailUrl | string | Optional | Native field |

end_streaming

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets streaming status to ended for specified services

CLI: fourthwall-cli end-streaming. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/streaming/end. Current source.

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | services | array | Required | Native field |

get_public_token

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns an existing public token for the shop, or creates a new one if none exists

CLI: fourthwall-cli get-public-token. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/public-token. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | output_file | string (minLength=1) | Required | Absolute NEW owner-private receipt file; exclusive0600 creation, no overwrite. Upload/public-token URLs never enter ordinary output. |

get_promotion

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a promotion by id

CLI: fourthwall-cli get-promotion. Policy: read.

Native: GET /open-api/v1.0/promotions/{promotionId}. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | promotion_id | string (minLength=1, maxLength=256) | Required | Native promotionId | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. |

update_promotion

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates an existing promotion's configuration. Only provided fields are updated; omitted fields remain unchanged. Status changes (activate/deactivate) are part of the same update call.

CLI: fourthwall-cli update-promotion. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/promotions/{promotionId}. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | promotion_id | string (minLength=1, maxLength=256) | Required | Native promotionId | | limits | object | Optional | Native field | | requirements | object | Optional | Native field | | appliesTo | union | Optional | Native field | | status | LIVE, ENDED | Optional | Native field | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | limits | object | Optional | Native field | | limits.maximumUse | integer (format=int32) | Optional | Native field | | limits.oneUsePerCustomer | boolean | Required | Native field | | requirements | object | Optional | Native field | | requirements.minimumOrderValue | object | Optional | Native field | | requirements.minimumOrderValue.value | number (minimum=0) | Required | Native field | | requirements.minimumOrderValue.currency | string | Required | Native field | | appliesTo | union | Optional | Native field | | appliesTo.variant 1 | value | Choose one | Native oneOf | | appliesTo.variant1.type | string | Optional | Native field | | appliesTo.variant 2 | value | Choose one | Native oneOf | | appliesTo.variant2.productIds | array | Optional | Native field | | appliesTo.variant2.oncePerOrder | boolean | Optional | Native field | | status | LIVE, ENDED | Optional | Native field |

update_product_state

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Transitions the product between PUBLIC and HIDDEN. Use DELETE /products/{productId} to archive — ARCHIVED is not reachable here. The sold-out (available) flag is preserved; flip it via PUT /products/{productId}/availability. Idempotent: no-op if the product is already in the requested state.

CLI: fourthwall-cli update-product-state. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/products/{productId}/state. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | product_id | string (minLength=1, maxLength=256) | Required | Native productId | | state | PUBLIC, HIDDEN | Optional | Target lifecycle state. PUBLIC makes the product visible on the storefront; HIDDEN keeps it unlisted. The sold-out (available) flag is preserved across the transition — use PUT /products/{productId}/availability to flip it. | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | state | PUBLIC, HIDDEN | Required | Target lifecycle state. PUBLIC makes the product visible on the storefront; HIDDEN keeps it unlisted. The sold-out (available) flag is preserved across the transition — use PUT /products/{productId}/availability to flip it. |

toggle_product_availability

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates a product (offer) availability

CLI: fourthwall-cli toggle-product-availability. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/products/{productId}/availability. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | product_id | string (minLength=1, maxLength=256) | Required | Native productId | | available | boolean | Optional | Native field | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | available | boolean | Required | Native field |

mark_download_complete

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Marks digital download as downloaded. If no downloads exist for a digital order and defaultFileUrl is provided in the request body, creates a download with that URL and marks it as downloaded.

CLI: fourthwall-cli mark-download-complete. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/order/{orderId}/downloaded. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | order_id | string (minLength=1, maxLength=256) | Required | Native orderId | | defaultFileUrl | string | Optional | Native field | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | defaultFileUrl | string | Optional | Native field |

finish_giveaway

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Finish giveaway and select winners

CLI: fourthwall-cli finish-giveaway. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/giveaways/giveaways/{id}/finish/twitch. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | id | string (minLength=1, maxLength=256) | Required | Native id | | participants | array | Optional | Native field | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | participants | array | Required | Native field | | participants.[].userId | string | Required | Native field | | participants.[].userName | string | Required | Native field |

create_giveaway_checkout

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new giveaway or updates existing one

CLI: fourthwall-cli create-giveaway-checkout. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/giveaways/giveaway-checkout. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | heading | string | Optional | Native field | | description | string | Optional | Native field | | iconUrl | string | Optional | Native field | | buttonText | string | Optional | Native field | | disabled | boolean | Optional | Native field | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | heading | string | Required | Native field | | description | string | Required | Native field | | iconUrl | string | Required | Native field | | buttonText | string | Required | Native field | | disabled | boolean | Optional | Native field |

disable_giveaway_checkout

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

disables a giveaway config

CLI: fourthwall-cli disable-giveaway-checkout. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/giveaways/giveaway-checkout. Current source.

finish_giveaway_draw

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Finish draw and select winners

CLI: fourthwall-cli finish-giveaway-draw. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/gifting/draw/{id}/finish. Current source.

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | participants | array | Required | Native field | | participants.[].variant 1 | value | Choose one | Native oneOf | | participants.[].variant1.service | string | Required | Native field | | participants.[].variant1.userId | string | Optional | Native field | | participants.[].variant1.userName | string | Optional | Native field |

get_gifting_config

Returns the calling shop's saved gifting rules. Returns a default-shaped config when none is persisted yet.

CLI: fourthwall-cli get-gifting-config. Policy: read.

Native: GET /open-api/v1.0/gifting/config. Current source.

update_gifting_config

Writes the four creator-controlled gifting rule fields. Validation (duration 20-180s, valid shipping/products) and the one-platform-per-shop mutex are enforced server-side. Upserts: a first-ever PUT materializes the config row.

CLI: fourthwall-cli update-gifting-config. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/gifting/config. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | enabled | boolean | Optional | Master flag. Off pauses purchasability without losing the rest. | | entryTimeLimitSeconds | integer (format=int32) | Optional | Entry time limit in seconds. Validated 20-180. | | shipping | union | Optional | Native field | | products | union | Optional | Native field | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | enabled | boolean | Required | Master flag. Off pauses purchasability without losing the rest. | | entryTimeLimitSeconds | integer (format=int32) | Required | Entry time limit in seconds. Validated 20-180. | | shipping | union | Required | Native field | | shipping.variant 1 | value | Choose one | Native oneOf | | shipping.variant1.type | string | Required | Native field | | shipping.variant1.type | ALL_CREATOR | Optional | Native field | | shipping.variant 2 | value | Choose one | Native oneOf | | shipping.variant2.type | string | Required | Native field | | shipping.variant2.type | ALL_WINNER | Optional | Native field | | shipping.variant 3 | value | Choose one | Native oneOf | | shipping.variant3.type | string | Required | Native field | | shipping.variant3.max | number (format=double) | Optional | Native field | | shipping.variant3.type | MAX_CREATOR | Optional | Native field | | products | union | Required | Native field | | products.variant 1 | value | Choose one | Native oneOf | | products.variant1.type | string | Required | Native field | | products.variant1.type | ALL | Optional | Native field | | products.variant 2 | value | Choose one | Native oneOf | | products.variant2.type | string | Required | Native field | | products.variant2.offerIds | array | Optional | Native field | | products.variant2.type | EXCLUDED | Optional | Native field | | products.variant 3 | value | Choose one | Native oneOf | | products.variant3.type | string | Required | Native field | | products.variant3.offerIds | array | Optional | Native field | | products.variant3.type | SELECTED | Optional | Native field |

update_collection

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates collection name, description, and/or product list

CLI: fourthwall-cli update-collection. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/collections/{collectionId}. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | collection_id | string (minLength=1, maxLength=256) | Required | Native collectionId | | name | string | Optional | Native field | | description | string | Optional | Native field | | offerIds | array | Optional | List of product IDs to set in the collection | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | name | string | Optional | Native field | | description | string | Optional | Native field | | offerIds | array | Optional | List of product IDs to set in the collection |

get_collection_products

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns paginated products in a collection with optional status filtering. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli get-collection-products. Policy: read.

Native: GET /open-api/v1.0/collections/{collectionId}/products. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | collection_id | string (minLength=1, maxLength=256) | Required | Native collectionId | | page | integer (minimum=0, format=int32, default=0) | Optional | Native page | | size | integer (minimum=1, maximum=100, format=int32, default=20) | Optional | Number of elements per page. The maximum page size is 100 - larger values are capped at 100. | | status | PUBLIC, AVAILABLE, SOLD_OUT, HIDDEN, ARCHIVED | Optional | Filter by product status | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. |

update_collection_products

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets the full list of product IDs in the collection

CLI: fourthwall-cli update-collection-products. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/collections/{collectionId}/products. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | collection_id | string (minLength=1, maxLength=256) | Required | Native collectionId | | offerIds | array | Optional | Full list of product IDs to set in the collection | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | offerIds | array | Required | Full list of product IDs to set in the collection |

update_collection_availability

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Toggle collection availability (available/unavailable)

CLI: fourthwall-cli update-collection-availability. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/collections/{collectionId}/availability. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | collection_id | string (minLength=1, maxLength=256) | Required | Native collectionId | | available | boolean | Optional | Native field | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | available | boolean | Required | Native field |

list_webhooks

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get webhooks

CLI: fourthwall-cli list-webhooks. Policy: read.

Native: GET /open-api/v1.0/webhooks. Current source.

create_webhook

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Create a webhook

CLI: fourthwall-cli create-webhook. Policy: explicit confirmation.

Native: POST /open-api/v1.0/webhooks. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | url | string | Optional | Native field | | allowedTypes | array | Optional | Native field | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | url | string | Required | Native field | | allowedTypes | array | Required | Native field |

list_promotions

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all promotions. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-promotions. Policy: read.

Native: GET /open-api/v1.0/promotions. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | page | integer (minimum=0, format=int32, default=0) | Optional | Native page | | size | integer (minimum=1, maximum=100, format=int32, default=20) | Optional | Number of elements per page. The maximum page size is 100 - larger values are capped at 100. | | codes | array | Optional | Filter by promotion code(s) | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. |

create_promotion

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a promotion

CLI: fourthwall-cli create-promotion. Policy: explicit confirmation.

Native: POST /open-api/v1.0/promotions. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | union | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

| Native JSON field | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | variant 1 | value | Choose one | Native oneOf | | variant1.type | string | Required | Native field | | variant1.codes | array | Optional | Native field | | variant1.discount | union | Optional | Native field | | variant1.discount.variant 1 | value | Choose one | Native oneOf | | variant1.discount.variant1.type | string | Required | Native field | | variant1.discount.variant1.percentage | number | Optional | Native field | | variant1.discount.variant1.type | PERCENTAGE | Optional | Native field | | variant1.requirements | object | Optional | Native field | | variant1.requirements.newMembersOnly | boolean | Required | Native field | | variant1.subscriptionType | union | Optional | Native field | | variant1.subscriptionType.variant 1 | value | Choose one | Native oneOf | | variant1.subscriptionType.variant1.type | string | Required | Native field | | variant1.subscriptionType.variant1.type | ALL | Optional | Native field | | variant1.subscriptionType.variant 2 | value | Choose one | Native oneOf | | variant1.subscriptionType.variant2.type | string | Required | Native field | | variant1.subscriptionType.variant2.type | ANNUAL | Optional | Native field | | variant1.subscriptionType.variant 3 | value | Choose one | Native oneOf | | variant1.subscriptionType.variant3.type | string | Required | Native field | | variant1.subscriptionType.variant3.type | MONTHLY | Optional | Native field | | variant1.tiers | union | Optional | Native field | | variant1.tiers.variant 1 | value | Choose one | Native oneOf | | variant1.tiers.variant1.type | string | Required | Native field | | variant1.tiers.variant1.type | ALL | Optional | Native field | | variant1.tiers.variant 2 | value | Choose one | Native oneOf | | variant1.tiers.variant2.type | string | Required | Native field | | variant1.tiers.variant2.ids | array | Optional | Native field | | variant1.tiers.variant2.type | SELECTED | Optional | Native field | | variant1.type | MEMBERSHIPS_MULTI | Optional | Native field | | variant 2 | value | Choose one | Native oneOf | | variant2.type | string | Required | Native field | | variant2.code | string | Optional | Native field | | variant2.discount | union | Optional | Native field | | variant2.discount.variant 1 | value | Choose one | Native oneOf | | variant2.discount.variant1.type | string | Required | Native field | | variant2.discount.variant1.percentage | number | Optional | Native field | | variant2.discount.variant1.type | PERCENTAGE | Optional | Native field | | variant2.requirements | object | Optional | Native field | | variant2.requirements.newMembersOnly | boolean | Required | Native field | | variant2.subscriptionType | union | Optional | Native field | | variant2.subscriptionType.variant 1 | value | Choose one | Native oneOf | | variant2.subscriptionType.variant1.type | string | Required | Native field | | variant2.subscriptionType.variant1.type | ALL | Optional | Native field | | variant2.subscriptionType.variant 2 | value | Choose one | Native oneOf | | variant2.subscriptionType.variant2.type | string | Required | Native field | | variant2.subscriptionType.variant2.type | ANNUAL | Optional | Native field | | variant2.subscriptionType.variant 3 | value | Choose one | Native oneOf | | variant2.subscriptionType.variant3.type | string | Required | Native field | | variant2.subscriptionType.variant3.type | MONTHLY | Optional | Native field | | variant2.tiers | union | Optional | Native field | | variant2.tiers.variant 1 | value | Choose one | Native oneOf | | variant2.tiers.variant1.type | string | Required | Native field | | variant2.tiers.variant1.type | ALL | Optional | Native field | | variant2.tiers.variant 2 | value | Choose one | Native oneOf | | variant2.tiers.variant2.type | string | Required | Native field | | variant2.tiers.variant2.ids | array | Optional | Native field | | variant2.tiers.variant2.type | SELECTED | Optional | Native field | | variant2.type | MEMBERSHIPS_SINGLE | Optional | Native field | | variant 3 | value | Choose one | Native oneOf | | variant3.type | string | Required | Native field | | variant3.codes | array | Optional | Native field | | variant3.discount | union | Optional | Native field | | variant3.discount.variant 1 | value | Choose one | Native oneOf | | variant3.discount.variant1.type | string | Required | Native field | | variant3.discount.variant1.money | object | Optional | Native field | | variant3.discount.variant1.money.value | number (minimum=0) | Required | Native field | | variant3.discount.variant1.money.currency | string | Required | Native field | | variant3.discount.variant1.freeShipping | boolean | Optional | Native field | | variant3.discount.variant1.type | FLAT_RATE | Optional | Native field | | variant3.discount.variant 2 | value | Choose one | Native oneOf | | variant3.discount.variant2.type | string | Required | Native field | | variant3.discount.variant2.type | FREE_SHIPPING | Optional | Native field | | variant3.discount.variant 3 | value | Choose one | Native oneOf | | variant3.discount.variant3.type | string | Required | Native field | | variant3.discount.variant3.percentage | number | Optional | Native field | | variant3.discount.variant3.shipping | Excluded, Included, FreeLowestOnly, Free | Optional | Native field | | variant3.discount.variant3.type | PERCENTAGE | Optional | Native field | | variant3.requirements | object | Optional | Native field | | variant3.requirements.minimumOrderValue | object | Optional | Native field | | variant3.requirements.minimumOrderValue.value | number (minimum=0) | Required | Native field | | variant3.requirements.minimumOrderValue.currency | string | Required | Native field | | variant3.appliesToProducts | object | Optional | Native field | | variant3.appliesToProducts.productIds | array | Required | Native field | | variant3.appliesToProducts.oncePerOrder | boolean | Optional | Native field | | variant3.limits | object | Optional | Native field | | variant3.limits.maximumUse | integer (format=int32) | Optional | Native field | | variant3.limits.oneUsePerCustomer | boolean | Required | Native field | | variant3.type | SHOP_MULTI | Optional | Native field | | variant 4 | value | Choose one | Native oneOf | | variant4.type | string | Required | Native field | | variant4.code | string | Optional | Native field | | variant4.discount | union | Optional | Native field | | variant4.discount.variant 1 | value | Choose one | Native oneOf | | variant4.discount.variant1.type | string | Required | Native field | | variant4.discount.variant1.money | object | Optional | Native field | | variant4.discount.variant1.money.value | number (minimum=0) | Required | Native field | | variant4.discount.variant1.money.currency | string | Required | Native field | | variant4.discount.variant1.freeShipping | boolean | Optional | Native field | | variant4.discount.variant1.type | FLAT_RATE | Optional | Native field | | variant4.discount.variant 2 | value | Choose one | Native oneOf | | variant4.discount.variant2.type | string | Required | Native field | | variant4.discount.variant2.type | FREE_SHIPPING | Optional | Native field | | variant4.discount.variant 3 | value | Choose one | Native oneOf | | variant4.discount.variant3.type | string | Required | Native field | | variant4.discount.variant3.percentage | number | Optional | Native field | | variant4.discount.variant3.shipping | Excluded, Included, FreeLowestOnly, Free | Optional | Native field | | variant4.discount.variant3.type | PERCENTAGE | Optional | Native field | | variant4.requirements | object | Optional | Native field | | variant4.requirements.minimumOrderValue | object | Optional | Native field | | variant4.requirements.minimumOrderValue.value | number (minimum=0) | Required | Native field | | variant4.requirements.minimumOrderValue.currency | string | Required | Native field | | variant4.appliesToProducts | object | Optional | Native field | | variant4.appliesToProducts.productIds | array | Required | Native field | | variant4.appliesToProducts.oncePerOrder | boolean | Optional | Native field | | variant4.limits | object | Optional | Native field | | variant4.limits.maximumUse | integer (format=int32) | Optional | Native field | | variant4.limits.oneUsePerCustomer | boolean | Required | Native field | | variant4.type | SHOP_SINGLE | Optional | Native field |

list_products

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all products with pagination. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-products. Policy: read.

Native: GET /open-api/v1.0/products. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | page | integer (minimum=0, format=int32, default=0) | Optional | Native page | | size | integer (minimum=1, maximum=100, format=int32, default=20) | Optional | Number of elements per page. The maximum page size is 100 - larger values are capped at 100. | | search | string | Optional | Native search | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. |

create_product

Rate limit: 5 requests / minute per shop. See Rate limiting.

Creates a product from a design or a digital product.

CLI: fourthwall-cli create-product. Policy: explicit confirmation.

Native: POST /open-api/v1.0/products. Current source.

| Argument | Type or constraint | Requirement | Meaning | | --- | --- | --- | --- | | account | string | Optional | Exact private shop profile label; not a provider identity or authorization proof. | | confirm | boolean | Optional | Set true only when the user asked for exactly this action. | | payload | object | Optional | Complete current native JSON body; cannot mix with native body flags or payload_file. | | payload_file | string (minLength=1) | Optional | Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags. |

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Fourthwall MCP Server & CLI

Two ways to use it

Command line

MCP server, for your AI app

Which one

Features

Contents

1. What you can ask it

2. Set up your account

Settings

3. Install

4. Output and exit codes

5. Which surface and what each costs

6. Tools

get_webhook

update_webhook

delete_webhook

start_streaming

end_streaming

get_public_token

get_promotion

update_promotion

update_product_state

toggle_product_availability

mark_download_complete

finish_giveaway

create_giveaway_checkout

disable_giveaway_checkout

finish_giveaway_draw

get_gifting_config

update_gifting_config

update_collection

get_collection_products

update_collection_products

update_collection_availability

list_webhooks

create_webhook

list_promotions

create_promotion

list_products

create_product