CLI commands - Tolstoy

Each command below shows the text that tolstoy <service> <command> --help prints in version 0.4.0 of @tolstoy-ai/cli. tolstoy --version shows the version you have. See Tolstoy CLI to install the CLI and sign in.

ai-widgets

AI widget projects, HTML publishing, plugins, storefront analytics, shopper submissions, reference files, past chats

ai-widgets add-media-to-playlist

Add one media-library item to a playlist.

USAGE:  tolstoy ai-widgets add-media-to-playlist [flags]

FLAGS:
  --playlist-id   (required)
  --vod-asset-id  (required)

ai-widgets clone-project

Clone a referenced AI Widget project into a local or temporary folder for inspection

USAGE:  tolstoy ai-widgets clone-project [flags]

FLAGS:
  --widget-id  Widget ID of the referenced AI Widget project (required)
  --path       Destination folder; defaults to a new temporary folder

ai-widgets create-playlist

Create a media-library playlist.

USAGE:  tolstoy ai-widgets create-playlist [flags]

FLAGS:
  --name  (required)

ai-widgets delete-playlist

Delete a media-library playlist. Its media stay in the library.

USAGE:  tolstoy ai-widgets delete-playlist [flags]

FLAGS:
  --playlist-id  (required)

ai-widgets execute-analytics-sql

Run a read-only SQL query on one AI widget’s storefront analytics: its events, the orders it influenced, and video and page performance, for up to 90 days.

USAGE:  tolstoy ai-widgets execute-analytics-sql [flags]

FLAGS:
  --widget-id   (required)
  --sql         (required)
  --date-range  (json)

SCHEMAS (TypeScript):
  --date-range
  type dateRange = {
      from: string;
      to: string;
  };

ai-widgets execute-store-analytics-sql

Run one read-only SELECT over the whole workspace’s analytics: orders, revenue, sessions, videos, widgets and Meta ads performance. The account filter is added for you and results are capped at 100 rows, so aggregate in SQL.

USAGE:  tolstoy ai-widgets execute-store-analytics-sql [flags]

FLAGS:
  --sql      (required)
  --app-url  A store of this workspace. With it, product_id in the rows is replaced with the product title from its catalog.

ai-widgets get-analytics-panels

Get complete analytics panel definitions for an AI widget

USAGE:  tolstoy ai-widgets get-analytics-panels [flags]

FLAGS:
  --widget-id  (required)

ai-widgets get-playlists

List the playlists a widget can show: built-in source playlists (system) and the merchant’s media-library playlists (custom).

USAGE:  tolstoy ai-widgets get-playlists [flags]

FLAGS:
  (no flags)

ai-widgets get-shopper-store-settings

Read which product pages of a widget show the See it on you and beauty try-on buttons. Change them with plugin-configure —plugin-id shopper-store-settings.

USAGE:  tolstoy ai-widgets get-shopper-store-settings [flags]

FLAGS:
  --widget-id  (required)

ai-widgets legacy-project-details

Get an older Tolstoy widget (carousel, stories, hero, or player) by its publish ID: settings, filters, media, and brand profile.

USAGE:  tolstoy ai-widgets legacy-project-details [flags]

FLAGS:
  --publish-id             Publish ID of the referenced legacy player widget project (required)
  --include-media          Include media selected by the project configuration, resolved in the legacy project workspace (boolean)
  --include-brand-context  Include the store brand context used by effective widget styling (boolean)
  --context-product-id     Product ID used to resolve a PDP widget media view
  --tags                   Shopify tags used to resolve contextual media filters (json)
  --from                   Zero-based media result offset (number, default: 0)
  --size                   Number of media items to return, max 50 (number, default: 12)

SCHEMAS (TypeScript):
  --tags
  type tags = string[];

ai-widgets list-canvas-assets

List the media assets of up to 20 chats, with createdAt, URL, isHighlighted (proposed for review, not approval) and likedByUser (the person hearted it). —chat-id is a chat you can open; —query ’{“chatIds”:[“id1”,“id2”],“limit”:100}’ picks the chats to read. Page with nextOffset.

USAGE:  tolstoy ai-widgets list-canvas-assets [flags]

FLAGS:
  --chat-id  (required)
  --query    (required, json)

SCHEMAS (TypeScript):
  --query
  type query = {
      /** Chats to read. Defaults to the current chat. */
      chatIds?: string[] | undefined;
      view?: ("all" | "highlights") | undefined;
      offset?: number | undefined;
      limit?: number | undefined;
  };

ai-widgets list-chats

List workspace chats newest activity first, with creator, folder, team, source and parent chat. dateFrom/dateTo filter on the creation time. The CLI inherits the current chat team. Without an explicit team or inherited context, it lists Main. Sub-agent and automation chats are left out unless includeChildChats is true or parentChatId is given. Page with nextCursor.

USAGE:  tolstoy ai-widgets list-chats [flags]

FLAGS:
  --sources              (json)
  --team-id              
  --cursor               
  --parent-chat-id       
  --include-child-chats  (boolean)
  --limit                (number, default: 100)
  --folder-id            
  --search               
  --created-by-user-id   
  --date-from            
  --date-to              
  --status               (values: active, archived, default: "active")
  --pinned-only          (boolean)
  --exclude-pinned       (boolean)

SCHEMAS (TypeScript):
  --sources
  type sources = string[];

ai-widgets list-context-files

List the reference files the AI can use for a widget: the files of its Studio project and the brand files of the project’s stores.

USAGE:  tolstoy ai-widgets list-context-files [flags]

FLAGS:
  --team-id    
  --widget-id  (required)

ai-widgets list-customer-data

List what shoppers saved through a widget (quiz answers, preferences, emails), newest first, with filters and a total count. The newest submissions can be missing.

USAGE:  tolstoy ai-widgets list-customer-data [flags]

FLAGS:
  --widget-id  (required)
  --limit      (number)
  --offset     (number)
  --filters    (json)

SCHEMAS (TypeScript):
  --filters
  type filters = {
      key: string;
      value: string;
  }[];

ai-widgets list-live-customer-data

List what shoppers saved through a widget, up to the second, one page at a time, with no filter or sort. Needs a paid plan.

USAGE:  tolstoy ai-widgets list-live-customer-data [flags]

FLAGS:
  --widget-id  (required)
  --limit      (number)
  --cursor     

ai-widgets list-projects

List AI Widget projects (widget IDs, names, statuses). Uses the current chat team when inherited; otherwise lists the workspace.

USAGE:  tolstoy ai-widgets list-projects [flags]

FLAGS:
  --team-id           
  --include-archived  Also include archived projects (boolean)

ai-widgets list-subagent-chats

Where the sub-agent chats of a chat’s family stand now: each item with its subagentRunId, chat, name and state (queued, running, completed, failed, abandoned). —chat-id is any chat of the family; the items of one spawn-subagents call share its subagentRunId.

USAGE:  tolstoy ai-widgets list-subagent-chats [flags]

FLAGS:
  --chat-id  (required)

ai-widgets plugin-configure

Replace the saved configuration of one widget plugin: tolstoy-media (media rules), analytics, interactive-quiz, or shopper-store-settings.

USAGE:  tolstoy ai-widgets plugin-configure [flags]

FLAGS:
  --widget-id  (required)
  --plugin-id  (required)
  --config     (required, json)

SCHEMAS (TypeScript):
  --config
  type config = {
      [x: string]: unknown;
  };

ai-widgets project-details

Get one AI widget project by widget ID: name, status, template, publish method, and latest commit.

USAGE:  tolstoy ai-widgets project-details [flags]

FLAGS:
  --widget-id  Widget ID of the referenced AI Widget project (required)

Build the widget and publish it with its publish method: website page, embed, script or Liquid snippet, Tapcart block, or Shopify theme pages. The new version goes live.

USAGE:  tolstoy ai-widgets publish-ai-widget-project [flags]

FLAGS:
  --widget-id  (required)

ai-widgets publish-html

Publish HTML text or a local HTML file as a public website and return its URL. Each call creates a new page.

USAGE:  tolstoy ai-widgets publish-html [flags]

FLAGS:
  --html  HTML text to publish; supply either --html or --file
  --file  Path to an existing HTML file; supply either --html or --file

ai-widgets read-chat

Read past workspace chats by chat ID, as role and content messages in time order. With includeToolCalls, each tool call shows its input and output (clipped), which carry the IDs of what the chat produced.

USAGE:  tolstoy ai-widgets read-chat [flags]

FLAGS:
  --chat-ids            JSON array of chat IDs from search-chats, for example ["id1"] (required, json)
  --last-messages       (number)
  --include-tool-calls  (boolean)

SCHEMAS (TypeScript):
  --chat-ids
  type chatIds = string[];

ai-widgets read-context-file

Read the text, passages, or download URL of one widget reference file.

USAGE:  tolstoy ai-widgets read-context-file [flags]

FLAGS:
  --team-id      
  --widget-id    (required)
  --file-id      (required)
  --start-chunk  (number)
  --end-chunk    (number)

