tokei-agent

tokei-agent

通过命令行管理你的 Tokei 上线前和候补名单营销活动，也可以通过 Claude Code、OpenClaw 等 AI Agent 管理。封装 Tokei v1 REST API，仅输出 JSON，无运行时依赖。

安装

npm install -g tokei-agent
# or run without installing:
npx tokei-agent --help

需要 Node 22.12+。

Claude Code

将其作为插件安装，tokei-agent 技能也会随之安装——之后 Claude 无需额外说明，就能了解完整的命令用法：

/plugin marketplace add gilesdawe/tokei-agent
/plugin install tokei-agent@tokei

设置 TOKEI_API_KEY（参见快速入门）即可。CLI 本身仍通过 npx 运行，因此无需安装其他内容。

快速入门

1. 在 tokei.io → Dashboard → Settings → API Keys 中创建 API 密钥。除非需要更改内容，否则请选择只读；使用 API 需要有效订阅或终身套餐。

2. 导出密钥——不同 Shell 的语法有所不同：

export TOKEI_API_KEY=tokei_k_...          # bash / zsh

set -x TOKEI_API_KEY tokei_k_...          # fish

$env:TOKEI_API_KEY = "tokei_k_..."        # PowerShell

3. 试试看：

tokei-agent me                       # verify the key, see plan + API usage
tokei-agent pages:list --status active
tokei-agent stats <contestId>        # analytics for one page

每条命令都会将 JSON 输出到 stdout，其中包含顶层 rate_limit 对象。退出码：0 表示成功，1 表示 API/网络错误，2 表示用法错误（JSON 输出到 stderr）。

交互式输出（0.3.1+）。 当 stdout 连接到交互式终端时，CLI 会显示横幅和易读的摘要，而不是原始 JSON。当 stdout 是管道、重定向、CI 或 mcp 传输时，它会按原样输出 JSON——因此不会影响 Agent、脚本和 MCP 客户端。设置 TOKEI_OUTPUT=json 可在终端中也强制输出 JSON；NO_COLOR 会禁用颜色和动画，TOKEI_NO_ANIM=1 则保留颜色但停止动态效果。

已知问题——Node 24 / Windows 上的退出码问题（已在 0.3.0 中修复）。 在 0.2.2 及更早版本中，CLI 可能会输出正确的 JSON，然后在进程退出时中止，导致退出码错误（无论成功还是失败，$LASTEXITCODE 都会显示 -1073740791 / 0xC0000409）。如果使用的是受影响的版本，请根据 stdout 上的 JSON 判断运行结果，而不要依据退出状态——或者升级。 （历史标注错误：0.3.0 的 tarball 将 --version 错误报告为 0.2.2；0.3.1+ 会正确报告。）

命令

读取（任意密钥均可）：

命令	功能
me	验证密钥；查看账户、套餐和 API 使用情况
pages:list	列出页面 — --status、--mode、--page、--per-page
pages:get <contestId>	获取完整页面（奖品、奖励等级、公开 URL）
stats <contestId>	汇总分析数据
leaderboard <contestId>	按积分排名的参与者
referrals:top <contestId>	按转化量排名的顶级推荐者，以及推荐总数
winners:list <contestId>	选择运行历史记录，按时间从新到旧排列，并嵌套显示每次运行的获奖者
entries:list <contestId>	报名 — 使用 --email 筛选
surveys:list <contestId>	问卷回复
webhooks:list	列出 Webhook 订阅
templates:list	平台提供的命名起始模板，可用于 pages:clone --template
actions:catalog	Tokei 支持的所有报名操作类型 — --type <actionType>
events:catalog	Tokei 投递引擎可识别的所有 Webhook 事件 — --type <eventName>

写入（需要读写密钥）：

命令	功能
pages:clone	通过克隆你拥有的页面、命名模板或起始模板来创建页面。每天最多 20 次
media:upload <file>	上传图片或视频，返回可供 pages:update 使用的 public_url。每个文件（包括视频）不得超过 4MB
pages:update <contestId>	更新标题、描述、日期、奖品、奖励等级、外观（包括 Custom 模板：--template simple / --custom-css）、媒体和报名操作（entry_methods，包括自定义链接行）
pages:publish <contestId>	发布页面（需要设置未来的 end_date）
pages:unpublish <contestId>	恢复为草稿 — 阻止新用户报名，并对访客隐藏页面
entries:create <contestId>	添加一条报名
webhooks:create	订阅一个 HTTPS 端点（whsec_ 密钥仅显示一次 — 请保存！）
webhooks:delete <webhookId>	移除订阅

