Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (motata) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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:

Direct access token
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"

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