ai-widgets remove-media-from-playlist

Remove one media-library item from a playlist.

USAGE:  tolstoy ai-widgets remove-media-from-playlist [flags]

FLAGS:
  --playlist-id   (required)
  --vod-asset-id  (required)

ai-widgets rename-playlist

Rename a media-library playlist.

USAGE:  tolstoy ai-widgets rename-playlist [flags]

FLAGS:
  --playlist-id  (required)
  --name         (required)

ai-widgets search-chats

Semantic search over prior chats and their images and assets. The CLI inherits the current chat team; without an explicit team or inherited context, it searches the teams available to the caller. Use it whenever the user refers to an earlier conversation, decision, draft, brief, headline, file, image or asset. Results carry chat IDs for read-chat —chat-ids.

USAGE:  tolstoy ai-widgets search-chats [flags]

FLAGS:
  --team-id       Search this team only. Null selects Main; omitted searches the teams available to the caller.
  --query         Natural language description of the prior conversation or image you are trying to recall (required)
  --title         Optional filter. Only search the chats whose current name contains all of these words.
  --source-types  Optional filter. Defaults to both chat_turn (conversation) and chat_image (generated/uploaded images). (json)
  --max-results   Maximum number of results (default 6, max 12) (number, default: 6)
  --timeframe     How to weight recency. 'recent' (default) biases toward newer chats among comparably-relevant results. Use 'any' only when the user wants the FIRST/oldest occurrence or the whole history regardless of date (e.g. 'the first time we talked about…', 'way back when'). (values: recent, any, default: "recent")
  --after         Optional ISO date/datetime. Only return chat content created on or after this. Set it when the user names the start of a period — resolve relative dates ("since March", "this week") to an absolute date using today's date.
  --before        Optional ISO date/datetime. Only return chat content created on or before this. Use with/instead of `after` for a bounded window ("in March", "last spring", "yesterday").

SCHEMAS (TypeScript):
  --source-types
  type sourceTypes = ("chat_turn" | "chat_image")[];

ai-widgets search-context-files

Search a widget’s reference files by meaning and return the matching passages.

USAGE:  tolstoy ai-widgets search-context-files [flags]

FLAGS:
  --team-id      
  --widget-id    (required)
  --query        (required)
  --max-results  (number)

ai-widgets set-analytics-panels

Replace all analytics panels for an AI widget

USAGE:  tolstoy ai-widgets set-analytics-panels [flags]

FLAGS:
  --widget-id  (required)
  --panels     (required, json)

SCHEMAS (TypeScript):
  --panels
  type panels = {
      id: string;
      title: string;
      description?: string | undefined;
      chartType: "number" | "bar" | "line" | "table" | "pie";
      colSpan?: number | undefined;
      sql: string;
  }[];

billing

Credits left and spent, plan and entitlements, Shoppable Videos views

billing get-account-balance

Get the credits the account has left now and has spent this period, for Studio and Shopper, plus Shoppable Videos views.

USAGE:  tolstoy billing get-account-balance [flags]

FLAGS:
  (no flags)

billing get-billable-impressions-time-series

Get billable Shoppable Videos views per day for a date range, and this period’s views against the plan limit.

USAGE:  tolstoy billing get-billable-impressions-time-series [flags]

FLAGS:
  --from-iso  (required)
  --to-iso    (required)

billing get-billing-info

Get the account’s current plans, paid-until dates, billing provider, and top-up settings, and the plans offered in the given plan group.

USAGE:  tolstoy billing get-billing-info [flags]

FLAGS:
  --group                             (required, values: tolstoy-platform, tolstoy-platform-enterprise, tolstoy-platform-v3)
  --include-legacy-subscription-info  (boolean)

billing get-credits-usage-time-series

Get credits spent per day by Studio or by Shopper for a date range.

USAGE:  tolstoy billing get-credits-usage-time-series [flags]

FLAGS:
  --product   (required, values: studio, shopper)
  --from-iso  (required)
  --to-iso    (required)

billing get-current-billing-store

Get the Shopify store whose subscription pays for the account. Empty when the account pays through Stripe.

USAGE:  tolstoy billing get-current-billing-store [flags]

FLAGS:
  (no flags)

billing get-entitlements

Get which features the account’s plan includes, as feature: true or false.

USAGE:  tolstoy billing get-entitlements [flags]

FLAGS:
  (no flags)

billing get-token-activity

Get the usage history. studio and ai_shopper rows count credits: spent per Studio chat and per Shopper day, and added. ai_player rows count Shoppable Videos views, not credits, and have no costInCents. Usage rows also carry costInCents and userIds; Studio usage rows split it into llmCostInCents and generationCostInCents. sourceChatId links a row to its chat. total is the number of rows.

USAGE:  tolstoy billing get-token-activity [flags]

FLAGS:
  --from-iso  
  --to-iso    

billing get-usage-data

Get the plan names, monthly credit allowance, credits spent this period, Shoppable Videos views, and billing dates.

USAGE:  tolstoy billing get-usage-data [flags]

FLAGS:
  (no flags)

brand

The brand profile of each store: name, logo, colors, fonts, audience, size guide, and brand files

brand assign-model-sizes

Propose a size label from the store’s size guide for each ready fashion model, from its measurements. It saves nothing; brand profile field modelSizeOverrides keeps the sizes.

USAGE:  tolstoy brand assign-model-sizes [flags]

FLAGS:
  --app-url  Store domain from tolstoy stores list, or "unknown" for the global brand profile (required)

brand delete-brand-context-file

Delete one brand file of a store.

USAGE:  tolstoy brand delete-brand-context-file [flags]

FLAGS:
  --app-url  Store domain from tolstoy stores list, or "unknown" for the global brand profile (required)
  --file-id  (required)

brand extract-brand-kit

Read the logo, colors, fonts, and tone of any public website. It saves nothing. Status extracting means the result is not ready yet.

USAGE:  tolstoy brand extract-brand-kit [flags]

FLAGS:
  --url  The brand's website URL — usually the storefront home page. (required)

brand get-brand-context

Get the brand profile of a store: name, website, description, audience, logos, colors, fonts, social links, size guide, and model sizes.

USAGE:  tolstoy brand get-brand-context [flags]

FLAGS:
  --app-url  Store domain from tolstoy stores list, or "unknown" for the global brand profile (required)

brand get-brand-context-file-download-url

Get a temporary download URL for one brand file.

USAGE:  tolstoy brand get-brand-context-file-download-url [flags]

FLAGS:
  --app-url  Store domain from tolstoy stores list, or "unknown" for the global brand profile (required)
  --file-id  (required)

brand list-brand-context-files

List a store’s brand files (PDFs, images, documents) that the AI uses as brand knowledge, with their status and URL.

USAGE:  tolstoy brand list-brand-context-files [flags]

FLAGS:
  --app-url  Store domain from tolstoy stores list, or "unknown" for the global brand profile (required)

brand update-brand-context

Change fields of a store’s brand profile. Each field you send replaces the saved value, and the live storefront widgets use the new value.

USAGE:  tolstoy brand update-brand-context [flags]

FLAGS:
  --app-url               Store domain from tolstoy stores list, or "unknown" for the global brand profile (required)
  --brand-name            
  --brand-website         
  --analytics-domain      
  --industry-verticals    (json)
  --language              
  --description           
  --target-audience       
  --logo-url              
  --player-logo-url       
  --main-logo-url         
  --unify-brand-logo      (boolean)
  --brand-colors          (json)
  --text-colors           (json)
  --font                  (json)
  --header-font           (json)
  --custom-fonts          (json)
  --social-links          (json)
  --measurement-units     (values: metric, imperial)
  --size-guide            
  --size-guide-labels     (json)
  --model-size-overrides  (json)
  --font-styles           (json)

SCHEMAS (TypeScript):
  --industry-verticals
  type industryVerticals = string[];

  --brand-colors
  type brandColors = {
      hex: string;
      name?: string | undefined;
  }[];

  --text-colors
  type textColors = {
      header: string;
      body: string;
  };

  --font
  type font = {
      fontFamily: string;
      sources?: {
          [x: string]: string;
      } | undefined;
  };

  --header-font
  type headerFont = {
      fontFamily: string;
      sources?: {
          [x: string]: string;
      } | undefined;
  };

  --custom-fonts
  type customFonts = {
      family: string;
      sources: {
          [x: string]: string;
      };
  }[];

  --social-links
  type socialLinks = {
      instagram?: string | undefined;
      facebook?: string | undefined;
      x?: string | undefined;
      tiktok?: string | undefined;
      youtube?: string | undefined;
      linkedin?: string | undefined;
      pinterest?: string | undefined;
      snapchat?: string | undefined;
      threads?: string | undefined;
  };

  --size-guide-labels
  type sizeGuideLabels = string[];

  --model-size-overrides
  type modelSizeOverrides = {
      [x: string]: string;
  };

  --font-styles
  type fontStyles = {
      styles: {
          id: string;
          type: "title" | "subtitle" | "heading" | "subheading" | "body" | "quote";
          name: string;
          fontFamily: string;
          fontSize: number;
          letterSpacing: "tight" | "normal" | "wide";
          bold: boolean;
          italic: boolean;
      }[];
  };

