motata-cli

motata is a modular ads operations CLI for Meta and TikTok.

It focuses on the workflows that usually break in real accounts:

• discovering usable Pages, Instagram identities, and pixels
• validating promotable objects before asset creation
• uploading media, including chunked video upload for larger files
• creating campaigns, ad sets, ads, and creatives
• inspecting insights and targeting options
• migrating assets across ad accounts with resumable jobs
• managing TikTok advertiser accounts, identity assets, targeting, insights, campaigns, ad groups, ads, creatives, and media assets through the official SDK
• exposing raw Meta error details instead of hiding them behind wrappers

Why This CLI Exists

motata is designed for direct execution against ads APIs with a practical bias toward:

• account portability
• debuggability
• batch safety
• migration reliability

It does not implement browser-based OAuth flows.

Installation

From PyPI:

pip install motata-cli

From npm:

npm install -g motata

The npm package bootstraps a local Python virtualenv during install, so python3 must be available on the target machine.

The TikTok Business SDK is bundled inside motata-cli, so you do not need to install it separately.

From source:

pip install -e .

Python 3.11+ is required.

Authentication

motata supports two auth paths:

1. Direct access token
2. Skill-assisted token retrieval

Direct Token

Pass a platform access token to any command:

motata meta campaigns list \
  --account 766290062019765 \
  --access-token "$META_ACCESS_TOKEN"

You can also set META_ACCESS_TOKEN or MOTATA_META_ACCESS_TOKEN in your shell and omit --access-token.

Skill-Assisted Token Retrieval

Use the motata token skill to fetch the account-scoped token, then pass the resulting access token to motata with --access-token.

The published package also bundles the same helper as a standalone command, so installation stays self-contained:

motata-token \
  --mode account \
  --account-id 1015303836971442 \
  --api-key "$AUTH_CENTER_API_KEY"

Legacy alias still works:

motata-auth-center-token ...

Once you have the token, call motata directly:

motata meta campaigns list \
  --account 1015303836971442 \
  --access-token "$META_ACCESS_TOKEN"

For TikTok, use the same pattern with TIKTOK_ACCESS_TOKEN or MOTATA_TIKTOK_ACCESS_TOKEN:

motata tiktok campaigns list \
  --advertiser-id 7444033053753835536 \
  --access-token "$TIKTOK_ACCESS_TOKEN"

Quick Start

Product

Scrape a product or app page into normalized name, price, and image URLs:

motata product scrape \
  "https://www.anker.com/products/a1695-anker-power-bank-25000mah-165w"

Build a strategy-ready intake with page signals, headline candidates, CTA hints, and execution guidance:

motata product intake \
  "https://www.anker.com/products/a1695-anker-power-bank-25000mah-165w"

Meta

Discover account assets:

motata meta assets discover \
  --account 766290062019765 \
  --access-token "$META_ACCESS_TOKEN"

List campaigns:

motata meta campaigns list \
  --account 766290062019765 \
  --access-token "$META_ACCESS_TOKEN" \
  --limit 25

Validate whether a creative can be attached to an ad set:

motata meta validate ad-link \
  --account 766290062019765 \
  --access-token "$META_ACCESS_TOKEN" \
  --adset-id <ADSET_ID> \
  --creative-id <CREATIVE_ID> \
  --cleanup

Classify the advertiser vertical from top-spend accounts, campaigns, landing pages, and app-store evidence:

motata meta user-type analyze \
  --access-token "$META_ACCESS_TOKEN" \
  --date-preset last_14d \
  --account-limit 10 \
  --campaign-limit 10

For TikTok, use the matching read-only classifier:

motata tiktok user-type analyze \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --advertiser-limit 10 \
  --campaign-limit 10

Upload a video with an explicit thumbnail:

motata meta videos upload \
  --account 766290062019765 \
  --access-token "$META_ACCESS_TOKEN" \
  --file ./video.mp4 \
  --thumbnail ./thumb.jpg \
  --name "demo-video"

Upload a larger video with automatic chunked upload:

motata meta videos upload \
  --account 766290062019765 \
  --access-token "$META_ACCESS_TOKEN" \
  --file ./large-video.mp4 \
  --name "large-demo-video"

TikTok

List normal campaigns:

motata tiktok campaigns list \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN"

Create a normal campaign with minimal flags:

motata tiktok campaigns create \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --name "TikTok Prospecting" \
  --objective-type TRAFFIC \
  --budget-mode BUDGET_MODE_DAY \
  --budget 100

Create a SmartPlus campaign:

motata tiktok smartplus-campaigns create \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --name "SmartPlus Scale" \
  --objective-type WEB_CONVERSIONS \
  --budget-mode BUDGET_MODE_TOTAL \
  --budget 150

For SmartPlus app promotion, motata now normalizes iOS dedicated-campaign fields, keeps the App Profile Page state consistent, converts source snapshots into create-safe budget settings, and preflights app_info so it can stop early when advanced_dedicated_campaign_allowed=false.