写入命令可通过标志传入简单字段，也可通过 --data '<json>' 或 --data @file.json 传入完整/嵌套内容（发生冲突时以标志为准）。运行 tokei-agent --help 查看所有标志，或参阅 SKILL.md — 此软件包附带的 Agent 参考文档，包含示例和错误处理指南。

tokei-agent pages:clone --title "Spring Launch Waitlist" --source <promotionId>
tokei-agent pages:update <contestId> --end-date 2026-09-01T00:00:00Z
tokei-agent media:upload ./hero.png
tokei-agent pages:update <contestId> --image-video <public_url from the upload above>
tokei-agent actions:catalog --type twitter_follow                  # see what a type accepts
tokei-agent pages:update <contestId> \
  --data '{"entry_methods":[{"actionType":"tiktok_follow","label":"Follow us on TikTok","points":3,"config":{"username":"tokei"}}]}'

MCP 服务

此软件包也可作为本地 MCP 服务（stdio）运行：上述每条命令都会变成一个 MCP 工具（pages_list、pages_update、stats 等），供 Claude Code、Claude Desktop 和其他 MCP 客户端使用。

claude mcp add tokei --env TOKEI_API_KEY=tokei_k_... -- npx -y tokei-agent mcp

或在 JSON 配置中：

{
  "mcpServers": {
    "tokei": {
      "command": "npx",
      "args": ["-y", "tokei-agent", "mcp"],
      "env": { "TOKEI_API_KEY": "tokei_k_..." }
    }
  }
}

环境

变量	必需	含义
TOKEI_API_KEY	是	以 Authorization: Bearer <key> 形式发送
TOKEI_API_URL	否	基础 URL 覆盖项（默认值为 https://tokei.io）

Agent 与人工参与

Tokei 的设计理念是由 Agent 起草、由人工审批：为监控 Agent 提供只读密钥，仅将读写密钥分配给确实需要修改内容的 Agent，并设置密钥过期时间。通过 API 创建新的 Webhook 订阅时，会向账户所有者发送安全通知。

隐私政策

完整政策：https://tokei.io/privacy

数据收集方式

tokei-agent 是 Tokei v1 REST API 的轻量客户端。它不会自行收集任何数据：没有遥测、没有分析、没有崩溃报告，也不会以任何方式向外发送数据。

它只会从你的环境中读取两项输入——TOKEI_API_KEY 和可选的 TOKEI_API_URL——以及你通过命令行传入的参数（或 MCP 客户端传给工具调用的参数）。对于 media:upload，它还会读取你指定的本地文件字节。

使用与存储

你的 API 密钥仅用作请求中发往你的 Tokei 账号的 Authorization: Bearer 标头。命令参数会成为请求路径、查询字符串或 JSON 请求体。它不会将任何内容写入磁盘：CLI 不会创建配置文件、缓存、凭据存储或日志文件，并且进程退出后不会保留任何内容。

API 响应可能包含参与者的电子邮件地址、问卷答案和分析数据，并会以 JSON 格式打印到标准输出。从这一刻起，这些内容由调用 CLI 的对象处理（你的 shell、脚本或 AI Agent 及其对话历史）。请将这些输出视为个人数据。

与第三方共享

不会出售或与第三方共享任何内容。数据只会传输至：

• Tokei（https://tokei.io，或你在 TOKEI_API_URL 中设置的主机）——每条命令都会向其发送请求，以便在你的账号中处理请求。
• Tokei 的对象存储提供商——仅用于 media:upload。CLI 会将文件发送到 Tokei API，由其与提供商一起存储；CLI 本身绝不会联系该提供商。该文件会成为你推广页面上的公开资源。

CLI 不会联系其他任何主机。

数据保留

CLI 不会保留任何内容。你 Tokei 账号中保存的数据——推广活动、条目、问卷答复——将按照上述 Tokei 隐私政策保留；你可以据此申请访问或删除数据。API 密钥由你在 Dashboard → Settings → API Keys 中创建、设定范围、设置过期时间并撤销；撤销密钥后，通过该密钥进行的所有访问都会立即停止。

联系信息

Tokei — https://tokei.io/privacy — [email protected]

文档

• API 参考：https://tokei.io/docs/api
• OpenAPI 规范：https://tokei.io/openapi.json
• Agent 技能参考：SKILL.md

许可证

MIT