folders

Studio projects and their folders, which hold chats, generated media, and widgets

folders create-folder

Create a Studio project, or a folder inside a project when parentFolderId is set

USAGE:  tolstoy folders create-folder [flags]

FLAGS:
  --team-id            
  --name               (required)
  --parent-folder-id   
  --brand-context-ids  (json)

SCHEMAS (TypeScript):
  --brand-context-ids
  type brandContextIds = string[];

folders list-folders

List the Studio projects and the folders inside them

USAGE:  tolstoy folders list-folders [flags]

FLAGS:
  --team-id  

folders rename-folder

Rename a Studio project or folder

USAGE:  tolstoy folders rename-folder [flags]

FLAGS:
  --team-id    
  --folder-id  (required)
  --name       (required)

meta-ads

The merchant’s Meta (Facebook and Instagram) ad accounts, campaigns, ads, and performance

meta-ads get-campaign-project-details

Get one Meta campaign that Tolstoy launched or manages, with its catalog, product set, and video.

USAGE:  tolstoy meta-ads get-campaign-project-details [flags]

FLAGS:
  --campaign-id  (required)

meta-ads get-campaign-projects

List the Meta campaigns Tolstoy launched or manages, from Tolstoy’s saved records across all ad accounts. Status can be out of date.

USAGE:  tolstoy meta-ads get-campaign-projects [flags]

FLAGS:
  (no flags)

meta-ads get-create-campaign-project-status

Get the progress of a Meta campaign launch from Tolstoy by job ID, and the created Meta IDs when it completes.

USAGE:  tolstoy meta-ads get-create-campaign-project-status [flags]

FLAGS:
  --job-id  (required)

meta-ads get-meta-ad-preview

Get a preview of a Meta ad creative as iframe HTML, for one placement (feed, story, or reels).

USAGE:  tolstoy meta-ads get-meta-ad-preview [flags]

FLAGS:
  --creative-id  (required)
  --ad-format    (values: MOBILE_FEED_STANDARD, DESKTOP_FEED_STANDARD, INSTAGRAM_STANDARD, INSTAGRAM_STORY, INSTAGRAM_REELS)

meta-ads get-meta-insights-for-app

Get Meta performance per campaign, ad set, or ad for a date preset: spend, impressions, clicks, CTR, CPC, purchases, and ROAS.

USAGE:  tolstoy meta-ads get-meta-insights-for-app [flags]

FLAGS:
  --level          (required, values: campaign, adset, ad)
  --ad-account-id  
  --date-preset    (values: today, last_7d, last_30d, maximum)
  --time-range     (json)
  --campaign-ids   (json)
  --ad-ids         (json)
  --include-daily  (boolean)

SCHEMAS (TypeScript):
  --time-range
  type timeRange = {
      since: string;
      until: string;
  };

  --campaign-ids
  type campaignIds = string[];

  --ad-ids
  type adIds = string[];

meta-ads get-tolstoy-launched-ads-spend-in-range

Get the total Meta spend, between two dates, of the campaigns Tolstoy launched or manages.

USAGE:  tolstoy meta-ads get-tolstoy-launched-ads-spend-in-range [flags]

FLAGS:
  --since  (required)
  --until  (required)

meta-ads list-ad-accounts

List the Meta ad accounts connected to this workspace.

USAGE:  tolstoy meta-ads list-ad-accounts [flags]

FLAGS:
  (no flags)

meta-ads list-all-meta-campaigns

List campaigns live from one Meta ad account: the ones Tolstoy launched or manages, or every campaign in the account with showAllMeta.

USAGE:  tolstoy meta-ads list-all-meta-campaigns [flags]

FLAGS:
  --campaign-ids      (json)
  --show-all-meta     (boolean)
  --ad-account-id     
  --cursor            
  --effective-status  (json)
  --limit             (number)

SCHEMAS (TypeScript):
  --campaign-ids
  type campaignIds = string[];

  --effective-status
  type effectiveStatus = string[];

meta-ads list-connected-meta-ad-accounts

List the Meta ad accounts connected to this workspace.

USAGE:  tolstoy meta-ads list-connected-meta-ad-accounts [flags]

FLAGS:
  (no flags)

meta-ads list-meta-ad-sets-for-app

List ad sets live from Meta, with budget, goal, schedule, and countries, filtered by campaign. Only Tolstoy campaigns unless showAllMeta is set.

USAGE:  tolstoy meta-ads list-meta-ad-sets-for-app [flags]

FLAGS:
  --campaign-ids   (json)
  --ad-set-ids     (json)
  --show-all-meta  (boolean)
  --ad-account-id  
  --cursor         

SCHEMAS (TypeScript):
  --campaign-ids
  type campaignIds = string[];

  --ad-set-ids
  type adSetIds = string[];

meta-ads list-meta-ads-for-app

List ads live from Meta, with status, issues, creative, and thumbnail, filtered by campaign or ad set. Only Tolstoy campaigns unless showAllMeta is set.

USAGE:  tolstoy meta-ads list-meta-ads-for-app [flags]

FLAGS:
  --campaign-ids   (json)
  --ad-set-ids     (json)
  --ad-ids         (json)
  --show-all-meta  (boolean)
  --ad-account-id  
  --cursor         

SCHEMAS (TypeScript):
  --campaign-ids
  type campaignIds = string[];

  --ad-set-ids
  type adSetIds = string[];

  --ad-ids
  type adIds = string[];

meta-ads list-pages

List the Facebook Pages the Meta connection can use for ads.

USAGE:  tolstoy meta-ads list-pages [flags]

FLAGS:
  (no flags)

List the videos already uploaded to one Meta ad account.

USAGE:  tolstoy meta-ads list-videos [flags]

FLAGS:
  --ad-account-id  (required)
  --limit          (number)

meta-ads meta-graph-get

Run a read-only Meta Graph API GET call using the connected Meta Ads integration

USAGE:  tolstoy meta-ads meta-graph-get [flags]

FLAGS:
  --path     Relative Meta Graph path, e.g. /me/adaccounts or /6983177803962/ads (required)
  --query    Meta Graph query parameters. Objects and arrays are JSON-encoded. (json)
  --version  Meta Graph API version, e.g. v24.0. Defaults to v24.0.

SCHEMAS (TypeScript):
  --query
  type query = {
      [x: string]: unknown;
  };

meta-ads search-targeting-countries

Search, by name, the countries a Meta campaign can target.

USAGE:  tolstoy meta-ads search-targeting-countries [flags]

FLAGS:
  --query  

models

The workspace’s fashion models: the people used for try-on and on-model photos, with their images

models create-model-folder

Create an empty folder for fashion models.

USAGE:  tolstoy models create-model-folder [flags]

FLAGS:
  --team-id  
  --name     (required)

models delete-model

Delete a fashion model from the workspace and from every team.

USAGE:  tolstoy models delete-model [flags]

FLAGS:
  --team-id     
  --model-id    Model ID (required)
  --is-default  (boolean)

models delete-model-folder

Delete a fashion-model folder. Its models stay in the workspace and in their other folders.

USAGE:  tolstoy models delete-model-folder [flags]

FLAGS:
  --team-id       
  --folder-id     (required)
  --operation-id  (required)

models edit-model

Change a fashion model: name, description, measurements, gender, age group, or images.

USAGE:  tolstoy models edit-model [flags]

FLAGS:
  --team-id         
  --model-id        Model ID (required)
  --name            
  --description     
  --measurements    (json)
  --media           (json)
  --new-image-urls  (json)
  --gender          (values: male, female)
  --age-group       (values: baby, kids, teen, adult, senior, all-ages)
  --is-default      (boolean)

SCHEMAS (TypeScript):
  --measurements
  type measurements = {
      chestOrBust?: number | undefined;
      height?: number | undefined;
      hips?: number | undefined;
      waist?: number | undefined;
  };

  --media
  type media = {
      id?: string | undefined;
      mediaReference: string;
      description?: string | undefined;
      inputPrompt?: string | undefined;
      variationType?: ("main" | "pose" | "environment") | undefined;
  }[];

  --new-image-urls
  type newImageUrls = string[];

models get-model

Get one fashion model by ID, with its images and measurements.

USAGE:  tolstoy models get-model [flags]

FLAGS:
  --team-id   
  --model-id  Model ID (required)

models get-model-folders

List the folders that organize the workspace’s fashion models.

USAGE:  tolstoy models get-model-folders [flags]

FLAGS:
  --team-id  

models get-models

List the workspace’s fashion models and Tolstoy’s stock models (defaultModels): name, gender, age group, measurements, and images.

USAGE:  tolstoy models get-models [flags]

FLAGS:
  --team-id         
  --sort-by         (values: createdAt, updatedAt, name)
  --sort-direction  (values: asc, desc)

