@bluevs/vhcli-tiktok-ads

English | 中文

English

TikTok Marketing API CLI — designed for AI agents and developers.

Installation

npm install -g @bluevs/vhcli-tiktok-ads

Authentication

Tokens are issued by vhcli (Vision Hub CLI). You do not need to handle access tokens directly.

# Fetch a token via vhcli and pass it to ttcli
TOKEN=$(vhcli project account-token \
  --customer-project-id=<PROJECT_ID> \
  --account-id=<ADVERTISER_ID> \
  --format=json | jq -r .access_token)

ttcli --token="$TOKEN" --advertiser-id=<ADVERTISER_ID> auth show

Or persist credentials for repeated use:

ttcli auth set --token="$TOKEN" --advertiser-id=<ADVERTISER_ID>

Mainland China users: TikTok's API requires a proxy. Set HTTPS_PROXY=http://127.0.0.1:7897 (or your local proxy port) before running any command.

Usage

ttcli [command] [flags]

Flags:
  --advertiser-id string   Advertiser ID (overrides env / config)
  --token string           Access token (overrides env / config)
  --human                  Human-readable output (default is JSON)

Output is JSON by default, suitable for piping and AI agent use. Pass --human for readable text.

Commands

| Command | Description | |---|---| | advertiser | Account balance, transactions, budget | | bc | Business Center: accounts, balance, payment portfolio | | campaign-label | Campaign labels / tags | | creative | Creative assets for DM Ads | | file | Ad file library (video, image upload) | | identity | Ad-publishing identities (Spark Ads) | | minis | TikTok Minis (small games / short dramas) | | optimizer | Automated rules | | report | Async reporting tasks | | smart-plus | Smart+ campaigns | | targeting | Interest / behavior / hashtag taxonomy | | tool | Utilities: geo, bid, device, timezone, url-validate, … | | tt-video | TikTok video posts authorized for Spark Ads | | user | Marketing API user info | | auth | Manage credentials | | schema | Dump full command tree (JSON) |

# Explore all commands
ttcli --help
ttcli <command> --help

# Dump full command tree for AI agents
ttcli schema | jq '.subcommands[] | {path, short}'

中文

TikTok 营销 API 命令行工具，专为 AI Agent 和开发者设计。

安装

npm install -g @bluevs/vhcli-tiktok-ads

鉴权

Token 由 vhcli（Vision Hub CLI）发证，无需手动处理 access_token。

# 通过 vhcli 获取 token 并传给 ttcli
TOKEN=$(vhcli project account-token \
  --customer-project-id=<项目ID> \
  --account-id=<广告主ID> \
  --format=json | jq -r .access_token)

ttcli --token="$TOKEN" --advertiser-id=<广告主ID> auth show

或持久化凭据，后续无需每次传入：

ttcli auth set --token="$TOKEN" --advertiser-id=<广告主ID>

国内用户：访问 TikTok API 需要代理。运行命令前设置 HTTPS_PROXY=http://127.0.0.1:7897（或本机代理端口）。

使用方式

ttcli [命令] [参数]

全局参数：
  --advertiser-id string   广告主 ID（覆盖环境变量 / 配置文件）
  --token string           访问令牌（覆盖环境变量 / 配置文件）
  --human                  人类可读输出（默认为 JSON）

默认输出 JSON，适合管道传递和 AI Agent 调用。加 --human 切换为易读文本。

命令列表

| 命令 | 说明 | |---|---| | advertiser | 账户余额、流水、预算 | | bc | Business Center：账户、余额、支付组合 | | campaign-label | 广告系列标签 | | creative | DM 广告创意素材 | | file | 广告素材库（视频、图片上传） | | identity | 广告发布身份（Spark Ads） | | minis | TikTok 小游戏 / 短剧 | | optimizer | 自动化规则 | | report | 异步报表任务 | | smart-plus | Smart+ 广告系列 | | targeting | 兴趣/行为/话题标签分类 | | tool | 工具集：地域、出价、设备、时区、URL 检测等 | | tt-video | 授权用于 Spark Ads 的 TikTok 视频 | | user | 营销 API 用户信息 | | auth | 管理凭据 | | schema | 输出完整命令树（JSON） |

# 查看所有命令
ttcli --help
ttcli <命令> --help

# 输出完整命令树（供 AI Agent 使用）
ttcli schema | jq '.subcommands[] | {path, short}'

License

MIT