> ## Documentation Index
> Fetch the complete documentation index at: https://developers.gotolstoy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI commands

> Every command of the Tolstoy CLI, with its flags, as `tolstoy <service> <command> --help` shows them.

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](https://developers.gotolstoy.com/agents/cli.md) 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.

```text theme={null}
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

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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

```text theme={null}
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).

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
USAGE:  tolstoy ai-widgets project-details [flags]

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

### ai-widgets publish-ai-widget-project

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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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

```text theme={null}
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

```text theme={null}
USAGE:  tolstoy folders list-folders [flags]

FLAGS:
  --team-id  
```

### folders rename-folder

Rename a Studio project or folder

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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).

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
USAGE:  tolstoy meta-ads list-pages [flags]

FLAGS:
  (no flags)
```

### meta-ads list-videos

List the videos already uploaded to one Meta ad account.

```text theme={null}
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

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
USAGE:  tolstoy products get-product-collections [flags]

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

### products get-product-filters

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

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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_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" | "seedream_v5_pro" | "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_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" | "seedream_v5_pro" | "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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
USAGE:  tolstoy studio get-remotion-templates [flags]

FLAGS:
  (no flags)
```

### studio get-studio-asset-comments

List team comments for a Studio image asset

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
USAGE:  tolstoy trends ad-spy-unsave-ad [flags]

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

### trends ad-spy-untrack-brand

Stop tracking a competitor brand

```text theme={null}
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.

```text theme={null}
USAGE:  tolstoy trends get-organic-search-status [flags]

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

### trends pinterest-inspiration

Search Pinterest for visual references

```text theme={null}
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

```text theme={null}
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.

```text theme={null}
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

```text theme={null}
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.

```text theme={null}
USAGE:  tolstoy video approve-v2 [flags]

FLAGS:
  --id  (required)
```

### video archive-v2

Archive a completed VodAssetV2 record.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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;
  };
```

### video list-dynamic-playlists

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

```text theme={null}
USAGE:  tolstoy video list-dynamic-playlists [flags]

FLAGS:
  (no flags)
```

### video list-playlists

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

```text theme={null}
USAGE:  tolstoy video list-playlists [flags]

FLAGS:
  (no flags)
```

### video query-dynamic-playlist

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

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
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.

```text theme={null}
USAGE:  tolstoy video unarchive-v2 [flags]

FLAGS:
  --id  (required)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.