models move-models

Move fashion models that are in at most one folder into another folder, or out of all folders.

USAGE:  tolstoy models move-models [flags]

FLAGS:
  --team-id       
  --operation-id  (required)
  --folder-id     
  --items         (required, json)

SCHEMAS (TypeScript):
  --items
  type items = {
      modelId: string;
      expectedRevision: number;
  }[];

models rename-model-folder

Rename a fashion-model folder.

USAGE:  tolstoy models rename-model-folder [flags]

FLAGS:
  --team-id            
  --folder-id          (required)
  --name               (required)
  --expected-revision  (required, number)

models update-model-folder-membership

Add fashion models to a folder, or remove them from it. Their other folders do not change.

USAGE:  tolstoy models update-model-folder-membership [flags]

FLAGS:
  --team-id       
  --operation-id  (required)
  --action        (required, values: add, remove)
  --folder-id     (required)
  --items         (required, json)

SCHEMAS (TypeScript):
  --items
  type items = {
      modelId: string;
      expectedRevision: number;
  }[];

models update-model-team-membership

Share a fashion model with one more team, or remove it from one team. Other teams keep it.

USAGE:  tolstoy models update-model-team-membership [flags]

FLAGS:
  --team-id            
  --model-id           (required)
  --operation-id       (required)
  --action             (required, values: add, remove)
  --target-team-id     
  --expected-revision  (required, number)

products

The store’s product catalog from Shopify: products, variants, product images, and collections

products get-collection-products

List the products in one Shopify collection, read live from Shopify, up to 2,000.

USAGE:  tolstoy products get-collection-products [flags]

FLAGS:
  --app-url        Store domain, from tolstoy stores list (required)
  --collection-id  Shopify Collection ID (required)

products get-collections

List the store’s Shopify collections with their product counts, read live from Shopify.

USAGE:  tolstoy products get-collections [flags]

FLAGS:
  --app-url  Store domain, from tolstoy stores list (required)
  --query    Filter collections by title
  --first    (number, default: 50)
  --after    

products get-product

Get one product by its Shopify product ID (the number): title, description, variants with price and stock, images, metafields, and store URL.

USAGE:  tolstoy products get-product [flags]

FLAGS:
  --app-url                  Store domain, from tolstoy stores list (required)
  --product-id               External product ID (required)
  --skip-variant-metafields  Skip live variant metafield enrichment (boolean)

products get-product-category-bucket-counts

Count the products in each category for a search term and filters, largest category first.

USAGE:  tolstoy products get-product-category-bucket-counts [flags]

FLAGS:
  --app-url      Store domain, from tolstoy stores list (required)
  --search-term  
  --filters      (json, default: {})
  --limit        (number)

SCHEMAS (TypeScript):
  --filters
  type filters = {
      productType?: (string[] | undefined) | null;
      category?: (string[] | undefined) | null;
      tags?: (string[] | undefined) | null;
      tagsMatchMode?: ("any" | "all") | undefined;
      inventory?: ({
          min?: (number | undefined) | null;
          max?: (number | undefined) | null;
      } | undefined) | null;
      inStock?: (boolean | undefined) | null;
      productId?: (string[] | undefined) | null;
      variantId?: (string[] | undefined) | null;
      sku?: (string[] | undefined) | null;
      productName?: (string[] | undefined) | null;
      createdAt?: ({
          from?: (string | undefined) | null;
          to?: (string | undefined) | null;
      } | undefined) | null;
  };

products get-product-collections

List the Shopify collections that one product belongs to.

USAGE:  tolstoy products get-product-collections [flags]

FLAGS:
  --app-url     Store domain, from tolstoy stores list (required)
  --product-id  External product ID (required)

List the exact productTypes, categories and tags a store uses, plus its product creation date range

USAGE:  tolstoy products get-product-filters [flags]

FLAGS:
  --app-url  Store domain, from tolstoy stores list (required)

products get-product-media

Get the images and videos attached to one product in Shopify, in store order.

USAGE:  tolstoy products get-product-media [flags]

FLAGS:
  --app-url     Store domain, from tolstoy stores list (required)
  --product-id  External product ID (required)

products get-products-count

Get the total number of products in the store, drafts and unpublished products included.

USAGE:  tolstoy products get-products-count [flags]

FLAGS:
  --app-url  Store domain, from tolstoy stores list (required)
  --strict   (boolean)

products search-products

Search the store’s products by keyword (title, type, tags, vendor) or by exact product ID, variant ID, or SKU, with filters. Returns one page and a cursor for the next.

USAGE:  tolstoy products search-products [flags]

FLAGS:
  --app-url         Store domain, from tolstoy stores list (required)
  --limit           (number, default: 30)
  --cursor          Cursor from previous page
  --search-term     
  --include         (json)
  --filters         (json, default: {})
  --sort-by         (values: inventoryQuantity, providerCreatedAt, providerUpdatedAt)
  --sort-direction  (values: asc, desc, default: "asc")
  --published-only  (boolean)

SCHEMAS (TypeScript):
  --include
  type include = {
      analysis?: (true | {
          analysisTimeoutMs?: number | undefined;
      }) | undefined;
      media?: boolean | undefined;
      variants?: boolean | undefined;
  };

  --filters
  type filters = {
      productType?: (string[] | undefined) | null;
      category?: (string[] | undefined) | null;
      tags?: (string[] | undefined) | null;
      tagsMatchMode?: ("any" | "all") | undefined;
      inventory?: ({
          min?: (number | undefined) | null;
          max?: (number | undefined) | null;
      } | undefined) | null;
      inStock?: (boolean | undefined) | null;
      productId?: (string[] | undefined) | null;
      variantId?: (string[] | undefined) | null;
      sku?: (string[] | undefined) | null;
      productName?: (string[] | undefined) | null;
      createdAt?: ({
          from?: (string | undefined) | null;
          to?: (string | undefined) | null;
      } | undefined) | null;
  };

shopify-theme

Read the files of the store’s Shopify themes

shopify-theme download-theme

Download all files of one Shopify theme into a local folder.

USAGE:  tolstoy shopify-theme download-theme [flags]

FLAGS:
  --app-url   Store domain, from tolstoy stores list (required)
  --theme-id  Shopify theme ID to download (required)
  --path      Output directory for the downloaded Shopify theme (required)

shopify-theme get-file-content

Read one Shopify theme file. Text files come back as text, binary files as base64.

USAGE:  tolstoy shopify-theme get-file-content [flags]

FLAGS:
  --app-url   (required)
  --theme-id  (required)
  --filename  (required)

shopify-theme list-files

List the file paths of one Shopify theme.

USAGE:  tolstoy shopify-theme list-files [flags]

FLAGS:
  --app-url   (required)
  --theme-id  (required)

shopify-theme list-themes

List the store’s Shopify themes. Role MAIN is the live theme. The id is the theme ID the other theme commands take.

USAGE:  tolstoy shopify-theme list-themes [flags]

FLAGS:
  --app-url  (required)

shopper

The store’s AI shopping assistant: profile, skills, chat buttons, and product top questions

shopper add-product-top-questions

Add questions to the top questions of many products. Existing questions stay, and the enabled flag does not change.

USAGE:  tolstoy shopper add-product-top-questions [flags]

FLAGS:
  --app-url                (required)
  --product-ids            (required, json)
  --questions-with-answer  (required, json)

SCHEMAS (TypeScript):
  --product-ids
  type productIds = string[];

  --questions-with-answer
  type questionsWithAnswer = {
      question: string;
      answer?: string | undefined;
  }[];

shopper delete-collection-top-question

Remove one question from the given collections.

USAGE:  tolstoy shopper delete-collection-top-question [flags]

FLAGS:
  --app-url                (required)
  --collection-ids         (required, json)
  --questions-with-answer  (required, json)

SCHEMAS (TypeScript):
  --collection-ids
  type collectionIds = string[];

  --questions-with-answer
  type questionsWithAnswer = {
      question: string;
      answer?: string | undefined;
  };

shopper get-collection-top-questions

Get the top questions set on collections.

USAGE:  tolstoy shopper get-collection-top-questions [flags]

FLAGS:
  --collection-ids  (required, json)
  --app-url         (required)

SCHEMAS (TypeScript):
  --collection-ids
  type collectionIds = string[];

shopper get-product-top-questions

Get the top questions shown for one product, with custom answers and whether they are enabled: the product’s own questions and those of its enabled collections. A product with none gets AI-written questions.

USAGE:  tolstoy shopper get-product-top-questions [flags]

FLAGS:
  --product-id  (required)
  --app-url     (required)

shopper get-shopper-agent-profile

Get the profile of the store’s AI shopping assistant: name, role, image, background, goal, tone, communication style and custom prompt. Global for the store: every shopper surface uses it. A store with no profile gets a generated one.

USAGE:  tolstoy shopper get-shopper-agent-profile [flags]

FLAGS:
  --app-url  (required)

