tokei-agent

tokei-agent

コマンドラインや、Claude Code、OpenClaw などの AI エージェントから、Tokei のローンチ前キャンペーンやウェイトリストキャンペーンを管理できます。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 キーを作成します。変更が必要な場合を除き、read-only を選択してください。API にアクセスするには、有効なサブスクリプションまたはライフタイムプランが必要です。

2. API キーをエクスポートします。構文はシェルによって異なります。

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

各コマンドは、トップレベルに rate_limit オブジェクトを含む JSON を標準出力に出力します。終了コードは、0 が成功、1 が API／ネットワークエラー、2 が使用方法のエラー（JSON を標準エラーに出力）です。

対話型出力（0.3.1 以降）。 標準出力が対話型ターミナルの場合、CLI はバナーと人間が読みやすい概要を表示し、生の JSON は表示しません。標準出力がパイプ、リダイレクト、CI、または mcp トランスポートの場合は、これまでどおり JSON のみを出力するため、エージェント、スクリプト、MCP クライアントへの影響はありません。ターミナルでも JSON を強制するには TOKEI_OUTPUT=json を設定してください。NO_COLOR を設定すると色とアニメーションが無効になり、TOKEI_NO_ANIM=1 を設定すると色はそのままに動きが止まります。

既知の問題 — Node 24／Windows での終了コード（0.3.0 で修正済み）。 0.2.2 以前では、CLI が正しい JSON 出力を表示した後、プロセス終了時に異常終了し、終了コードが壊れることがありました（成功時も失敗時も $LASTEXITCODE が -1073740791／0xC0000409 と表示されました）。該当するバージョンでは、終了ステータスではなく標準出力の JSON で実行結果を判断するか、アップグレードしてください。（過去のラベル表記ミス：0.3.0 の tarball では --version が 0.2.2 と誤って表示されていました。0.3.1 以降では正しく表示されます。）

コマンド

読み取り（任意のキー）：

コマンド	内容
me	キーを検証します。アカウント、プラン、API 使用状況を確認します
pages:list	ページを一覧表示します — --status、--mode、--page、--per-page
pages:get <contestId>	1 ページの全情報（賞品、報酬ティア、公開 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	所有するページ、名前付きテンプレート、またはスターターを複製してページを作成します。1 日あたり上限 20 件
media:upload <file>	画像または動画をアップロードし、pages:update 用の public_url を取得します。1 ファイルあたり 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 をご覧ください。

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）

エージェントと人間による確認

Tokei は、エージェントが下書きを作成し、人間が承認するように設計されています。監視エージェントには読み取り専用キーを付与し、実際に変更を行う必要があるエージェントにのみ読み取り＋書き込みキーを使用し、キーの有効期限を設定してください。API 経由で新しい Webhook サブスクリプションが作成されると、アカウント所有者にセキュリティ通知が送信されます。

プライバシーポリシー

ポリシー全文：https://tokei.io/privacy

データ収集に関する取り組み

tokei-agent は、Tokei v1 REST API のシンクライアントです。独自にデータを収集することはありません。テレメトリー、アナリティクス、クラッシュレポート、またはいかなる種類のホームへの通信もありません。

環境から読み取る入力は TOKEI_API_KEY と任意の TOKEI_API_URL の2つだけです。これに加えて、コマンドラインで渡す引数（または MCP クライアントがツール呼び出しに渡す引数）を読み取ります。media:upload では、指定したローカルファイルのバイトデータも読み取ります。

使用と保存

API キーは、Tokei アカウントへのリクエストで Authorization: Bearer ヘッダーとしてのみ使用されます。コマンドの引数は、リクエストのパス、クエリ文字列、または JSON 本文になります。ディスクへの書き込みはありません。CLI は設定ファイル、キャッシュ、認証情報ストア、ログファイルを作成せず、プロセス終了後に何も保持しません。

API レスポンスには、参加者のメールアドレス、アンケートの回答、アナリティクスが含まれることがあり、JSON 形式で stdout に出力されます。その時点から、CLI を呼び出したもの（シェル、スクリプト、または AI エージェントとその会話履歴）がデータを扱います。この出力は個人データとして取り扱ってください。

サードパーティとの共有

第三者への販売や共有はありません。データの送信先は次のとおりです。

• Tokei（https://tokei.io、または TOKEI_API_URL に設定したホスト）— ご自身のアカウントに対するリクエストを処理するため、すべてのコマンドで送信されます。
• Tokei のオブジェクトストレージプロバイダー — media:upload の場合のみです。CLI はファイルを Tokei API に送信し、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
• エージェントスキルのリファレンス：SKILL.md

ライセンス

MIT