{
  "markdown": "# tokei-agent\n\nControl your [Tokei](https://tokei.io) pre-launch and waitlist campaigns from the command line — and from AI agents like Claude Code and OpenClaw. Wraps the Tokei v1 REST API with JSON-only output, zero runtime dependencies.\n\n## Install\n\n```sh\nnpm install -g tokei-agent\n# or run without installing:\nnpx tokei-agent --help\n```\n\nRequires Node 22+.\n\n### Claude Code\n\nInstall it as a plugin and the `tokei-agent` skill comes with it — Claude then\nknows the whole command surface without being told:\n\n```\n/plugin marketplace add gilesdawe/tokei-agent\n/plugin install tokei-agent@tokei\n```\n\nSet `TOKEI_API_KEY` (see [Quick start](#quick-start)) and you're done. The CLI\nitself still runs via `npx`, so there is nothing else to install.\n\n## Quick start\n\n1. Create an API key at [tokei.io](https://tokei.io) → Dashboard → Settings → API Keys. Pick **read-only** unless you need to change things; API access requires an active subscription or lifetime plan.\n\n2. Export it — the syntax differs by shell:\n\n```sh\nexport TOKEI_API_KEY=tokei_k_...          # bash / zsh\n```\n\n```fish\nset -x TOKEI_API_KEY tokei_k_...          # fish\n```\n\n```powershell\n$env:TOKEI_API_KEY = \"tokei_k_...\"        # PowerShell\n```\n\n3. Try it:\n\n```sh\ntokei-agent me                       # verify the key, see plan + API usage\ntokei-agent pages:list --status active\ntokei-agent stats <contestId>        # analytics for one page\n```\n\nEvery command prints JSON to stdout with a top-level `rate_limit` object. Exit codes: `0` success, `1` API/network error, `2` usage error (JSON on stderr).\n\n> **Interactive output (0.3.1+).** When stdout is an interactive terminal, the CLI renders a banner and a human-readable summary instead of raw JSON. When stdout is a pipe, a redirect, CI, or the `mcp` transport, it prints exactly the JSON it always has — so agents, scripts and MCP clients are unaffected. Set `TOKEI_OUTPUT=json` to force JSON at a terminal too; `NO_COLOR` disables colour and animation, and `TOKEI_NO_ANIM=1` keeps the colour but stops the movement.\n\n> **Known issue — exit codes on Node 24 / Windows (fixed in 0.3.0).** On 0.2.2 and earlier the CLI could print its correct JSON output and then abort during process exit, corrupting the exit code (`$LASTEXITCODE` read `-1073740791` / `0xC0000409` on success and failure alike). On an affected version, judge a run by the JSON on stdout, not by the exit status — or upgrade. (Historical labelling slip: the 0.3.0 tarball misreported `--version` as `0.2.2`; 0.3.1+ reports correctly.)\n\n## Commands\n\nRead (any key):\n\n| Command                    | Does                                                        |\n| -------------------------- | ----------------------------------------------------------- |\n| `me`                       | Verify the key; account, plan, API usage                    |\n| `pages:list`               | List pages — `--status`, `--mode`, `--page`, `--per-page`   |\n| `pages:get <contestId>`    | One page in full (prizes, reward tiers, public URL)         |\n| `stats <contestId>`        | Aggregated analytics                                        |\n| `leaderboard <contestId>`  | Participants ranked by points                               |\n| `referrals:top <contestId>`| Top referrers ranked by conversions, plus referral totals   |\n| `winners:list <contestId>` | Selection-run history, newest first, with each run's winners nested |\n| `entries:list <contestId>` | Signups — filter with `--email`                             |\n| `surveys:list <contestId>` | Survey responses                                            |\n| `webhooks:list`            | List webhook subscriptions                                  |\n| `templates:list`           | The platform's named starting points, for `pages:clone --template` |\n| `actions:catalog`          | Every entry-action type Tokei supports — `--type <actionType>`     |\n| `events:catalog`           | Every webhook event Tokei's delivery engine understands — `--type <eventName>` |\n\nWrite (needs a read+write key):\n\n| Command                       | Does                                                                     |\n| ----------------------------- | ------------------------------------------------------------------------ |\n| `pages:clone`                 | Create a page by cloning one you own, a named template, or the starter. 20/day cap |\n| `media:upload <file>`         | Upload an image or video, get back a `public_url` for `pages:update`. ≤5MB per file (video too) |\n| `pages:update <contestId>`    | Update title, description, dates, prizes, reward tiers, appearance (incl. the Custom template: `--template simple` / `--custom-css`), media, and entry actions (`entry_methods`, incl. custom-link rows) |\n| `pages:publish <contestId>`   | Take a page live (needs a future `end_date`)                             |\n| `pages:unpublish <contestId>` | Back to draft — blocks new signups, but the page still renders publicly  |\n| `entries:create <contestId>`  | Add a signup                                                             |\n| `webhooks:create`             | Subscribe an HTTPS endpoint (`whsec_` secret shown once — save it!)      |\n| `webhooks:delete <webhookId>` | Remove a subscription                                                    |\n\nWrite commands take simple fields as flags and full/nested bodies via `--data '<json>'` or `--data @file.json` (flags win on conflict). Run `tokei-agent --help` for every flag, or see [SKILL.md](./SKILL.md) — the agent-oriented reference bundled in this package, with worked examples and error-handling guidance.\n\n```sh\ntokei-agent pages:clone --title \"Spring Launch Waitlist\" --source <promotionId>\ntokei-agent pages:update <contestId> --end-date 2026-09-01T00:00:00Z\ntokei-agent media:upload ./hero.png\ntokei-agent pages:update <contestId> --image-video <public_url from the upload above>\ntokei-agent actions:catalog --type twitter_follow                  # see what a type accepts\ntokei-agent pages:update <contestId> \\\n  --data '{\"entry_methods\":[{\"actionType\":\"tiktok_follow\",\"label\":\"Follow us on TikTok\",\"points\":3,\"config\":{\"username\":\"tokei\"}}]}'\n```\n\n## MCP server\n\nThe package doubles as a local MCP server (stdio): every command above becomes an MCP tool (`pages_list`, `pages_update`, `stats`, …) for Claude Code, Claude Desktop, and other MCP clients.\n\n```sh\nclaude mcp add tokei --env TOKEI_API_KEY=tokei_k_... -- npx -y tokei-agent mcp\n```\n\nOr in JSON config:\n\n```json\n{\n  \"mcpServers\": {\n    \"tokei\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tokei-agent\", \"mcp\"],\n      \"env\": { \"TOKEI_API_KEY\": \"tokei_k_...\" }\n    }\n  }\n}\n```\n\n## Environment\n\n| Variable        | Required | Meaning                                          |\n| --------------- | -------- | ------------------------------------------------ |\n| `TOKEI_API_KEY` | Yes      | Sent as `Authorization: Bearer <key>`            |\n| `TOKEI_API_URL` | No       | Base URL override (default `https://tokei.io`)   |\n\n## Agents, human in the loop\n\nTokei is built so agents draft and humans approve: give monitoring agents a read-only key, reserve read+write keys for agents that genuinely need to change things, and set key expiry. New webhook subscriptions created via the API trigger a security notification to the account owner.\n\n## Privacy Policy\n\nFull policy: https://tokei.io/privacy\n\n### Data collection practices\n\n`tokei-agent` is a thin client for the Tokei v1 REST API. It collects no data of\nits own: there is no telemetry, no analytics, no crash reporting, and no\nphone-home of any kind.\n\nIt reads exactly two inputs from your environment — `TOKEI_API_KEY` and the\noptional `TOKEI_API_URL` — plus the arguments you pass on the command line (or\nthe arguments an MCP client passes to a tool call). For `media:upload` it also\nreads the bytes of the local file you name.\n\n### Usage and storage\n\nYour API key is used solely as an `Authorization: Bearer` header on requests to\nyour Tokei account. Command arguments become the request path, query string, or\nJSON body. Nothing is written to disk: the CLI creates no config file, cache,\ncredential store, or log file, and holds nothing after the process exits.\n\nAPI responses — which can include entrant email addresses, survey answers, and\nanalytics — are printed as JSON to stdout. From that point they are handled by\nwhatever invoked the CLI (your shell, your scripts, or your AI agent and its\nconversation history). Treat that output as the personal data it is.\n\n### Third-party sharing\n\nNothing is sold or shared with third parties. Data is transmitted only to:\n\n- **Tokei** (`https://tokei.io`, or the host you set in `TOKEI_API_URL`) — every\n  command, to serve your request against your own account.\n- **Tokei's object storage provider** — `media:upload` only. The API returns a\n  short-lived signed upload URL and the CLI PUTs your file bytes straight to it;\n  the file becomes a public asset on your promotion page.\n\nThe CLI contacts no other host.\n\n### Data retention\n\nThe CLI retains nothing. Data held in your Tokei account — promotions, entries,\nsurvey responses — is retained under the Tokei privacy policy above, and you can\nrequest access or deletion there. API keys are created, scoped, expired, and\nrevoked by you at Dashboard → Settings → API Keys; revoking a key immediately\nstops all access through it.\n\n### Contact information\n\nTokei — https://tokei.io/privacy — support@tokei.io\n\n## Docs\n\n- API reference: https://tokei.io/docs/api\n- OpenAPI spec: https://tokei.io/openapi.json\n- Agent skill reference: [SKILL.md](./SKILL.md)\n\n## License\n\nMIT\n",
  "bytes": 9577,
  "sha": "75a24450a067d106b436634d463a1d194245a4aa12315607272ce21ad1c75667",
  "repo_slug": "gilesdawe/tokei-agent",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gilesdawe_tokei_agent_95e57c1a/readme"
}