shopper get-shopper-agent-skills

Get the shopper agent skills of a store (try-on, add to cart, coupons, sign-in first, support handoff and others) with their settings.

USAGE:  tolstoy shopper get-shopper-agent-skills [flags]

FLAGS:
  --app-url  (required)

shopper get-shopper-marketplace-tryon-config

Get whether shoppers can try on this store’s products in the Tolstoy Shopper app for Claude and ChatGPT (enabled), and the daily try-on cap (dailyCap). These try-ons are billed to the merchant.

USAGE:  tolstoy shopper get-shopper-marketplace-tryon-config [flags]

FLAGS:
  --app-url  (required)

shopper get-shopper-quick-actions

Get the custom suggested-reply buttons the shopper chat shows under the agent’s replies. An empty list means the agent picks them, starting with the product top questions.

USAGE:  tolstoy shopper get-shopper-quick-actions [flags]

FLAGS:
  --app-url  (required)

shopper get-shopper-shortcuts

Get the shortcut buttons on the opening screen of the shopper chat: send a message, open a page, or show a collection.

USAGE:  tolstoy shopper get-shopper-shortcuts [flags]

FLAGS:
  --app-url  (required)

shopper save-collection-top-questions

Add questions to the top questions of collections. Existing questions stay; pass oldQuestionWithAnswer to replace that one question. enabled applies only to collections that have no questions yet.

USAGE:  tolstoy shopper save-collection-top-questions [flags]

FLAGS:
  --app-url                   (required)
  --collection-ids            (required, json)
  --enabled                   (required, boolean)
  --old-question-with-answer  (json)
  --questions-with-answer     (required, json)

SCHEMAS (TypeScript):
  --collection-ids
  type collectionIds = string[];

  --old-question-with-answer
  type oldQuestionWithAnswer = {
      question: string;
      answer?: string | undefined;
  };

  --questions-with-answer
  type questionsWithAnswer = {
      question: string;
      answer?: string | undefined;
  }[];

shopper save-product-top-questions

Replace the own top questions of the given products and set whether they are enabled. Questions that come from a collection are not part of this list.

USAGE:  tolstoy shopper save-product-top-questions [flags]

FLAGS:
  --product-ids            (required, json)
  --app-url                (required)
  --questions-with-answer  (required, json)
  --enabled                (required, boolean)

SCHEMAS (TypeScript):
  --product-ids
  type productIds = string[];

  --questions-with-answer
  type questionsWithAnswer = {
      question: string;
      answer?: string | undefined;
  }[];

shopper save-shopper-agent-profile

Save the shopper agent profile of a store. Every profile field is required, so start from get-shopper-agent-profile and change only what the merchant asked. Global for the store: every shopper surface uses it.

USAGE:  tolstoy shopper save-shopper-agent-profile [flags]

FLAGS:
  --app-url              (required)
  --name                 (required)
  --role                 (required)
  --image                (required)
  --background           (required)
  --goal                 (required)
  --tone                 (required)
  --communication-style  (required)
  --generating           (boolean)
  --custom-prompt        

shopper save-shopper-agent-skills

Replace the shopper agent skills of a store. The list replaces the saved one, so send every skill from get-shopper-agent-skills with your changes. Global for the store: every shopper surface uses it.

USAGE:  tolstoy shopper save-shopper-agent-skills [flags]

FLAGS:
  --app-url  (required)
  --skills   (required, json)

SCHEMAS (TypeScript):
  --skills
  type skills = ({
      type?: any;
      enabled?: boolean;
      supportMode?: "contact" | "event";
      supportUrl?: string;
      supportEventName?: string;
  } | {
      type?: any;
      enabled?: boolean;
      initialSizeRecommendation?: boolean;
      requireMeasurements?: boolean;
  } | {
      type?: any;
      enabled?: boolean;
      previewImage?: unknown;
      previewImageUrl?: string | undefined;
      weeklyUsageLimit?: number;
      skipSignIn?: boolean;
      signInPromptText?: string;
      signInButtonLabel?: string;
      brandMarketingConsentText?: string | undefined;
      privacyPolicyUrl?: string | undefined;
      privacyPolicyLinkText?: string | undefined;
      enableBrandedEmails?: boolean;
      /** The model that renders the try-on. The default, gpt_image_2_5_sunburst_fast, is fast and low-cost, but it refuses many swimwear, lingerie, sleepwear and revealing-cut renders; with allowModelFallback on, a refused render gets one more attempt on a slower model that holds the shopper's face less well. nano_banana_2_1 renders most of the swimwear, lingerie and sleepwear that the default refuses, and it holds the shopper's face best of the models that render them. */
      tryonModel?: "nano_banana" | "nano_banana_pro" | "nano_banana_2" | "nano_banana_2_lite" | "nano_banana_2_1" | "flux_2_pro" | "gpt_image_2_low" | "gpt_image_2_medium" | "gpt_image_2_5_sunburst_fast" | "gpt_image_2_5_sunburst_balanced" | "seedream_v5_lite" | "meta_muse_image";
      allowModelFallback?: boolean;
      allowAnimation?: boolean;
      nsfwMode?: "allow" | "block" | "hide";
      tryonContext?: string | undefined;
      stylingReferenceImageUrl?: string | undefined;
      seedMessage?: string | undefined;
  } | {
      type?: any;
      enabled?: boolean;
      previewImage?: unknown;
      previewImageUrl?: string | undefined;
      weeklyUsageLimit?: number;
      skipSignIn?: boolean;
      signInPromptText?: string;
      signInButtonLabel?: string;
      brandMarketingConsentText?: string | undefined;
      privacyPolicyUrl?: string | undefined;
      privacyPolicyLinkText?: string | undefined;
      enableBrandedEmails?: boolean;
      tryonModel?: "nano_banana" | "nano_banana_pro" | "nano_banana_2" | "nano_banana_2_lite" | "nano_banana_2_1" | "flux_2_pro" | "gpt_image_2_low" | "gpt_image_2_medium" | "gpt_image_2_5_sunburst_fast" | "gpt_image_2_5_sunburst_balanced" | "seedream_v5_lite" | "meta_muse_image";
      allowModelFallback?: boolean;
      allowAnimation?: boolean;
      nsfwMode?: "allow" | "block" | "hide";
      tryonContext?: string | undefined;
      seedMessage?: string | undefined;
  } | {
      type?: any;
      enabled?: boolean;
      skipSignIn?: boolean | undefined;
      signInPromptText?: string | undefined;
      signInButtonLabel?: string | undefined;
  } | {
      type?: any;
      enabled?: boolean;
      /** Array of Shopify tags that should be excluded from add to cart */
      blockedTags?: string[];
      /** Array of collection IDs that should be excluded from add to cart */
      blockedCollectionIds?: string[];
  } | {
      type?: any;
      enabled?: boolean;
  } | {
      type?: any;
      enabled?: boolean;
  } | {
      type?: any;
      enabled?: boolean;
  } | {
      type?: any;
      enabled?: boolean;
  } | {
      type?: any;
      enabled?: boolean;
      vertical?: "beauty" | "fashion" | "eyewear";
      weeklyUsageLimit?: number | undefined;
  } | {
      type?: any;
      enabled?: boolean | null;
      allowOutOfStockDiscovery?: boolean;
      allowOutOfStockRecommendations?: boolean;
  })[];

shopper save-shopper-marketplace-tryon-config

Turn on or off try-on of this store’s products in the Tolstoy Shopper app for Claude and ChatGPT, or change its daily cap. These try-ons are billed to the merchant. Only the fields you send change.

USAGE:  tolstoy shopper save-shopper-marketplace-tryon-config [flags]

FLAGS:
  --app-url    (required)
  --enabled    (boolean, default: false)
  --daily-cap  (number, default: 100)

shopper save-shopper-quick-actions

Replace the custom suggested-reply buttons of the shopper chat. The list replaces the saved one, so read it first. A non-empty list replaces the buttons the agent picks, at every turn. Global for the store.

USAGE:  tolstoy shopper save-shopper-quick-actions [flags]

FLAGS:
  --app-url  (required)
  --actions  (required, json)

SCHEMAS (TypeScript):
  --actions
  type actions = {
      text: string;
      type: "CHAT_MESSAGE" | "FIND_MY_SIZE" | "TRY_ANOTHER_PRODUCT" | "ADD_TO_CART" | "TRY_ANOTHER_VARIANT" | "TRY_ON_PRODUCT" | "GET_COUPON" | "UPLOAD_PHOTO_FOR_TRYON";
  }[];

shopper save-shopper-shortcuts

Replace the shortcut buttons on the opening screen of the shopper chat. The list replaces the saved one, so read it first. Global for the store.

USAGE:  tolstoy shopper save-shopper-shortcuts [flags]

FLAGS:
  --app-url    (required)
  --shortcuts  (required, json)

