> ## Documentation Index > Fetch the complete documentation index at: https://widgetic.com/llms.txt > Use this file to discover all available pages before exploring further. # widgetic mcp > 48 commands for the tools of the MCP server, generated from its tool contract. `widgetic mcp ` calls one tool of the Widgetic MCP server (tool contract 1.22.0). It has 48 commands, in four groups by what the key must be allowed to do. Every command also takes [the flags every command takes](https://widgetic.com/docs/cli/commands/index.md). A build tool sends `publish: false` unless `--publish` is passed, so what the CLI builds stays a draft. ## Read (23) ### `widgetic mcp get-ab-test` Get an A/B test Use this when the user wants to see how one A/B test is set up or how it is doing, or before changing or stopping it. It returns the goal, the versions with their share of traffic, the settings, the results so far (visitors, how many reached the goal, each version's rate and its lift over the control) with a recommendation, the winner once there is one, and the embed code. Visitors see the versions only while the test is running. It uses no credits. Do not use it to list tests (list\_ab\_tests) or to change one (save\_ab\_test, set\_ab\_test\_state). * Tool: `get_ab_test` (`widgetic mcp call get_ab_test` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--ab-test-id ` | uuid | yes | The ab\_test\_id returned by list\_ab\_tests, save\_ab\_test or get\_ab\_test. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp get-ab-test`. ### `widgetic mcp get-ab-test-options` Get A/B test options Use this when the user wants to set up an A/B test and needs to know which goals a test can be judged on and which of their published widgets can be a version. Each goal says whether it is counted automatically or only when the widget reports it, and each widget lists the goals it reports by itself. Pass composition\_ids to look up particular widgets, or query to search by name; widgets come newest first, up to 20 at a time, with next\_cursor for more. It uses no credits. Do not use it to see the tests that exist (list\_ab\_tests) or to make one (save\_ab\_test). * Tool: `get_ab_test_options` (`widgetic mcp call get_ab_test_options` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--composition-ids ` | list (repeat the flag) | | Look up only these widgets. At most 10. | | `--cursor ` | text | | Opaque cursor: the next\_cursor of the previous page. Leave out for the first page. | | `--limit ` | integer | | How many widgets to return, 1 to 20. Defaults to 10. (default: 10) | | `--query ` | text | | Words the widget name contains, for example "hero". | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp get-ab-test-options`. ### `widgetic mcp get-account-usage` Get account usage Use this when the user asks how many credits they have left, how much storage is used, how many widgets they have, or whether their account can publish and is serving embeds right now. It reads the account's current state, changes nothing and uses no credits. A figure that cannot be read at the moment is null; null does not mean zero. Do not use it to follow a build (get\_widget) or to list widgets (list\_widgets). * Tool: `get_account_usage` (`widgetic mcp call get_account_usage` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. | The whole description and the schemas: `widgetic schema mcp get-account-usage`. ### `widgetic mcp get-brand-kit` Get the Brand Kit Use this when the user asks what their Brand Kit holds, or before changing it (update\_brand\_kit): the colors, the font of each role, the corner radius, the style notes and the names of the icons the account uploaded, which every widget the account builds in its own workspace starts from. It reads the connected account's own Brand Kit, never a team's (a widget made in a team uses the team's kit, which is on widgetic.com), changes nothing and uses no credits. When the account has saved none it returns Widgetic's default look and says so (is\_default). * Tool: `get_brand_kit` (`widgetic mcp call get_brand_kit` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. | The whole description and the schemas: `widgetic schema mcp get-brand-kit`. ### `widgetic mcp get-embed-code` Get embed code Use this when the user wants the code or link to put a published widget on a website: plain HTML, an iframe, or a React, Vue, Svelte or Angular component, at a fixed size or fully responsive. It returns the code and a share link. If embeds are not being served right now because of the account's state, serving\_status says so and note explains: relay it as written. It uses no credits. Do not use it for a widget that has not been published. * Tool: `get_embed_code` (`widgetic mcp call get_embed_code` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--composition-id ` | uuid | yes | The composition\_id returned by publish\_widget, get\_widget or duplicate\_composition. A widget has one only after it was published. | | `--format ` | one of `html`, `iframe`, `react`, `vue`, `svelte`, `angular` | | html (a script snippet), iframe, or the framework component to generate. (default: html) | | `--height ` | integer | | Height in pixels. | | `--responsive` | switch | | True to fill the available width of the page; false to use width and height as given. (default: true) --no-responsive turns it off. | | `--width ` | integer | | Width in pixels. Used when responsive is false. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp get-embed-code`. ### `widgetic mcp get-profile` Get Widgetic account Use this when you need to know which Widgetic account is connected, for example to tell the user whose widgets will be created or to confirm the connection works. Returns the profile represented by this request's credentials: an opaque id that stays the same for the account across reconnects, plus name, email and nickname when available. It also says which workspace the connection works in right now (the user's own, or a team's), which is where new widgets and workflow, A/B test and translation changes land. Do not use it to look up anyone else's account. * Tool: `get_profile` (`widgetic mcp call get_profile` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. | The whole description and the schemas: `widgetic schema mcp get-profile`. ### `widgetic mcp get-translation` Get a translation Use this when the user wants to see one translation: its state, the original language, and for each language whether its copy is ready, still being translated or failed, with the widget of each copy. It also lists the languages being added right now, and returns the embed code, which shows visitors their own language only while the translation is active. It uses no credits. Do not use it to list translations (list\_translations) or to change one (add\_translation\_languages, set\_translation\_state). * Tool: `get_translation` (`widgetic mcp call get_translation` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--translation-id ` | uuid | yes | The translation\_id returned by list\_translations, create\_translation or get\_translation. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp get-translation`. ### `widgetic mcp get-translation-options` Get translation options Use this when the user wants to translate a widget and needs to know which languages are available and how many a translation may hold. Each language has its code, its English and native name, its region and whether it is one most translations start with; the limits say how many languages one call translates and how many a translation holds in all. It uses no credits. Do not use it to see the translations that exist (list\_translations) or to make one (create\_translation). * Tool: `get_translation_options` (`widgetic mcp call get_translation_options` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. | The whole description and the schemas: `widgetic schema mcp get-translation-options`. ### `widgetic mcp get-widget` Get widget status Use this when you need the current state of one widget: whether it is still being built, how far along it is, whether the draft is ready or failed, the link to its preview, and whether it has been published and is being served. For a published widget it also lists its compositions (the embeddable copies) with their composition\_id. After create\_widget or revise\_widget, call it every 5 to 10 seconds until phase is "ready", "failed" or "cancelled". It uses no credits. Do not use it to list several widgets (list\_widgets) or to show the user a preview card (show\_widget). * Tool: `get_widget` (`widgetic mcp call get_widget` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--widget-id ` | uuid | yes | The widget\_id returned by create\_widget, list\_widgets or get\_widget. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp get-widget`. ### `widgetic mcp get-widget-customization-options` Get customization options Use this when the user wants to change a widget's text, images, list items, colors, fonts or sizes without rebuilding it. It lists every content field, list and design control with its current value and limits. Call it before update\_widget\_customization so you only use keys that exist. It uses no credits. Give widget\_id (a draft or a published widget) or composition\_id (one published copy), not both. A draft shows the values saved on it; one that is still being built has no options yet. Do not use it to see the widget itself (show\_widget) or to get embed code (get\_embed\_code). * Tool: `get_widget_customization_options` (`widgetic mcp call get_widget_customization_options` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--composition-id ` | uuid | | One published copy of a widget. Give this or widget\_id, not both. | | `--widget-id ` | uuid | | The widget whose options to read, a draft or a published one. Give this or composition\_id, not both. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp get-widget-customization-options`. ### `widgetic mcp get-widget-data` Get widget data Use this when the user wants the results of a published widget: how many votes each option got, how many people said yes to an RSVP, or what visitors wrote. It counts the entries of one table (call list\_widget\_data first for the table and column names). Pass group\_by to get a tally, for example the number of entries per choice, largest first. Entries themselves come back only when include\_rows is true, newest first, up to 25. Ask for them only when the user wants to read what visitors wrote; a count or a tally does not need them. * Tool: `get_widget_data` (`widgetic mcp call get_widget_data` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--composition-id ` | uuid | yes | The composition\_id returned by publish\_widget, get\_widget or duplicate\_composition. A widget has one only after it was published. | | `--group-by ` | text | | Count entries per value of this column, for example the column holding the chosen option. Leave out for a plain count. | | `--include-rows` | switch | | True to also return the entries themselves; leave false for counts only. (default: false) | | `--limit ` | integer | | How many entries to return when include\_rows is true, 1 to 25. Defaults to 10. (default: 10) | | `--table ` | text | yes | A table name exactly as list\_widget\_data returned it, for example "votes". | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp get-widget-data`. ### `widgetic mcp get-workflow` Get a workflow Use this when the user wants to see how one workflow is built, or before changing it. It returns the workflow as a script (the start step, the steps and the moves between them, with the rules that choose the next step) in exactly the shape save\_workflow takes, with its state, its revision, any problems and the names of its widgets. For a published workflow it also returns the embed code and the snippet for events from the page; pass include\_stats for how many visitors reached each step in the last 30 days. * Tool: `get_workflow` (`widgetic mcp call get_workflow` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--include-stats` | switch | | True to include how many visitors reached each step of the live version in the last 30 days. Defaults to false. (default: false) | | `--workflow-id ` | uuid | yes | The workflow\_id returned by list\_workflows, save\_workflow or get\_workflow. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp get-workflow`. ### `widgetic mcp get-workflow-options` Get workflow options Use this when the user wants to build or change a workflow and needs to know which of their published widgets it can use, and what a visitor can do on each one. Each entry has the composition\_id to use as a step, whether its widget is published, the tables visitors can add entries to with the columns a rule may read, and the actions the widget reports, such as a click. A move can wait only for what is listed here. Pass composition\_ids to look up particular compositions, or query to search by name; entries come newest first, up to 20 at a time, with next\_cursor for more. It uses no credits. * Tool: `get_workflow_options` (`widgetic mcp call get_workflow_options` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--composition-ids ` | list (repeat the flag) | | Look up only these compositions. At most 10. | | `--cursor ` | text | | Opaque cursor: the next\_cursor of the previous page. Leave out for the first page. | | `--limit ` | integer | | How many compositions to return, 1 to 20. Defaults to 10. (default: 10) | | `--query ` | text | | Words the composition name contains, for example "quiz". | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp get-workflow-options`. ### `widgetic mcp list-ab-tests` List A/B tests Use this when the user wants to see their A/B tests: experiments that split visitors between two to four widgets and measure which does better. Each entry has its name, its state (draft, running, paused, completed or graduated), the goal, how many versions it has and how many days ago it started. It lists the workspace the person is signed in to on widgetic.com, newest first, up to 20 at a time; pass next\_cursor back for more. It uses no credits. Do not use it to see the results of one test (get\_ab\_test), to see what a test can use (get\_ab\_test\_options) or to list widgets (list\_widgets). * Tool: `list_ab_tests` (`widgetic mcp call list_ab_tests` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--cursor ` | text | | Opaque cursor: the next\_cursor of the previous page. Leave out for the first page. | | `--limit ` | integer | | How many tests to return, 1 to 20. Defaults to 10. (default: 10) | | `--query ` | text | | Words the test name contains, for example "headline". | | `--state ` | one of `all`, `draft`, `running`, `paused`, `completed`, `graduated` | | Which tests to list: all (the default) or only those in one state. (default: all) | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp list-ab-tests`. ### `widgetic mcp list-media-library` List media library Use this when the user wants to browse or find files already saved in their Widgetic media library, or when you need a media\_id for create\_widget, revise\_widget, update\_widget\_customization, manage\_media\_library or delete\_media\_file. It shows thumbnails as a carousel, filtered by folder, kind or name; pass next\_cursor back to see more. A file that widgets were given says which in used\_in (recorded since Widgetic began keeping track, so a file without it may still be in use). It uses no credits. Do not use it to save new files (save\_to\_media\_library) or to list widgets (list\_widgets). * Tool: `list_media_library` (`widgetic mcp call list_media_library` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--cursor ` | text | | Opaque cursor: the next\_cursor of the previous page. Leave out for the first page. | | `--folder ` | text | | Media library folder name, for example "Assets". Matched by name. | | `--kind ` | one of `image`, `video`, `audio`, `document`, `data` | | Only files of this kind. | | `--limit ` | integer | | How many items to return, 1 to 8. Defaults to 6. (default: 6) | | `--query ` | text | | Words the file name contains, for example "logo". | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp list-media-library`. ### `widgetic mcp list-translations` List translations Use this when the user wants to see their translations: a widget made available in several languages on one embed, each language its own copy. Each entry has its name, its state (making, ready, active, paused or unfinished), the original language, the languages it holds and the widget it was made from. It lists the workspace the person is signed in to on widgetic.com, newest first, up to 20 at a time; pass next\_cursor back for more. It uses no credits. Do not use it to see one translation in full (get\_translation) or to list widgets (list\_widgets). * Tool: `list_translations` (`widgetic mcp call list_translations` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--cursor ` | text | | Opaque cursor: the next\_cursor of the previous page. Leave out for the first page. | | `--limit ` | integer | | How many translations to return, 1 to 20. Defaults to 10. (default: 10) | | `--query ` | text | | Words the translation name contains, for example "spring". | | `--state ` | one of `all`, `making`, `ready`, `active`, `paused`, `unfinished` | | Which translations to list: all (the default) or only those in one state. (default: all) | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp list-translations`. ### `widgetic mcp list-widget-data` List widget data Use this when the user asks what visitors have sent in through a published widget: votes, RSVPs, form entries, comments or ratings. It shows which tables of entries the widget keeps, their columns and how many entries each holds, so you know what to ask get\_widget\_data for. A widget that keeps no entries answers with has\_data false. It reads one published widget of the connected account, changes nothing and uses no credits. Do not use it for how many people viewed the widget, to change or delete an entry, or for a widget that was never published. * Tool: `list_widget_data` (`widgetic mcp call list_widget_data` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--composition-id ` | uuid | yes | The composition\_id returned by publish\_widget, get\_widget or duplicate\_composition. A widget has one only after it was published. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp list-widget-data`. ### `widgetic mcp list-widget-versions` List widget versions Use this when the user wants to see the versions a widget has been through, find out which one is live, or go back to an earlier one. Each version has a number, a short title when it has one, whether it was ever published and whether it is the live one. They come newest first, up to 20 at a time; pass next\_cursor back for older ones. To make an earlier version live again, pass its number to publish\_widget. It uses no credits. Do not use it to list several widgets (list\_widgets) or to follow a build in progress (get\_widget). * Tool: `list_widget_versions` (`widgetic mcp call list_widget_versions` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--cursor ` | text | | Opaque cursor: the next\_cursor of the previous page. Leave out for the first page. | | `--limit ` | integer | | How many versions to return, 1 to 20. Defaults to 10. (default: 10) | | `--widget-id ` | uuid | yes | The widget\_id returned by create\_widget, list\_widgets or get\_widget. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp list-widget-versions`. ### `widgetic mcp list-widgets` List widgets Use this when the user wants to see, find or pick one of their widgets: all of them, only drafts, only published ones, or those whose name contains some words. It shows up to 8 at a time as a carousel; pass next\_cursor back to see more. It uses no credits. Do not use it to follow the progress of one widget (get\_widget) or to look at media files (list\_media\_library). * Tool: `list_widgets` (`widgetic mcp call list_widgets` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--cursor ` | text | | Opaque cursor: the next\_cursor of the previous page. Leave out for the first page. | | `--filter ` | one of `all`, `drafts`, `published` | | all, only drafts that were never published, or only published widgets. (default: all) | | `--limit ` | integer | | How many items to return, 1 to 8. Defaults to 6. (default: 6) | | `--query ` | text | | Words the widget name contains, for example "countdown". | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp list-widgets`. ### `widgetic mcp list-workflows` List workflows Use this when the user wants to see their workflows: the chains of published widgets that take a visitor from one widget to the next on a single embed. Each entry has its name, its state (draft, live, paused or archived), whether the saved draft has changes visitors do not have yet, how many widgets it shows and how many visitors started it. It lists the workspace the person is signed in to on widgetic.com, newest first, up to 20 at a time; pass next\_cursor back for more. It uses no credits. * Tool: `list_workflows` (`widgetic mcp call list_workflows` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--cursor ` | text | | Opaque cursor: the next\_cursor of the previous page. Leave out for the first page. | | `--limit ` | integer | | How many workflows to return, 1 to 20. Defaults to 10. (default: 10) | | `--query ` | text | | Words the workflow name contains, for example "onboarding". | | `--state ` | one of `in_use`, `all`, `draft`, `live`, `paused`, `archived` | | Which workflows to list: in\_use (the default: draft, live and paused), all (archived too), or one state. (default: in\_use) | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp list-workflows`. ### `widgetic mcp show-widget` Show a widget Use this when you want to show the user a widget as a card: build progress while it is generating, then the live preview with actions to revise, publish, customize or copy the embed code. Call it right after create\_widget, replicate\_widget or revise\_widget so the user can watch the build, and again whenever the user asks to see the widget. In clients that cannot display cards it returns the same state as text. It uses no credits. Do not use it to wait for a build silently (get\_widget) or to show several widgets (list\_widgets). * Tool: `show_widget` (`widgetic mcp call show_widget` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--widget-id ` | uuid | yes | The widget\_id returned by create\_widget, list\_widgets or get\_widget. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp show-widget`. ### `widgetic mcp suggest-widgets` Suggest widgets to build Use this when the user says what they want to make or do (a landing page, a course, an event, a workflow) and wants to know which widgets would fit, before anything is built. It answers with the widgets worth building, each with a title, what visitors would see and a brief that create\_widget\_batch can build as written, and, where some of them work as a journey a visitor goes through step by step, the workflows they make (what each does, which widgets in order). If the goal is too open it asks up to three questions first: put them to the user, then call again with their answers in details. * Tool: `suggest_widgets` (`widgetic mcp call suggest_widgets` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--details ` | text | | The user's answers to the questions an earlier call asked, with anything else they said about it (who it is for, the content they have, the look they want). | | `--goal ` | text | yes | What the user wants to make or do, in their own words, for example "a landing page for my basketball team" or "a workflow that welcomes new members and collects their details". | | `--max-suggestions ` | integer | | The most widgets to suggest, 1 to 12. Defaults to 9. The widgets of a workflow count, so ask for more when the user wants several workflows. (default: 9) | | `--purpose ` | one of `page`, `workflow` | | workflow when the user describes steps a visitor goes through one after another, page when they describe one web page or site made of parts seen together. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp suggest-widgets`. ### `widgetic mcp test-workflow` Test a workflow Use this when the user wants to check how a workflow behaves before it goes live: it plays visitor events, one after another, through the workflow and says where the visitor ends up and why. Give either workflow\_id (the saved draft) or script (one you have not saved), and the events: an entry added to a table with its values, an action the widget reports, an event from the page, or a wait that is over. It plays up to 20 events. Nothing is saved, no visitor is moved and no entry is created. It uses no credits. Do not use it to publish (publish\_workflow) or to change a workflow (save\_workflow). * Tool: `test_workflow` (`widgetic mcp call test_workflow` runs it by that name) * Permission: `widgetic.read` * It only reads. | Flag | Takes | Required | What it does | | - | - | - | - | | `--workflow-id ` | uuid | | Play through the saved draft of this workflow. Give this or script, not both. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. `events`, `script` can only be given this way. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp test-workflow`. ## Write (20) ### `widgetic mcp add-translation-languages` Add translation languages Use this when the user wants more languages in a translation they already made, or wants a language that failed to be tried again: it translates the original widget into each language you name and adds the copies. The widget's text is sent to a language model to be translated, so tell the user that before you call. A call takes one to 5 languages and a translation holds 20 in all; a language that is already there and ready is skipped. It waits for under a minute and then answers even if some languages are still being translated: check them with get\_translation. * Tool: `add_translation_languages` (`widgetic mcp call add_translation_languages` runs it by that name) * Permission: `widgetic.write` * It changes something; safe to repeat. | Flag | Takes | Required | What it does | | - | - | - | - | | `--expected-workspace ` | text | | The workspace the user means: "personal" for their own, or the team's name as get\_profile shows it. If this connection works in another one, nothing is changed and the answer says where. | | `--languages ` | one of `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `pl`, `sv`, `da`, `bg`, `hr`, `cs`, `et`, `fi`, `el`, `hu`, `ga`, `lv`, `lt`, `mt`, `ro`, `sk`, `sl`, `ru`, `no`, `zh`, `ja`, `ko`, `hi`, `ar`, `tr` | yes | The languages to add, as codes from get\_translation\_options: one to 5. A language that failed is named here to try it again. | | `--translation-id ` | uuid | yes | The translation\_id returned by list\_translations, create\_translation or get\_translation. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp add-translation-languages`. ### `widgetic mcp cancel-widget-batch` Cancel several widget builds Use this when the user wants to stop the builds of several widgets at once, such as a create\_widget\_batch they have changed their mind about: pass the widget\_ids that call returned. A build still waiting to start is stopped and its credit is returned. One being written is stopped too, but its credit is returned only if the model had not begun to write, so tell the user which. It answers for every id: cancelled, already\_finished (nothing was running: it was built, had failed or was already stopped) or not\_found. One id never stops the others, and it uses no credits itself. * Tool: `cancel_widget_batch` (`widgetic mcp call cancel_widget_batch` runs it by that name) * Permission: `widgetic.write` * It changes something; can delete or stop something; safe to repeat. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--widget-ids ` | list (repeat the flag) | yes | The widget\_ids of the builds to stop: the ones create\_widget\_batch returned, or the ones from list\_widgets that are still building. At most 25. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp cancel-widget-batch`. ### `widgetic mcp cancel-widget-creation` Cancel a widget build Use this when the user wants to cancel a widget that is still being built (phase "queued" or "generating"). It marks the build cancelled. A build that had not started has its credit returned; one being written has it returned only if the model had not begun to write, and may still finish and leave a draft. It has no effect on a widget whose draft is ready or that is published, and the result says so. Do not use it to delete a widget or to undo a published version. * Tool: `cancel_widget_creation` (`widgetic mcp call cancel_widget_creation` runs it by that name) * Permission: `widgetic.write` * It changes something; can delete or stop something; safe to repeat. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--widget-id ` | uuid | yes | The widget\_id returned by create\_widget, list\_widgets or get\_widget. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp cancel-widget-creation`. ### `widgetic mcp create-translation` Create a translation Use this when the user wants a widget translated into other languages: it makes a copy of the widget for each language you name and groups them as one translation. Give the language the widget is written in now and the languages to translate into (one to 5); the original is kept as it is. The widget's text is sent to a language model to be translated, so tell the user that before you call. It waits for under a minute and then answers even if some languages are still being translated: check them with get\_translation, and add more later with add\_translation\_languages. * Tool: `create_translation` (`widgetic mcp call create_translation` runs it by that name) * Permission: `widgetic.write` * It changes something. | Flag | Takes | Required | What it does | | - | - | - | - | | `--composition-id ` | uuid | yes | The widget to translate: a composition\_id from get\_widget or list\_widgets. It must be one the person made themselves. | | `--description ` | text | | What the translation is for, in a sentence. | | `--expected-workspace ` | text | | The workspace the user means: "personal" for their own, or the team's name as get\_profile shows it. If this connection works in another one, nothing is changed and the answer says where. | | `--languages ` | one of `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `pl`, `sv`, `da`, `bg`, `hr`, `cs`, `et`, `fi`, `el`, `hu`, `ga`, `lv`, `lt`, `mt`, `ro`, `sk`, `sl`, `ru`, `no`, `zh`, `ja`, `ko`, `hi`, `ar`, `tr` | yes | The languages to translate into, as codes from get\_translation\_options: one to 5. Leave the original language out. | | `--name ` | text | yes | The translation name, for example "Spring sale in four languages". | | `--original-language ` | one of `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `pl`, `sv`, `da`, `bg`, `hr`, `cs`, `et`, `fi`, `el`, `hu`, `ga`, `lv`, `lt`, `mt`, `ro`, `sk`, `sl`, `ru`, `no`, `zh`, `ja`, `ko`, `hi`, `ar`, `tr` | yes | The language the widget is written in now, as a code from get\_translation\_options, for example en. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp create-translation`. ### `widgetic mcp create-widget` Create a widget Use this when the user wants a new interactive widget built from a description: a quiz, countdown, gallery, timeline, FAQ, chart, calculator, list, carousel or similar, to preview and embed on a website. It starts the build and returns at once with a widget\_id; call show\_widget right away so the user watches it, and poll get\_widget until phase is "ready" (usually a few minutes). * Tool: `create_widget` (`widgetic mcp call create_widget` runs it by that name) * Permission: `widgetic.write` * It changes something. | Flag | Takes | Required | What it does | | - | - | - | - | | `--brief ` | text | yes | What the widget should do and show, in the user's terms, for example "A countdown to 14 March 2027, 9:00, with a Register now button". A Figma link the user pasted goes in figma\_links. | | `--content-summary ` | text | | Only when the widget is built from the conversation (a timeline or quiz about what was discussed, for example): the facts, questions or items the widget must contain, written by you. | | `--expected-workspace ` | text | | The workspace the user means: "personal" for their own, or the team's name as get\_profile shows it. If this connection works in another one, nothing is changed and the answer says where. | | `--figma-links ` | list (repeat the flag) | | Figma links the user pasted ("Copy link to selection" on a frame or a selection in Figma, up to 3), exactly as pasted. Each is read with the user's own connected Figma account and the widget replicates that design. | | `--figma-structure ` | list (repeat the flag) | | Layer data of the Figma frame a designer selected in the Widgetic Figma plugin, which fills this in itself: the JSON text of one frame per item, up to 3. | | `--media-ids ` | list (repeat the flag) | | Images already in the media library that the widget should use. | | `--project-name ` | text | | Optional. A project on widgetic.com to put this widget in, for example "Spring campaign": made in the workspace this connection works in if there is none with that name, reused if there is. | | `--publish` | switch | | True (the default) publishes the widget as soon as it is built, so it comes back with a composition\_id the user can customize and embed. Pass false only if the user wants to keep it a draft. In this CLI it is false unless you pass --publish. | | `--style ` | text | | Look and feel, for example "minimal, dark, rounded corners" or "use the brand colors #1a73e8 and white". | | `--title ` | text | yes | Short name for the widget, shown in the user's library, for example "Product launch countdown". | | `--type-hint ` | text | | The kind of widget, if the user named one, for example "quiz", "countdown", "gallery", "timeline", "chart" or "calculator". | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. `files` can only be given this way. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp create-widget`. ### `widgetic mcp create-widget-batch` Create several widgets Use this when the user has agreed to build several widgets at once, such as the ones suggest\_widgets proposed: up to 25 in one call, each its own widget and canvas. Each widget uses 1 credit, charged when its build starts, so tell the user the total and get a yes first. max\_credits is the most they agreed to: nothing is started if the new widgets would cost more. It returns at once; follow each widget with get\_widget until its phase is "ready". A built widget is published unless publish is false. * Tool: `create_widget_batch` (`widgetic mcp call create_widget_batch` runs it by that name) * Permission: `widgetic.write` * It changes something. | Flag | Takes | Required | What it does | | - | - | - | - | | `--expected-workspace ` | text | | The workspace the user means: "personal" for their own, or the team's name as get\_profile shows it. If this connection works in another one, nothing is changed and the answer says where. | | `--max-credits ` | integer | yes | The most credits the user agreed to spend on this call: 1 credit for each widget they said yes to. If the widgets that are new would cost more, nothing is started. | | `--project-name ` | text | | Optional. A project on widgetic.com to put all of these widgets in, for example "Basketball team site": made if the user has none with that name, reused if they have. | | `--publish` | switch | | True (the default) publishes each widget as soon as it is built, so it comes back with a composition\_id the user can customize and embed. Pass false only if the user wants drafts. In this CLI it is false unless you pass --publish. | | `--workflow-name ` | text | | Optional. Only when the widgets are the steps of one workflow the user asked for: the name of a draft workflow Widgetic saves by itself, with these widgets as its steps in the order sent, once every one of them is built… | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. `widgets` can only be given this way. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp create-widget-batch`. ### `widgetic mcp draft-workflow-from-widgets` Draft a workflow from widgets Use this when the user wants widgets they have built, such as the ones a create\_widget\_batch made for a workflow, chained into one workflow: pass the widget\_ids in the order visitors should meet them, and a name. It saves a draft with one step for each widget, in that order. A step leads on when its widget keeps entries (a visitor sends one) or reports an action (a click, a choice). A step whose widget offers neither is saved with no way on and the answer says which, so ask the user what should take visitors on and set it with save\_workflow. * Tool: `draft_workflow_from_widgets` (`widgetic mcp call draft_workflow_from_widgets` runs it by that name) * Permission: `widgetic.write` * It changes something. | Flag | Takes | Required | What it does | | - | - | - | - | | `--expected-workspace ` | text | | The workspace the user means: "personal" for their own, or the team's name as get\_profile shows it. If this connection works in another one, nothing is changed and the answer says where. | | `--name ` | text | yes | The name of the new draft workflow. | | `--widget-ids ` | list (repeat the flag) | yes | The widget\_ids of the widgets to chain, in the order visitors should meet them: the first is where a visitor starts. Each once, at most 25. Every one must be built and published. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp draft-workflow-from-widgets`. ### `widgetic mcp duplicate-composition` Copy a published widget Use this when the user wants a second embed of a published widget that starts as an exact copy, for example the same widget on another page with different texts or colors. The copy has the same content, design and embed settings as the source and gets its own composition\_id and embed code; change it afterwards with update\_widget\_customization. A widget can have up to 10 compositions in all. It uses no credits and does not rebuild or republish anything. Do not use it to make a new widget (create\_widget), to publish a draft (publish\_widget) or to change the original. * Tool: `duplicate_composition` (`widgetic mcp call duplicate_composition` runs it by that name) * Permission: `widgetic.write` * It changes something. | Flag | Takes | Required | What it does | | - | - | - | - | | `--composition-id ` | uuid | yes | The composition\_id returned by publish\_widget, get\_widget or duplicate\_composition. A widget has one only after it was published. | | `--name ` | text | | Name for the copy, shown in the user's library. Defaults to "Copy of" followed by the name of the original. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp duplicate-composition`. ### `widgetic mcp manage-media-library` Rename or move media files Use this when the user wants to rename files in their Widgetic media library or move them to another folder, for example to tidy what save\_to\_media\_library stored. Send up to 20 changes, each with a media\_id from list\_media\_library and a new name, a new folder or both. A name keeps the file's extension, so send it without one. Widgets already built are not affected: they load the file from its address, which does not change. The result shows each file as it is now and as it was, and lists the changes that could not be made with the reason; the others are still made. It uses no credits. * Tool: `manage_media_library` (`widgetic mcp call manage_media_library` runs it by that name) * Permission: `widgetic.write` * It changes something; safe to repeat. | Flag | Takes | Required | What it does | | - | - | - | - | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. `changes` can only be given this way. | The whole description and the schemas: `widgetic schema mcp manage-media-library`. ### `widgetic mcp rename-widget` Rename a widget Use this when the user wants to give a widget a different name, for example to tell several widgets apart. It changes the widget title only: its published copies keep their names, nothing is rebuilt, embeds are not affected and it uses no credits. The result returns the previous title. Do not use it to change what the widget shows (update\_widget\_customization) or what it does (revise\_widget). * Tool: `rename_widget` (`widgetic mcp call rename_widget` runs it by that name) * Permission: `widgetic.write` * It changes something; safe to repeat. | Flag | Takes | Required | What it does | | - | - | - | - | | `--title ` | text | yes | The new name for the widget, for example "Product launch countdown". | | `--widget-id ` | uuid | yes | The widget\_id returned by create\_widget, list\_widgets or get\_widget. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp rename-widget`. ### `widgetic mcp replicate-widget` Replicate a widget Use this when the user pastes a Widgetic widget link (it ends in a code that starts with wgc\_), made by the Widgetic browser extension from an element on a web page. The link names a copy Widgetic keeps for a day: pass it as written and do not open the page. The copy is the replica. The model does not run, nothing is built, and no credits are used. Do not call show\_widget or get\_widget for the result, and do not start a build. A link that has expired is refused. A change the user asked for is not made: the copy is offered as it was captured. * Tool: `replicate_widget` (`widgetic mcp call replicate_widget` runs it by that name) * Permission: `widgetic.write` * It changes something. | Flag | Takes | Required | What it does | | - | - | - | - | | `--capture-code ` | text | yes | The widget link the user pasted, exactly as written (it ends in a code that starts with wgc\_), or just that code. Never the address of a web page. | | `--instructions ` | text | | Only when the user wants the copy changed, in their words, for example "make it dark" or "translate it to French". Leave it out for a faithful replica. | | `--publish` | switch | | Ignored. The copy is offered as it was captured, and nothing is published. In this CLI it is false unless you pass --publish. | | `--title ` | text | | Short name for the widget, shown in the user's library, for example "Pricing table". Leave it out for a generic name. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp replicate-widget`. ### `widgetic mcp revise-widget` Revise a widget Use this when the user wants to change what a widget does or how it is laid out in ways that need new code (new features, a different layout, another visual style), based on their feedback. It starts a new build from the latest draft and returns at once; call show\_widget right after so the user watches it, and poll get\_widget until phase is "ready". Each call uses 1 credit, charged up front. * Tool: `revise_widget` (`widgetic mcp call revise_widget` runs it by that name) * Permission: `widgetic.write` * It changes something; can delete or stop something. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--feedback ` | text | yes | What to change, as the user put it, for example "make the numbers bigger and add a dark mode". A Figma link the user pasted goes in figma\_links. | | `--figma-links ` | list (repeat the flag) | | Figma links the user pasted for this change ("Copy link to selection", up to 3), exactly as pasted. Each is read with the user's own connected Figma account and the revision is built to match that design. | | `--media-ids ` | list (repeat the flag) | | Images already in the media library to use for this change. | | `--publish` | switch | | True (the default) publishes the revision as soon as it is built, so every composition of the widget shows it. Pass false only if the user wants to try the change without touching what live embeds show. In this CLI it is false unless you pass --publish. | | `--widget-id ` | uuid | yes | The widget\_id returned by create\_widget, list\_widgets or get\_widget. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. `files` can only be given this way. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp revise-widget`. ### `widgetic mcp save-ab-test` Save an A/B test Use this when the user wants to create an A/B test or change a draft one. Without ab\_test\_id it makes a new draft: name, goal and 2 to 4 versions (each a published widget, by composition\_id) are required; leave out the traffic shares for an even split. With ab\_test\_id it changes a draft's name, description, goal or settings; the versions of a saved test cannot be changed, and a test that has started cannot be edited here. Saving shows nothing to visitors: a test starts only with set\_ab\_test\_state. Check the goals and the widgets with get\_ab\_test\_options first. It uses no credits. * Tool: `save_ab_test` (`widgetic mcp call save_ab_test` runs it by that name) * Permission: `widgetic.write` * It changes something; can delete or stop something. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--ab-test-id ` | uuid | | The draft to change. Leave out to make a new test. | | `--auto-graduate` | switch | | True to let the test stop by itself and record the version that clearly won; its tag then shows nothing until the winner's own embed code replaces it. Defaults to false. | | `--confidence-percent ` | number | | How sure the results must be before a version counts as better, in percent, 80 to 99.9. Defaults to 95. | | `--description ` | text | | What the test is about, in a sentence. Send an empty text to clear it. | | `--expected-workspace ` | text | | The workspace the user means: "personal" for their own, or the team's name as get\_profile shows it. If this connection works in another one, nothing is changed and the answer says where. | | `--goal ` | one of `clicks`, `conversions`, `plays`, `submissions`, `signups`, `purchases`, `downloads` | | What counts as success: one goal id from get\_ab\_test\_options, for example clicks. Required for a new test; a draft can change it. | | `--min-sample-size ` | integer | | The fewest visitors, across the versions, before the results are judged, 50 to 1000000. Defaults to 1000. | | `--name ` | text | | The test name. Required for a new test; with ab\_test\_id it renames. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. `versions` can only be given this way. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp save-ab-test`. ### `widgetic mcp save-to-media-library` Save to media library Use this when the user wants images (PNG, JPEG, WebP, GIF, HEIC or SVG), videos (MP4, WebM or MOV), audio (MP3, WAV, OGG or M4A), PDF documents or data files (CSV, JSON or Excel XLSX) they provided (attached files or links) kept in their Widgetic media library so widgets can use them. Each file is fetched (HTTPS links only, no redirects, up to 250 MB each; SVG up to 2 MB; JSON and Excel files up to 10 MB), filed under the folder name you give (default "Assets") and returned with a media\_id. It counts against the account's storage allowance. * Tool: `save_to_media_library` (`widgetic mcp call save_to_media_library` runs it by that name) * Permission: `widgetic.write` * It changes something. | Flag | Takes | Required | What it does | | - | - | - | - | | `--file-urls ` | list (repeat the flag) | | HTTPS links to files the user asked to save. Send files, file\_urls or both. | | `--folder ` | text | | Media library folder name, for example "Assets". Matched by name. (default: Assets) | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. `files` can only be given this way. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp save-to-media-library`. ### `widgetic mcp save-workflow` Save a workflow Use this when the user wants to create a workflow or change one: it saves the script as the draft. Without workflow\_id it makes a new workflow (name is then required). With workflow\_id it replaces the draft script, or only the name when you send no script, starting from the revision you read; if the draft changed since, nothing is saved and you are told to read it again. The script is the start step, the steps (published compositions) and the moves between them; the answer lists any problems in plain words, and nothing reaches visitors until publish\_workflow. * Tool: `save_workflow` (`widgetic mcp call save_workflow` runs it by that name) * Permission: `widgetic.write` * It changes something; can delete or stop something. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--expected-workspace ` | text | | The workspace the user means: "personal" for their own, or the team's name as get\_profile shows it. If this connection works in another one, nothing is changed and the answer says where. | | `--name ` | text | | The workflow name. Required for a new workflow; with workflow\_id it renames. | | `--revision ` | integer | | The revision from get\_workflow that your change starts from. Required with workflow\_id, left out for a new workflow. | | `--workflow-id ` | uuid | | The workflow to change. Leave out to make a new one. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. `script` can only be given this way. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp save-workflow`. ### `widgetic mcp set-ab-test-state` Start, pause or stop a test Use this when the user wants to start an A/B test, pause a running one, start a paused one again, or stop one for good. Starting splits real visitors between the versions on every page that carries the test's embed code. While a test is paused or stopped its tag shows no widget. Stopping cannot be undone, so a stopped test cannot be started again; to stop with a winner pass winner\_version\_id, then put the winning widget's own embed code (get\_embed\_code) on the page in place of the test's tag. It uses no credits. * Tool: `set_ab_test_state` (`widgetic mcp call set_ab_test_state` runs it by that name) * Permission: `widgetic.write` * It changes something; can delete or stop something; safe to repeat. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--ab-test-id ` | uuid | yes | The ab\_test\_id returned by list\_ab\_tests, save\_ab\_test or get\_ab\_test. | | `--action ` | one of `start`, `pause`, `stop` | yes | start a draft or a paused test, pause a running one, or stop a running or paused one for good. | | `--expected-workspace ` | text | | The workspace the user means: "personal" for their own, or the team's name as get\_profile shows it. If this connection works in another one, nothing is changed and the answer says where. | | `--winner-version-id ` | uuid | | With stop: the version\_id of the version that won, as get\_ab\_test lists it. Leave out to stop without a winner. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp set-ab-test-state`. ### `widgetic mcp set-translation-state` Activate or pause a translation Use this when the user wants a translation to go live or to stop being shown: activate makes the embed show each visitor the language of their browser, pause takes it away again. A translation can be activated once it is ready, or when it is paused; not while it is still being made. Nothing is deleted and each action can be undone. It uses no credits. Do not use it to add languages (add\_translation\_languages) or to make a translation (create\_translation). * Tool: `set_translation_state` (`widgetic mcp call set_translation_state` runs it by that name) * Permission: `widgetic.write` * It changes something; can delete or stop something; safe to repeat. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--action ` | one of `activate`, `pause` | yes | activate a ready or paused translation so visitors get it, or pause an active one so they no longer do. | | `--expected-workspace ` | text | | The workspace the user means: "personal" for their own, or the team's name as get\_profile shows it. If this connection works in another one, nothing is changed and the answer says where. | | `--translation-id ` | uuid | yes | The translation\_id returned by list\_translations, create\_translation or get\_translation. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp set-translation-state`. ### `widgetic mcp set-workflow-state` Pause or archive a workflow Use this when the user wants to pause a live workflow, resume a paused one, set one aside (archive) or bring an archived one back (unarchive). While a workflow is paused, its embeds show only its first widget and move no visitor on; resume starts moving them again. An archived workflow is out of the list and cannot be changed or published until it is brought back (a published one comes back paused, a never-published one as a draft). Nothing is deleted and every change can be undone. It uses no credits. * Tool: `set_workflow_state` (`widgetic mcp call set_workflow_state` runs it by that name) * Permission: `widgetic.write` * It changes something; can delete or stop something; safe to repeat. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--action ` | one of `pause`, `resume`, `archive`, `unarchive` | yes | pause a live workflow, resume a paused one, archive a workflow to set it aside, or unarchive an archived one. | | `--expected-workspace ` | text | | The workspace the user means: "personal" for their own, or the team's name as get\_profile shows it. If this connection works in another one, nothing is changed and the answer says where. | | `--workflow-id ` | uuid | yes | The workflow\_id returned by list\_workflows, save\_workflow or get\_workflow. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp set-workflow-state`. ### `widgetic mcp update-brand-kit` Change the Brand Kit Use this when the user wants to change the look every new widget starts from: its colors, fonts, corner radius or style notes, for example square corners, a main color of #314F2F, titles in Playfair Display or backgrounds that are white. Send only the parts to change; a part left out stays as it is. colors replaces the whole palette (no two colors share a role), so read it first with get\_brand\_kit and send every color to keep. instructions are the account's own style notes: an empty string removes them. * Tool: `update_brand_kit` (`widgetic mcp call update_brand_kit` runs it by that name) * Permission: `widgetic.write` * It changes something; safe to repeat. | Flag | Takes | Required | What it does | | - | - | - | - | | `--corner-radius ` | integer | | The corner radius in pixels of a card: 0 makes every corner square, 12 is the usual roundness. Buttons and inputs get about two thirds of it and large panels a quarter more. At most 64. | | `--instructions ` | text | | The account's own style notes for every widget, in the person's words, for example "Use the dark color as the background and the light color for titles". At most 500 characters. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. `colors`, `fonts` can only be given this way. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp update-brand-kit`. ### `widgetic mcp update-widget-customization` Update widget customization Use this when the user wants to change what a widget shows or how it looks: its texts, images from the media library, list items, colors, fonts or sizes. Give widget\_id or composition\_id, not both. On a published widget the change applies at once and embeds show it; on a draft (a widget with no composition yet) it is saved on the draft, shows in its preview and goes live when the widget is published. It uses no credits. Only keys returned by get\_widget\_customization\_options are accepted, and values are checked against the widget's limits. * Tool: `update_widget_customization` (`widgetic mcp call update_widget_customization` runs it by that name) * Permission: `widgetic.write` * It changes something; can delete or stop something; safe to repeat. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--composition-id ` | uuid | | One published copy of a widget. Give this or widget\_id, not both. | | `--widget-id ` | uuid | | The widget to change, a draft or a published one. Give this or composition\_id, not both. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. `content`, `design`, `embed`, `lists` can only be given this way. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp update-widget-customization`. ## Publish (3) ### `widgetic mcp publish-widget` Publish a widget Use this when the user has seen a widget's preview, approved it, and wants it live so it can be embedded on a website, or wants an earlier version live again. It publishes the newest draft (final build and upload), or the version you pass (a number from list\_widget\_versions), creates the widget's composition the first time, and returns the composition\_id and the published version. It can take up to a minute. It replaces the version existing embeds show, so call it only after the user agreed. It needs a plan that includes publishing; if the account's plan does not, the result explains. * Tool: `publish_widget` (`widgetic mcp call publish_widget` runs it by that name) * Permission: `widgetic.publish` * It changes something; can delete or stop something. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--composition-name ` | text | | Name for the published composition, shown in the user's library. Defaults to the widget title. | | `--version ` | integer | | Publish this version instead of the newest draft, for going back to an earlier one: a number from list\_widget\_versions. | | `--widget-id ` | uuid | yes | The widget\_id returned by create\_widget, list\_widgets or get\_widget. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp publish-widget`. ### `widgetic mcp publish-workflow` Publish a workflow Use this when the user wants a workflow to go live: it checks the saved draft and makes it the version visitors get on embeds. Pass the revision you last read; if the draft changed since, nothing is published and you are told to read it again. Problems are listed in plain words and nothing is published until there are none. The result returns the embed code and the snippet for events from the page. Publishing replaces the version that is live now. A paused workflow stays paused until set\_workflow\_state resumes it. It uses no credits. * Tool: `publish_workflow` (`widgetic mcp call publish_workflow` runs it by that name) * Permission: `widgetic.publish` * It changes something; can delete or stop something. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--expected-workspace ` | text | | The workspace the user means: "personal" for their own, or the team's name as get\_profile shows it. If this connection works in another one, nothing is changed and the answer says where. | | `--revision ` | integer | yes | The revision from get\_workflow or save\_workflow that you checked and want published. | | `--workflow-id ` | uuid | yes | The workflow\_id returned by list\_workflows, save\_workflow or get\_workflow. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp publish-workflow`. ### `widgetic mcp unpublish-widget` Unpublish a widget Use this when the user clearly asks for a published widget to come offline without being deleted: its embeds and share links stop showing it to new visitors and it goes back to being a draft. Nothing is deleted: its versions, embed codes, customizations and visitors' entries stay, and publish\_widget brings it back with the same composition\_id (pass the version this tool names to bring back that very one). Pages that already loaded it keep showing it until they reload. It is refused while a running A/B test or a live or paused workflow uses the widget, and it uses no credits. * Tool: `unpublish_widget` (`widgetic mcp call unpublish_widget` runs it by that name) * Permission: `widgetic.publish` * It changes something; can delete or stop something; safe to repeat. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--widget-id ` | uuid | yes | The widget\_id returned by create\_widget, list\_widgets or get\_widget. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp unpublish-widget`. ## Delete (2) ### `widgetic mcp delete-media-file` Delete a media file Use this when the user has clearly asked to permanently delete one file from their media library and has confirmed which one. It removes the stored file and gives its space back to the storage allowance; it cannot be undone. A widget that loads the file from its address stops showing it, so a file that widgets use is refused, with their names, unless even\_if\_used is true (only after the user has heard which widgets). * Tool: `delete_media_file` (`widgetic mcp call delete_media_file` runs it by that name) * Permission: `widgetic.delete` * It changes something; can delete or stop something; safe to repeat. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--confirm-name ` | text | yes | The exact name of the file as the user confirmed it, extension included. The file is deleted only if it matches. | | `--even-if-used` | switch | | Set to true only when the user has been told which widgets use the file and still wants it deleted. Without it, a file that is in use, or whose use could not be fully checked, is not deleted. (default: false) | | `--media-id ` | uuid | yes | A media\_id returned by save\_to\_media\_library or list\_media\_library. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp delete-media-file`. ### `widgetic mcp delete-widget` Delete a widget Use this when the user has clearly asked to permanently delete one of their widgets and has confirmed which one. It removes the widget with all its versions and its published copies; embeds already placed on websites stop working, and it cannot be undone. Credits already used are not refunded. Pass confirm\_title: the exact title of the widget, as returned by get\_widget or list\_widgets and confirmed by the user. A widget that is still being built cannot be deleted. It uses no credits. * Tool: `delete_widget` (`widgetic mcp call delete_widget` runs it by that name) * Permission: `widgetic.delete` * It changes something; can delete or stop something; safe to repeat. * It asks first; without a terminal it needs `--yes`. | Flag | Takes | Required | What it does | | - | - | - | - | | `--confirm-title ` | text | yes | The exact title of the widget as the user confirmed it. The widget is deleted only if it matches. | | `--widget-id ` | uuid | yes | The widget\_id returned by create\_widget, list\_widgets or get\_widget. | | `--input ` | JSON, `@path` or `-` | | The arguments as JSON, `@path` to a file that holds them, or `-` for standard input. The flags above override its keys. | The whole description and the schemas: `widgetic schema mcp delete-widget`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.