If you have an App Profile Page asset, pass its ID with --page-id when creating or copying SmartPlus app campaigns.

If you already have an App Profile Page, you can pass its page_id directly to SmartPlus ad create/update with --page-id; the CLI converts it into the page_list payload TikTok expects.

For SmartPlus copy flows where you want to keep the app promotion structure but avoid Advanced Dedicated Campaign and App Profile Page, use --copy-route normal.

Bootstrap a SmartPlus app campaign from the best matching template:

motata tiktok smartplus-campaigns bootstrap-app \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --name "SmartPlus App Scale" \
  --app-id <APP_ID> \
  --dry-run

List ad groups under TikTok:

motata tiktok adgroups list \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --page-size 20

Inspect TikTok advertiser account details:

motata tiktok accounts info \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN"

Discover TikTok preflight assets:

motata tiktok assets discover \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN"

Validate a TikTok website promoted object before create:

motata tiktok validate promoted-object \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --objective-type WEB_CONVERSIONS \
  --promotion-type WEBSITE \
  --placement PLACEMENT_TIKTOK \
  --pixel-id <PIXEL_ID> \
  --optimization-event INITIATE_ORDER \
  --landing-page-url "https://example.com"

List usable TikTok posting identities:

motata tiktok identities list \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --page-size 20

Query TikTok regions and targeting helpers:

motata tiktok targeting regions \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --language en

Run a TikTok integrated report:

motata tiktok insights get \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --report-type BASIC \
  --data-level AUCTION_AD \
  --dimension stat_time_day \
  --metric spend \
  --metric impressions \
  --start-date 2026-04-15 \
  --end-date 2026-04-15

List SmartPlus ads:

motata tiktok smartplus-ads list \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --page-size 20

Upload a TikTok video asset:

motata tiktok videos upload \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --file ./video.mp4 \
  --name "tt-demo-video"

Inspect a TikTok image asset:

motata tiktok images info \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  <IMAGE_ID>

List AIGC voices:

motata tiktok aigc voices \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --page-size 20

Submit an Image to Video task:

motata tiktok aigc image-animation create \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --image-url "https://example.com/product-hero.jpg" \
  --change-background \
  --background-prompt "Simple backdrop" \
  --animation-prompt "Product demo" \
  --provider-model GOKU \
  --video-generation-count 2

Check Image to Video task status and generated videos:

motata tiktok aigc image-animation tasks \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --task-id <TASK_ID>

motata tiktok aigc image-animation list \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --task-id <TASK_ID>

Submit a VOICEOVER or AVATAR_PRODUCT task:

motata tiktok aigc video create \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --type VOICEOVER \
  --payload-file /path/to/voiceover_create_task.json

motata tiktok aigc video create \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --type AVATAR_PRODUCT \
  --payload-file /path/to/avatar_product_create_task.json

Bootstrap a minimal AIGC task directly from a product page:

motata tiktok aigc video create \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --type VOICEOVER \
  --product-url "https://www.anker.com/products/a1695-anker-power-bank-25000mah-165w" \
  --input-video-id <VIDEO_ID>

motata tiktok aigc video create \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --type AVATAR_PRODUCT \
  --product-url "https://www.anker.com/products/a1695-anker-power-bank-25000mah-165w" \
  --avatar-id <AVATAR_ID> \
  --input-video-id <VIDEO_ID>

For VOICEOVER and AVATAR_PRODUCT, motata now maps product-page bootstrap onto TikTok's product_video_info payload. Use --input-video-id to pass existing source clips, and --input-image-url to override the product page image list when needed.

Query AIGC video tasks and outputs by type:

motata tiktok aigc video tasks \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --type VOICEOVER \
  --task-id <TASK_ID>

motata tiktok aigc video list \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --type VOICEOVER \
  --task-id <TASK_ID>

List digital avatars and create a digital avatar video:

motata tiktok aigc digital-avatar list \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --tag-type identity \
  --tag real

motata tiktok aigc digital-avatar task-create \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --payload-file /path/to/digital_avatar_create_task.json

motata tiktok aigc digital-avatar task-get \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  <TASK_ID>

motata tiktok aigc digital-avatar videos \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --start-date 2026-04-01 \
  --end-date 2026-04-21

motata tiktok aigc digital-avatar rename-video \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --avatar-video-id <AVATAR_VIDEO_ID> \
  --file-name "spring-ugc-cut"

Use raw payloads when you need fields not exposed as dedicated CLI flags:

motata tiktok smartplus-campaigns create \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  --payload-file /path/to/smartplus-campaign.json

Use the payload examples above and the bundled motata-token helper when you want a known-good starting point for:

• SmartPlus website conversion flow
• Manual app promotion flow
• AIGC voice, image-animation, and digital-avatar flows

Normal TikTok ad updates support partial autofill for a single ad. If you pass an ad_id, motata will fetch the current ad, hydrate the required creative fields, then apply your override:

motata tiktok ads update \
  --advertiser-id 1234567890123456789 \
  --access-token "$TIKTOK_ACCESS_TOKEN" \
  1862625263782337 \
  --name "Renamed creative"

You can still pass --payload-json or --creatives-json; the autofilled creative becomes the base and your explicit fields win.

Command Surface

Top-level commands:

• product
• meta
• tiktok

Highlights:

• product scrape
• product intake
• meta assets discover, meta assets promotable-pages, meta assets pixels
• meta campaigns|adsets|ads|creatives list|get|create|update
• meta pages list, meta pages instagram
• meta insights get
• meta targeting interests|suggestions|locations|behaviors|demographics|estimate
• meta validate creative|ad-link|promoted-object
• meta migrate plan|run|status|resume
• meta debug graph
• tiktok campaigns list|get|create|update|status
• tiktok smartplus-campaigns list|get|create|update|status|bootstrap-app
• tiktok adgroups list|get|create|update|status
• tiktok smartplus-adgroups list|get|create|update|status
• tiktok ads list|get|create|update|status
• tiktok smartplus-ads list|get|create|update|status
• tiktok accounts list|info|inspect|update
• tiktok creative-assets portfolio list|get|create|select|inspect|export|match-campaign
• tiktok creative-assets asset delete|share
• tiktok creative-assets share-link|smart-text
• tiktok creatives list|get|create|share-link|smart-text
• tiktok identities list|create|video-info
• tiktok targeting regions|search|info|list
• tiktok insights get|smartplus-overview|smartplus-breakdown
• tiktok media upload-image|upload-video
• tiktok images upload|info
• tiktok videos upload|info|search
• tiktok aigc voices
• tiktok aigc image-animation create|tasks|list
• tiktok aigc video create|tasks|list
• tiktok aigc digital-avatar list|task-create|task-get|videos|rename-video
• tiktok assets discover|image-info|video-info|video-search|delete|share
• tiktok validate creative|ad-link|promoted-object

Module Layout

The CLI is now split by platform and responsibility:

• motata_cli.__main__: root entrypoint and parser bootstrap
• motata_cli/meta/commands.py: Meta operational commands
• motata_cli/tiktok/sdk.py: bundled TikTok SDK loader with vendored fallback
• motata_cli/tiktok/client.py: thin TikTok API adapter
• motata_cli/tiktok/commands.py: TikTok CLI command layer

Validation Behavior

Before sending create or update payloads, motata performs local checks for common operator mistakes, including:

• invalid budget combinations
• invalid bid strategy requirements
• malformed targeting payloads
• invalid tracking specs
• invalid conversion domains
• missing required promoted object fields for certain optimization goals

For ad set targeting, the CLI also normalizes targeting payloads to preserve Meta compatibility where needed.

Video Upload Behavior

Video upload supports:

• normal upload for smaller files
• chunked upload for larger files
• retry logic for retryable network and Meta API errors
• explicit thumbnail upload
• automatic thumbnail extraction when requested

Migration

motata meta migrate is intended for cross-account recreation flows where IDs, Pages, pixels, creatives, videos, and ads need to be rebuilt safely.

Typical flow:

motata meta migrate export --help
motata meta migrate plan --help
motata meta migrate run --help
motata meta migrate resume --help

Recommended workflow:

motata meta migrate export \
  --export-dir /tmp/meta-export-campaign-123 \
  --source-account-id 1234567890 \
  --campaign-id 120000000000000001 \
  --source-access-token "$ACCESS_TOKEN"

motata meta migrate plan \
  --export-dir /tmp/meta-export-campaign-123 \
  --source-account-id 1234567890 \
  --target-account-id 0987654321 \
  --target-access-token "$ACCESS_TOKEN"

motata meta migrate run \
  --export-dir /tmp/meta-export-campaign-123 \
  --source-account-id 1234567890 \
  --target-account-id 0987654321 \
  --page-id 111111111111111 \
  --pixel-id 222222222222222 \
  --source-access-token "$ACCESS_TOKEN" \
  --target-access-token "$ACCESS_TOKEN"

The export step writes the migration package expected by plan and run:

• asset-tree.json
• creatives.raw.json
• export-manifest.json

For app promotion or Sales migrations, run can also remap promotable app fields before any real writes:

• --target-application-id
• --target-object-store-url
• --promoted-object-overrides '{"application_id":"...","object_store_url":"..."}'

migrate run now performs a target promoted-object preflight before recreating creatives, campaigns, and ad sets. If Meta rejects the mapped page/pixel/app combination, the CLI stops early with a validation error instead of failing later in the main write path.

Debugging

For low-level troubleshooting, use:

motata meta debug graph --help

This is useful when you want raw Meta API responses and error payloads.

Project Notes

• The package entrypoint is motata
• The package name is motata-cli
• The internal product spec is kept in motata-cli-spec.md