SCHEMAS (TypeScript):
  --shortcuts
  type shortcuts = ({
      label: string;
      type: "NAVIGATE";
      url: string;
  } | {
      label: string;
      type: "CHAT_MESSAGE";
  } | {
      label: string;
      type: "SHOW_COLLECTION";
      collectionId: string;
      collectionHandle?: string | undefined;
  })[];

stores

The stores connected to this workspace: the values for —app-url

stores list

List the stores connected to this workspace. Each appUrl is a value for —app-url.

USAGE:  tolstoy stores list [flags]

FLAGS:
  (no flags)

studio

AI Studio generations (images, videos, audio) and saved Remotion video templates

studio create-studio-asset-comment

Create a team comment or reply on a Studio image asset

USAGE:  tolstoy studio create-studio-asset-comment [flags]

FLAGS:
  --team-id            
  --asset-id           (required)
  --body               (required)
  --parent-comment-id  

studio get-draft-studio-asset-counts-by-product-ids

Count, per product, the Studio generations that are not in the media library yet.

USAGE:  tolstoy studio get-draft-studio-asset-counts-by-product-ids [flags]

FLAGS:
  --team-id              
  --product-ids          (required, json)
  --included-folder-ids  (json)

SCHEMAS (TypeScript):
  --product-ids
  type productIds = string[];

  --included-folder-ids
  type includedFolderIds = string[];

studio get-remotion-template-by-id

Get one saved Remotion video template by ID, with its code.

USAGE:  tolstoy studio get-remotion-template-by-id [flags]

FLAGS:
  --id  (required)

studio get-remotion-templates

List the 50 newest Remotion video templates saved in this workspace, without their code.

USAGE:  tolstoy studio get-remotion-templates [flags]

FLAGS:
  (no flags)

studio get-studio-asset-comments

List team comments for a Studio image asset

USAGE:  tolstoy studio get-studio-asset-comments [flags]

FLAGS:
  --team-id   
  --asset-id  (required)

trends

Market research: competitor Meta ads, TikTok and Instagram posts, Pinterest and X trends

trends ad-spy-get-all-ads

List the collected Meta ads of all tracked brands, with the same filters as for one brand.

USAGE:  tolstoy trends ad-spy-get-all-ads [flags]

FLAGS:
  --limit             (number, default: 30)
  --offset            (number, default: 0)
  --is-active         (boolean)
  --display-format    
  --keyword           
  --sort-by           (values: newest, running_days, default: "running_days")
  --min-running-days  (number)
  --saved-only        (boolean)

trends ad-spy-get-brand-ads

List the collected Meta ads of one tracked brand, filtered by format, keyword, active state, or running days.

USAGE:  tolstoy trends ad-spy-get-brand-ads [flags]

FLAGS:
  --brand-id          (required, number)
  --limit             (number, default: 30)
  --offset            (number, default: 0)
  --is-active         (boolean)
  --display-format    
  --keyword           
  --sort-by           (values: newest, running_days, default: "running_days")
  --min-running-days  (number)
  --saved-only        (boolean)

trends ad-spy-get-brand-analytics

Get the ad statistics of one tracked brand: counts by format and state, running days, and top landing pages.

USAGE:  tolstoy trends ad-spy-get-brand-analytics [flags]

FLAGS:
  --brand-id  (required, number)

trends ad-spy-get-tracked-brands

List the competitor brands this workspace tracks, with the number of new ads in the last 7 days.

USAGE:  tolstoy trends ad-spy-get-tracked-brands [flags]

FLAGS:
  (no flags)

trends ad-spy-save-ad

Bookmark a competitor ad in Ad Spy. The media library does not change.

USAGE:  tolstoy trends ad-spy-save-ad [flags]

FLAGS:
  --brand-ad-id  (required, number)

trends ad-spy-track-brand

Start tracking the Meta ads of a competitor brand by its Facebook Page ID. New ads are collected every day.

USAGE:  tolstoy trends ad-spy-track-brand [flags]

FLAGS:
  --platform          (required)
  --external-page-id  (required)
  --name              (required)
  --image-url         
  --category          

trends ad-spy-unsave-ad

Remove an Ad Spy bookmark from a competitor ad.

USAGE:  tolstoy trends ad-spy-unsave-ad [flags]

FLAGS:
  --brand-ad-id  (required, number)

trends ad-spy-untrack-brand

Stop tracking a competitor brand

USAGE:  tolstoy trends ad-spy-untrack-brand [flags]

FLAGS:
  --brand-id  (required, number)

trends get-organic-search-status

Get the status of an organic post search by processId, and the posts when it is complete.

USAGE:  tolstoy trends get-organic-search-status [flags]

FLAGS:
  --process-id  Process ID from submit (required)

trends pinterest-inspiration

Search Pinterest for visual references

USAGE:  tolstoy trends pinterest-inspiration [flags]

FLAGS:
  --query  Search term for visual inspiration (required)
  --limit  Maximum number of pins to return (number, default: 20)

trends pinterest-trends

Trending Pinterest keywords with growth data

USAGE:  tolstoy trends pinterest-trends [flags]

FLAGS:
  --interests   Interest categories to filter by (e.g. ["womens_fashion", "beauty", "home_decor"]) (json, default: [])
  --region      Pinterest trend market. UK and AU are accepted as aliases for their supported combined markets. (values: US, CA, DE, FR, ES, IT, DE+AT+CH, GB+IE, IT+ES+PT+GR+MT, PL+RO+HU+SK+CZ, SE+DK+FI+NO, NL+BE+LU, AR, BR, CO, MX, MX+AR+CO+CL, AU+NZ, UK, AU, default: "US")
  --trend-type  Type of trends to fetch (values: growing, monthly, yearly, seasonal, default: "growing")
  --limit       Maximum number of trends to return (number, default: 20)

SCHEMAS (TypeScript):
  --interests
  type interests = string[];

trends submit-organic-search

Start a search for public TikTok or Instagram posts by profile handle, or by hashtag on Instagram. Returns a processId.

USAGE:  tolstoy trends submit-organic-search [flags]

