kolplanet CLI

kolplanet 是一个零依赖的 Node.js CLI，用来封装 KOLPlanet CRM 的 Market Discovery HTTP 接口，方便在终端、脚本或后续 Codex skill 中直接调用。

当前支持的能力：

• login -> POST /auth/login
• list-influencers -> GET /influencers
• contact-influencer -> GET /contact_influencers
• list-filter-options -> GET /filter_options/:type

特性

• 零依赖，基于 Node 18+ 内置 fetch
• 支持 kolplanet login 并自动持久化本地 JWT
• 同时支持 kebab-case 命令和 Go 风格方法名别名
• 后续请求自动复用本地保存的 base_url + jwt token
• 统一支持 --base-url、--token、--token-file
• 过滤器支持 --filter、--filter-file、--filter-stdin
• 支持重复 --set key=value，便于动态拼装查询参数
• stdout 始终输出 JSON，适合 shell 脚本和 AI skill 继续消费

运行要求

• Node.js >=18
• npm >=9（建议）

本地安装

在仓库根目录执行：

npm install
npm link

安装后可直接使用：

kolplanet --help

如果你只是想在另一个本地项目中引用这个 CLI，也可以直接安装当前目录：

npm install /absolute/path/to/kolplanet-cli

配置

环境变量：

export KOLPLANET_BASE_URL="https://crm.example.com"
export KOLPLANET_TOKEN="<crm-jwt-token>"
export KOLPLANET_TOKEN_FILE="$HOME/.kolplanet.crm.token"

默认本地登录态文件：

~/.kolplanet/auth.json

也可以通过 KOLPLANET_AUTH_FILE 覆盖。

默认值：

• --base-url 默认是 https://testapi.kolplanet.com
• list-influencers 的 --per-page 默认是 10

快速开始

1. 登录

首次使用建议先登录：

kolplanet login \
  --base-url "$KOLPLANET_BASE_URL" \
  --username "your_crm_username"

也可以一次性传入密码：

kolplanet login \
  --base-url "$KOLPLANET_BASE_URL" \
  --username "your_crm_username" \
  --password "your_password"

登录成功后，JWT 会被保存到本地；后续命令会自动复用。如果查询时 JWT 为空，CLI 会提示先执行 kolplanet login。

2. 查询达人

最小调用：

kolplanet list-influencers --base-url "$KOLPLANET_BASE_URL"

传完整 filter JSON：

kolplanet list-influencers \
  --filter '{"platform":"Instagram","keyword":"#beauty"}'

用 --set 动态组装：

kolplanet list-influencers \
  --platform Instagram \
  --set keyword='#beauty' \
  --set followers='{"range":[100000,200000]}' \
  --paged 1 \
  --per-page 20

从 stdin 读取 filter：

echo '{"platform":"Youtube","keyword":"gaming"}' | \
kolplanet list-influencers --filter-stdin

筛选建议：

• 分类、相关、话题、标签类语义搜索优先使用 keyword
• 纯文本主题词可用 --set keyword=beauty
• Hashtag / 相关标签可用 --set keyword='#beauty'
• 如果只是找某个话题相关的 KOL，优先尝试 keyword，再考虑 topics、text_tags、influencer_interest

例如筛选印尼美妆相关、粉丝 10 万到 20 万的 Instagram KOL：

kolplanet list-influencers \
  --base-url https://testapi.kolplanet.com \
  --platform Instagram \
  --set influencer_loc='["304751"]' \
  --set followers='{"range":[100000,200000]}' \
  --set keyword='#beauty' \
  --per-page 5 \
  --compact

3. 查询联系方式

kolplanet contact-influencer \
  --id Instagram/17841461846042365

如果是 creator 侧逻辑：

kolplanet contact-influencer \
  --id Tiktok/728393838 \
  --type creators

4. 查询筛选项

kolplanet list-filter-options language

按关键词搜索：

kolplanet list-filter-options search \
  --q makeup \
  --platform instagram

按多个 ID 查询：

kolplanet list-filter-options topic-tags \
  --id Instagram/123 \
  --id Instagram/456

命令别名

为了和 Go 方法名保持一致，CLI 同时支持以下别名：

kolplanet CrmLogin ...
kolplanet Login ...
kolplanet ListInfluencers ...
kolplanet ContactInfluencer ...
kolplanet ListFilterOptions ...

开发

常用命令：

npm test
npm run pack:dry-run

项目结构：

bin/   CLI 入口
lib/   核心实现
test/  Node 原生测试

如果准备公开发布到 GitHub 或 npm，建议在发布前确认：

• 仓库地址、issue 地址等元信息已经填入 package.json
• 许可证已经明确，不再保持 UNLICENSED
• 远端 CI 能在目标 Node 版本上稳定通过

面向 Skill 的约定

• stdout 读取 JSON 结果
• stderr 仅用于错误和 --verbose 请求日志
• 建议先执行一次 kolplanet login，后续直接复用本地登录态
• 敏感 token 优先使用 KOLPLANET_TOKEN_FILE 或环境变量
• 复杂筛选优先使用 --filter-stdin 或重复 --set

License

当前 package.json 中仍标记为 UNLICENSED。如果这个仓库将作为公开开源项目发布，建议在 push 前补上明确的开源许可证并同步更新元信息。