FLAGS:
  --platform      Social platform to search (required, values: tiktok, instagram)
  --query         Username handle (no @) or hashtag (no #) (required)
  --search-type   Search type (Instagram only, default: profile) (values: profile, hashtag)
  --results-type  Content type (Instagram only, default: reels) (values: posts, reels)
  --limit         Max results (1-30, default: 20) (number)

trends x-trends

Currently trending topics on X

USAGE:  tolstoy trends x-trends [flags]

FLAGS:
  --region  Region code (US, UK, CA, AU, DE, FR, JP, BR, IN, MX, or WORLDWIDE) (default: "US")
  --limit   Maximum number of trends to return (number, default: 20)

video

The media library (VOD assets): the merchant’s videos and images, playlists, and product tags

video approve-v2

Approve a completed Studio draft without changing its asset ID.

USAGE:  tolstoy video approve-v2 [flags]

FLAGS:
  --id  (required)

video archive-v2

Archive a completed VodAssetV2 record.

USAGE:  tolstoy video archive-v2 [flags]

FLAGS:
  --id  (required)

video get-active-shopify-tags

List the Shopify product tags that are attached to at least one media-library item.

USAGE:  tolstoy video get-active-shopify-tags [flags]

FLAGS:
  (no flags)

video get-tagged-vod-asset-counts-by-product-ids

Count, per Shopify product, the media-library items tagged to it. Archived items are counted.

USAGE:  tolstoy video get-tagged-vod-asset-counts-by-product-ids [flags]

FLAGS:
  --product-ids            JSON array of Shopify product IDs, for example ["123"] (required, json)
  --asset-types            (json)
  --project-folder-filter  (json)

SCHEMAS (TypeScript):
  --product-ids
  type productIds = string[];

  --asset-types
  type assetTypes = unknown[];

  --project-folder-filter
  type projectFolderFilter = {
      includedProjectFolderIds: string[];
      excludedLegacyProjectFolderIds: string[];
  };

video get-v2

Get VodAssetV2 records by ID, with optional media and connections.

USAGE:  tolstoy video get-v2 [flags]

FLAGS:
  --ids      (required, json)
  --include  (json)

SCHEMAS (TypeScript):
  --ids
  type ids = string[];

  --include
  type include = {
      mediaDbAsset?: boolean | undefined;
      widgetRenditions?: boolean | undefined;
      connections?: (boolean | string) | undefined;
  };

List saved dynamic playlists (media filter views): id, name, and rule conditionExpression. Use to resolve a dynamic playlist the merchant names.

USAGE:  tolstoy video list-dynamic-playlists [flags]

FLAGS:
  (no flags)

List the media library’s playlists, which the merchant fills by hand.

USAGE:  tolstoy video list-playlists [flags]

FLAGS:
  (no flags)

video query-dynamic-playlist

Preview the media of a saved dynamic playlist. Nothing changes.

USAGE:  tolstoy video query-dynamic-playlist [flags]

FLAGS:
  --app-url             Store domain, from tolstoy stores list (required)
  --context-product-id  Product ID used to resolve Product view filters
  --tags                Shopify tags used to resolve contextual tag filters (json)
  --params              Custom values for __PLACEHOLDER__ tokens in the filter (json)
  --from                Zero-based result offset (number, default: 0)
  --size                Number of media items to return, max 50 (number, default: 12)
  --view-id             Saved dynamic playlist ID from list-dynamic-playlists (required)

SCHEMAS (TypeScript):
  --tags
  type tags = string[];

  --params
  type params = {
      [x: string]: string | string[];
  };

video query-media

Preview the media a widget shows for a dynamic-playlist rule, with the same engine and exclusions as the storefront. Nothing is saved.

USAGE:  tolstoy video query-media [flags]

FLAGS:
  --app-url               Store domain, from tolstoy stores list (required)
  --context-product-id    Product ID used to resolve Product view filters
  --tags                  Shopify tags used to resolve contextual tag filters (json)
  --params                Custom values for __PLACEHOLDER__ tokens in the filter (json)
  --from                  Zero-based result offset (number, default: 0)
  --size                  Number of media items to return, max 50 (number, default: 12)
  --condition-expression  Dynamic playlist condition expression (required, json)
  --pins                  Optional pinned media and positions (json, default: [])
  --sort                  (values: asc, desc)
  --sort-by               (values: created-at, updated-at, likes)

SCHEMAS (TypeScript):
  --tags
  type tags = string[];

  --params
  type params = {
      [x: string]: string | string[];
  };

  --condition-expression
  type conditionExpression = ({
      field: string;
      customId?: string | undefined;
      operator: "EQUAL";
      value: string | number | boolean;
  } | {
      field: string;
      customId?: string | undefined;
      operator: "IN";
      value: (string | number | boolean)[];
  } | {
      field: string;
      customId?: string | undefined;
      operator: "GT";
      value: string | number;
  } | {
      field: string;
      customId?: string | undefined;
      operator: "GTE";
      value: string | number;
  } | {
      field: string;
      customId?: string | undefined;
      operator: "LT";
      value: string | number;
  } | {
      field: string;
      customId?: string | undefined;
      operator: "LTE";
      value: string | number;
  } | {
      field: string;
      customId?: string | undefined;
      operator: "STARTS_WITH";
      value: string;
  } | {
      field: string;
      customId?: string | undefined;
      operator: "CONTAINS";
      value: string;
  } | {
      field: string;
      customId?: string | undefined;
      operator: "EXISTS";
  }) | {
      operator: "EQUAL";
      customId?: string | undefined;
      left: string | number | boolean;
      right: string | number | boolean;
  } | {
      customId?: string | undefined;
      operator: "AND" | "OR";
      children: conditionExpression;
  } | {
      customId?: string | undefined;
      operator: "NOT";
      child: conditionExpression;
  } | {
      operator: "PIN";
      customId?: string | undefined;
      child: conditionExpression;
  } | {
      operator: "BOOST";
      customId?: string | undefined;
      boost: number;
      children: conditionExpression;
  };

  --pins
  type pins = {
      id: string;
      position: number;
      productId?: string | undefined;
  }[];

video search-v2

Search uploaded media and Studio drafts as VodAssetV2 records, with text, metadata, product, folder, and status filters.

USAGE:  tolstoy video search-v2 [flags]

FLAGS:
  --filter     (json)
  --variables  (json)
  --sort       (json)
  --cursor     Omit or pass null for the first page; pass nextCursor for the next page with the same filters and sort.
  --page       (json, default: {})
  --include    (json)
  --team-id    (default: null)

SCHEMAS (TypeScript):
  --filter
  type filter = ({
      op: "eq";
      field: (("id" | "appKey" | "name" | "createdByUserId" | "createInTeam" | "sharedWithTeams" | "mediaDBId" | "uploadType" | "type" | "status" | "projectFolderId" | "appExternalId" | "externalId" | "ugcUsername" | "pinterestBoardId" | "labelIds" | "shopifyTags" | "externalProductIds" | "suggestedProducts" | "hasShopifyTagsInStores" | "hasSuggestedProductsInStores" | "hasProductsInStores" | "hasShopifyMediaInStores") | ("likes" | "comments") | ("createdAt" | "updatedAt" | "externalCreatedAt" | "aggregatedCreatedAt" | "metafields.expirationDate" | "metafields.archivedAt") | ("favorite") | "description") | ("type" | "value");
      value: string | number | boolean;
      boost?: number | undefined;
  } | {
      op: "in";
      field: (("id" | "appKey" | "name" | "createdByUserId" | "createInTeam" | "sharedWithTeams" | "mediaDBId" | "uploadType" | "type" | "status" | "projectFolderId" | "appExternalId" | "externalId" | "ugcUsername" | "pinterestBoardId" | "labelIds" | "shopifyTags" | "externalProductIds" | "suggestedProducts" | "hasShopifyTagsInStores" | "hasSuggestedProductsInStores" | "hasProductsInStores" | "hasShopifyMediaInStores") | ("likes" | "comments") | ("createdAt" | "updatedAt" | "externalCreatedAt" | "aggregatedCreatedAt" | "metafields.expirationDate" | "metafields.archivedAt") | ("favorite") | "description") | ("type" | "value");
      value: (string | number | boolean)[];
      boost?: number | undefined;
  } | {
      op: "gt" | "gte" | "lt" | "lte";
      field: ("createdAt" | "updatedAt" | "externalCreatedAt" | "aggregatedCreatedAt" | "metafields.expirationDate" | "metafields.archivedAt") | ("likes" | "comments");
      value: string | number;
      boost?: number | undefined;
  } | {
      op: "startsWith" | "contains";
      field: ("id" | "appKey" | "name" | "createdByUserId" | "createInTeam" | "sharedWithTeams" | "mediaDBId" | "uploadType" | "type" | "status" | "projectFolderId" | "appExternalId" | "externalId" | "ugcUsername" | "pinterestBoardId" | "labelIds" | "shopifyTags" | "externalProductIds" | "suggestedProducts" | "hasShopifyTagsInStores" | "hasSuggestedProductsInStores" | "hasProductsInStores" | "hasShopifyMediaInStores") | ("type" | "value") | "description";
      value: string;
      caseSensitive?: boolean | undefined;
      boost?: number | undefined;
  } | {
      op: "match";
      field: "name" | "description";
      value: string;
      boost?: number | undefined;
  } | {
      op: "exists";
      field: (("id" | "appKey" | "name" | "createdByUserId" | "createInTeam" | "sharedWithTeams" | "mediaDBId" | "uploadType" | "type" | "status" | "projectFolderId" | "appExternalId" | "externalId" | "ugcUsername" | "pinterestBoardId" | "labelIds" | "shopifyTags" | "externalProductIds" | "suggestedProducts" | "hasShopifyTagsInStores" | "hasSuggestedProductsInStores" | "hasProductsInStores" | "hasShopifyMediaInStores") | ("likes" | "comments") | ("createdAt" | "updatedAt" | "externalCreatedAt" | "aggregatedCreatedAt" | "metafields.expirationDate" | "metafields.archivedAt") | ("favorite") | "description") | ("type" | "value");
      boost?: number | undefined;
  }) | {
      and: filter[];
      boost?: number | undefined;
  } | {
      or: filter[];
      boost?: number | undefined;
  } | {
      not: filter;
      boost?: number | undefined;
  } | {
      nested: {
          path: "metadata";
          filter: filter;
      };
  };

  --variables
  type variables = {
      [x: string]: string;
  };

  --sort
  type sort = {
      field: (("id" | "appKey" | "name" | "createdByUserId" | "createInTeam" | "sharedWithTeams" | "mediaDBId" | "uploadType" | "type" | "status" | "projectFolderId" | "appExternalId" | "externalId" | "ugcUsername" | "pinterestBoardId" | "labelIds" | "shopifyTags" | "externalProductIds" | "suggestedProducts" | "hasShopifyTagsInStores" | "hasSuggestedProductsInStores" | "hasProductsInStores" | "hasShopifyMediaInStores") | ("likes" | "comments") | ("createdAt" | "updatedAt" | "externalCreatedAt" | "aggregatedCreatedAt" | "metafields.expirationDate" | "metafields.archivedAt") | ("favorite") | "description") | "_score";
      order: "asc" | "desc";
      missing?: ("first" | "last") | undefined;
      mode?: ("min" | "max") | undefined;
  }[];

  --page
  type page = {
      limit?: number;
  };

  --include
  type include = {
      mediaDbAsset?: boolean | undefined;
      widgetRenditions?: boolean | undefined;
      connections?: (boolean | string) | undefined;
  };

video search-vod

Search the media library (videos, images, galleries) by text, type, source, product, playlist, tag, or date. Archived items are left out. Use original.url for generation when original.status is ready.

USAGE:  tolstoy video search-vod [flags]

FLAGS:
  --filters                Filters to include and exclude. notSatisfies defaults to []. (required, json)
  --sort                   Optional single-field sort override. (json)
  --sort-by                Advanced multi-field sort. Defaults to newest media first. (json, default: [{"field":"date","direction":"desc"}])
  --from                   Zero-based index of the first result (required, number)
  --size                   Number of results in the page (required, number)
  --with-connections       Include product tags, playlists, and other media connections. (boolean)
  --app-url                Store domain, from tolstoy stores list (required)
  --include-invalid        (boolean)
  --include-shared         (boolean)
  --shared-only            (boolean)
  --project-folder-filter  (json)

SCHEMAS (TypeScript):
  --filters
  type filters = {
      satisfies: ({
          name: "type";
          value: "video" | "image" | "gallery";
      } | {
          name: "types";
          value: ("video" | "image" | "gallery")[];
      } | {
          name: "text";
          value: string;
      } | {
          name: "source";
          value: unknown[];
      } | {
          name: "tagged";
          value: {
              taggedIn: ("tag" | "productId" | "vodLabelId" | "suggestedProducts")[];
              shopifyUrl: string;
          } | {
              taggedIn: ("vodLabelId")[];
          };
      } | {
          name: "products";
          value: string[];
      } | {
          name: "uploadType";
          value: string[];
      } | {
          name: "labels";
          value: string[];
      } | {
          name: "tags";
          value: string[];
      } | {
          name: "owner";
          value: string[];
      } | {
          name: "suggestedProducts";
          value: string[];
      } | {
          name: "appExternalId";
          value: string[];
      } | {
          name: "createDate";
          value: {
              start?: string | undefined;
              end?: string | undefined;
          };
      } | {
          name: "date";
          value: {
              start?: string | undefined;
              end?: string | undefined;
          };
      } | {
          name: "instaTags";
          value: string[];
      } | {
          name: "settingsVersion";
          value: string;
      } | {
          name: "ugcUsername";
          value: string[];
      } | {
          name: "stores";
          value: string[];
      } | {
          name: "folder";
          value: string;
      } | {
          name: "favorite";
          value: boolean;
      } | {
          name: "pinterestBoardIds";
          value: string[];
      } | {
          name: "shopifyPublished";
          value: boolean;
      })[];
      notSatisfies?: ({
          name: "type";
          value: "video" | "image" | "gallery";
      } | {
          name: "types";
          value: ("video" | "image" | "gallery")[];
      } | {
          name: "text";
          value: string;
      } | {
          name: "source";
          value: unknown[];
      } | {
          name: "tagged";
          value: {
              taggedIn: ("tag" | "productId" | "vodLabelId" | "suggestedProducts")[];
              shopifyUrl: string;
          } | {
              taggedIn: ("vodLabelId")[];
          };
      } | {
          name: "products";
          value: string[];
      } | {
          name: "uploadType";
          value: string[];
      } | {
          name: "labels";
          value: string[];
      } | {
          name: "tags";
          value: string[];
      } | {
          name: "owner";
          value: string[];
      } | {
          name: "suggestedProducts";
          value: string[];
      } | {
          name: "appExternalId";
          value: string[];
      } | {
          name: "createDate";
          value: {
              start?: string | undefined;
              end?: string | undefined;
          };
      } | {
          name: "date";
          value: {
              start?: string | undefined;
              end?: string | undefined;
          };
      } | {
          name: "instaTags";
          value: string[];
      } | {
          name: "settingsVersion";
          value: string;
      } | {
          name: "ugcUsername";
          value: string[];
      } | {
          name: "stores";
          value: string[];
      } | {
          name: "folder";
          value: string;
      } | {
          name: "favorite";
          value: boolean;
      } | {
          name: "pinterestBoardIds";
          value: string[];
      } | {
          name: "shopifyPublished";
          value: boolean;
      })[];
  };

  --sort
  type sort = {
      field: "createdAt" | "updatedAt" | "date" | "likes" | "comments" | "aiUgcScore" | "uploadType" | "type";
      direction: "asc" | "desc";
  };

  --sort-by
  type sortBy = {
      field: "createdAt" | "updatedAt" | "date" | "likes" | "comments" | "aiUgcScore" | "uploadType" | "type";
      direction: "asc" | "desc";
  }[];

  --project-folder-filter
  type projectFolderFilter = {
      includedProjectFolderIds: string[];
      excludedLegacyProjectFolderIds: string[];
  };

video search-vod-assets-by-product-id

List the media-library items tagged to one Shopify product. Use original.url for generation when original.status is ready.

USAGE:  tolstoy video search-vod-assets-by-product-id [flags]

FLAGS:
  --product-id             (required)
  --from                   Zero-based index of the first result (required, number)
  --size                   Number of results in the page (required, number)
  --project-folder-filter  (json)

SCHEMAS (TypeScript):
  --project-folder-filter
  type projectFolderFilter = {
      includedProjectFolderIds: string[];
      excludedLegacyProjectFolderIds: string[];
  };

video search-vod-by-external-ids

Get media-library items by the ID they have in their source, such as an Instagram post ID or the ID of the Studio generation they came from. Use original.url for generation when original.status is ready.

USAGE:  tolstoy video search-vod-by-external-ids [flags]

FLAGS:
  --external-ids  JSON array of source IDs, for example ["id1"] (required, json)

SCHEMAS (TypeScript):
  --external-ids
  type externalIds = string[];

video search-vod-by-ids

Get media-library items by their IDs, archived items included. Use original.url for generation when original.status is ready.

USAGE:  tolstoy video search-vod-by-ids [flags]

FLAGS:
  --ids  JSON array of media-library IDs, for example ["id1","id2"] (required, json)

SCHEMAS (TypeScript):
  --ids
  type ids = string[];

video tag-product

Tag a Shopify product and its complete selected variant list on one media-library item.

USAGE:  tolstoy video tag-product [flags]

FLAGS:
  --app-url                               Store domain, from tolstoy stores list (required)
  --vod-asset-id                          VOD asset ID to tag (required)
  --external-product-id                   Shopify external product ID to tag on the VOD asset (required)
  --variant-id                            Legacy single variant ID. Use variantIds for new calls. Cannot be combined with variantIds.
  --variant-ids                           Complete Shopify variant ID list. Include all sizes of the selected color. Empty or omitted means every variant. Replaces the existing list. (json)
  --replace-existing-product-connections  Remove existing product tags on this VOD asset after the new product tag is saved (boolean, default: false)

SCHEMAS (TypeScript):
  --variant-ids
  type variantIds = string[];

video unarchive-v2

Restore an archived VodAssetV2 record.

USAGE:  tolstoy video unarchive-v2 [flags]

FLAGS:
  --id  (required)

​ai-widgets

​ai-widgets add-media-to-playlist

​ai-widgets clone-project

​ai-widgets create-playlist

​ai-widgets delete-playlist

​ai-widgets execute-analytics-sql

​ai-widgets execute-store-analytics-sql

​ai-widgets get-analytics-panels

​ai-widgets get-playlists

​ai-widgets get-shopper-store-settings

​ai-widgets legacy-project-details

​ai-widgets list-canvas-assets

​ai-widgets list-chats

​ai-widgets list-context-files

​ai-widgets list-customer-data

​ai-widgets list-live-customer-data

​ai-widgets list-projects

​ai-widgets list-subagent-chats

​ai-widgets plugin-configure

​ai-widgets project-details

​ai-widgets publish-ai-widget-project

​ai-widgets publish-html

​ai-widgets read-chat

​ai-widgets read-context-file

​ai-widgets remove-media-from-playlist

​ai-widgets rename-playlist

​ai-widgets search-chats

​ai-widgets search-context-files

​ai-widgets set-analytics-panels

​billing

​billing get-account-balance

​billing get-billable-impressions-time-series

​billing get-billing-info

​billing get-credits-usage-time-series

​billing get-current-billing-store

​billing get-entitlements

​billing get-token-activity

​billing get-usage-data

​brand

​brand assign-model-sizes

​brand delete-brand-context-file

​brand extract-brand-kit

​brand get-brand-context

​brand get-brand-context-file-download-url

​brand list-brand-context-files

​brand update-brand-context

​folders

​folders create-folder

​folders list-folders

​folders rename-folder

​meta-ads

​meta-ads get-campaign-project-details

​meta-ads get-campaign-projects

​meta-ads get-create-campaign-project-status

​meta-ads get-meta-ad-preview

​meta-ads get-meta-insights-for-app

​meta-ads get-tolstoy-launched-ads-spend-in-range

​meta-ads list-ad-accounts

​meta-ads list-all-meta-campaigns

​meta-ads list-connected-meta-ad-accounts

​meta-ads list-meta-ad-sets-for-app

​meta-ads list-meta-ads-for-app

​meta-ads list-pages

​meta-ads list-videos

​meta-ads meta-graph-get

​meta-ads search-targeting-countries

​models

​models create-model-folder

​models delete-model

​models delete-model-folder

​models edit-model

​models get-model

​models get-model-folders

​models get-models

​models move-models

​models rename-model-folder

​models update-model-folder-membership

​models update-model-team-membership

​products

​products get-collection-products