{"id":"e16d3bfa-9a0e-4dcc-9b73-a8e6815aafd8","entityType":"agent","slug":"clawhub-gilesdawe-tokei-agent","name":"tokei-agent","canonicalUrl":"https://www.xpersona.co/agent/clawhub-gilesdawe-tokei-agent","canonicalPath":"/agent/clawhub-gilesdawe-tokei-agent","generatedAt":"2026-10-11T03:55:54.420Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T01:24:02.556Z","emptyReason":null},"description":"Tokei (tokei.io) is a pre-launch, waitlist and giveaway platform — launch pages, competition giveaways, sweepstakes, referral and viral-loop campaigns, Product Hunt launch drives, Gleam-style and KickoffLabs-style entry pages. This CLI controls them from the command line — list, clone, update, publish and unpublish pages, upload images and video, set prizes, reward tiers and deadlines, restyle pages, and read stats, leaderboards, top referrers, signups, survey responses, winner selections and the webhook event catalog, plus manage webhooks (all 5 events) — all via the Tokei v1 REST API.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17f49saxv9xfh8dt4h21w9pgs8ax0fm:tokei-agent","sourceUrl":"https://clawhub.ai/gilesdawe/tokei-agent","homepage":"https://clawhub.ai/gilesdawe/skills/tokei-agent","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/gilesdawe/tokei-agent","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/gilesdawe/skills/tokei-agent","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"tokei-agent technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T01:24:02.556Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T01:24:02.556Z","emptyReason":null},"stars":null,"forks":null,"downloads":1206,"packageName":null,"latestVersion":"0.3.6","tractionLabel":"1.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T01:24:02.491Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T01:24:02.556Z","lastCrawledAt":"2026-10-11T01:24:02.491Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T01:24:02.491Z","lastVerifiedAt":null,"highlights":[{"version":"0.3.6","createdAt":"2026-09-04T20:16:23.598Z","changelog":"- Removes deprecated skill-card.md file. - Updates dependencies in package.json. - Adjusts and expands tests in __tests__ directory. - Updates internal HTTP, MCP, and media handling logic. - Expands and clarifies documentation in SKILL.md.","fileCount":23,"zipByteSize":92184},{"version":"0.3.5","createdAt":"2026-08-28T02:03:56.756Z","changelog":"- Removed deprecated skill-card.md file. - Updated documentation in SKILL.md for clarity and completeness. - Updated CHANGELOG.md and package.json for version 0.3.5. - Minor test adjustments in src/__tests__/mcp.test.ts. - Small code and logic updates in src/index.ts and src/mcp.ts. - No breaking changes to core CLI usage or API envelope.","fileCount":23,"zipByteSize":90452},{"version":"0.3.4","createdAt":"2026-08-21T02:40:32.539Z","changelog":"tokei-agent 0.3.4 - Improved and updated documentation in SKILL.md, README.md, and CHANGELOG.md. - Minor updates to code and tests for maintainability. - Removed obsolete file: skill-card.md.","fileCount":23,"zipByteSize":87216},{"version":"0.3.3","createdAt":"2026-08-04T17:17:55.196Z","changelog":"tokei-agent 0.3.3 - Added full webhook event catalog and management, supporting all 5 event types. - Introduced a fourth hard rule: require explicit human approval before actions that affect entrants or alter public visibility. - Expanded documentation for the new rule and updated usage guidelines. - Added CHANGELOG.md; removed outdated skill-card.md. - Improved test coverage and clarified instructions in the README. - Minor dependency and code quality updates.","fileCount":23,"zipByteSize":84843},{"version":"0.3.2","createdAt":"2026-08-02T22:29:20.423Z","changelog":"- Added new referrals:top command to fetch top referrers for a campaign. - Updated documentation and examples to include the new referrals:top command and its JSON output structure. - Clarified and expanded README and SKILL.md, including notes about output envelope and updated command coverage. - Removed deprecated skill-card.md file. - General maintenance updates across code and tests.","fileCount":22,"zipByteSize":78001},{"version":"0.3.1","createdAt":"2026-08-02T16:53:45.239Z","changelog":"- Added human-friendly UI banner and summary when run in an interactive terminal; JSON output is now reserved for non-TTY (pipes, subprocesses, CI, or when TOKEI_OUTPUT=json). - Updated documentation to clarify the new output behavior and how agents/subprocesses always receive pure JSON. - Improved internal structure with new UI handling files and related tests. - Removed obsolete skill-card.md documentation.","fileCount":22,"zipByteSize":76789},{"version":"0.3.0","createdAt":"2026-07-26T22:04:46.015Z","changelog":"**Big update: Adds media upload support and revises workflow documentation.** - New `media:upload` command for uploading images and video, with an allowlisted URL returned for use on pages. - Strict enforcement: all media uploaded to pages must use `media:upload`—direct file paths or third-party URLs are rejected. - Extended documentation covering media handling, workflow patterns, and key error/plan checks. - Homepage updated, expanded README and SKILL.md, and improved field and workflow explanations. - Removed obsolete file (`skill-card.md`).","fileCount":20,"zipByteSize":56240},{"version":"0.2.2","createdAt":"2026-07-25T14:10:44.562Z","changelog":"- Added new test file: `src/__tests__/version.test.ts` - Updated documentation in README and SKILL.md, including new notes on exit codes for Node 24 / Windows - Improved and clarified sample output for `templates:list` in SKILL.md, with usage guidance and new illustrative section on skin appearances - Minor code changes across core files and tests - Removed obsolete `skill-card.md` file","fileCount":18,"zipByteSize":41478}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17f49saxv9xfh8dt4h21w9pgs8ax0fm:tokei-agent","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17f49saxv9xfh8dt4h21w9pgs8ax0fm:tokei-agent` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/gilesdawe/tokei-agent before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gilesdawe-tokei-agent/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gilesdawe-tokei-agent/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gilesdawe-tokei-agent/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-gilesdawe-tokei-agent/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-gilesdawe-tokei-agent/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-gilesdawe-tokei-agent/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T03:55:54.416Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gilesdawe-tokei-agent/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gilesdawe-tokei-agent/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gilesdawe-tokei-agent/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-gilesdawe-tokei-agent/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T01:24:02.556Z","emptyReason":null},"readme":"Skill: tokei-agent\n\nOwner: gilesdawe\n\nSummary: Tokei (tokei.io) is a pre-launch, waitlist and giveaway platform — launch pages, competition giveaways, sweepstakes, referral and viral-loop campaigns, Product Hunt launch drives, Gleam-style and KickoffLabs-style entry pages. This CLI controls them from the command line — list, clone, update, publish and unpublish pages, upload images and video, set prizes, reward tiers and deadlines, restyle pages, and read stats, leaderboards, top referrers, signups, survey responses, winner selections and the webhook event catalog, plus manage webhooks (all 5 events) — all via the Tokei v1 REST API.\n\nTags: latest:0.3.6\n\nVersion history:\n\nv0.3.6 | 2026-09-04T20:16:23.598Z | auto\n\n- Removes deprecated skill-card.md file.\n- Updates dependencies in package.json.\n- Adjusts and expands tests in __tests__ directory.\n- Updates internal HTTP, MCP, and media handling logic.\n- Expands and clarifies documentation in SKILL.md.\n\nv0.3.5 | 2026-08-28T02:03:56.756Z | auto\n\n- Removed deprecated skill-card.md file.\n- Updated documentation in SKILL.md for clarity and completeness.\n- Updated CHANGELOG.md and package.json for version 0.3.5.\n- Minor test adjustments in src/__tests__/mcp.test.ts.\n- Small code and logic updates in src/index.ts and src/mcp.ts.\n- No breaking changes to core CLI usage or API envelope.\n\nv0.3.4 | 2026-08-21T02:40:32.539Z | auto\n\ntokei-agent 0.3.4\n\n- Improved and updated documentation in SKILL.md, README.md, and CHANGELOG.md.\n- Minor updates to code and tests for maintainability.\n- Removed obsolete file: skill-card.md.\n\nv0.3.3 | 2026-08-04T17:17:55.196Z | auto\n\ntokei-agent 0.3.3\n\n- Added full webhook event catalog and management, supporting all 5 event types.\n- Introduced a fourth hard rule: require explicit human approval before actions that affect entrants or alter public visibility.\n- Expanded documentation for the new rule and updated usage guidelines.\n- Added CHANGELOG.md; removed outdated skill-card.md.\n- Improved test coverage and clarified instructions in the README.\n- Minor dependency and code quality updates.\n\nv0.3.2 | 2026-08-02T22:29:20.423Z | auto\n\n- Added new referrals:top command to fetch top referrers for a campaign.\n- Updated documentation and examples to include the new referrals:top command and its JSON output structure.\n- Clarified and expanded README and SKILL.md, including notes about output envelope and updated command coverage.\n- Removed deprecated skill-card.md file.\n- General maintenance updates across code and tests.\n\nv0.3.1 | 2026-08-02T16:53:45.239Z | auto\n\n- Added human-friendly UI banner and summary when run in an interactive terminal; JSON output is now reserved for non-TTY (pipes, subprocesses, CI, or when TOKEI_OUTPUT=json).\n- Updated documentation to clarify the new output behavior and how agents/subprocesses always receive pure JSON.\n- Improved internal structure with new UI handling files and related tests.\n- Removed obsolete skill-card.md documentation.\n\nv0.3.0 | 2026-07-26T22:04:46.015Z | auto\n\n**Big update: Adds media upload support and revises workflow documentation.**\n\n- New `media:upload` command for uploading images and video, with an allowlisted URL returned for use on pages.\n- Strict enforcement: all media uploaded to pages must use `media:upload`—direct file paths or third-party URLs are rejected.\n- Extended documentation covering media handling, workflow patterns, and key error/plan checks.\n- Homepage updated, expanded README and SKILL.md, and improved field and workflow explanations.\n- Removed obsolete file (`skill-card.md`).\n\nv0.2.2 | 2026-07-25T14:10:44.562Z | auto\n\n- Added new test file: `src/__tests__/version.test.ts`\n- Updated documentation in README and SKILL.md, including new notes on exit codes for Node 24 / Windows\n- Improved and clarified sample output for `templates:list` in SKILL.md, with usage guidance and new illustrative section on skin appearances\n- Minor code changes across core files and tests\n- Removed obsolete `skill-card.md` file\n\nv0.2.1 | 2026-07-22T23:39:18.301Z | auto\n\n- Added support for listing and cloning from named platform templates; new `templates:list` command and `pages:clone --template ` flag.\n- `pages:get` output and docs now include more fields, with clarified descriptions and new writeable fields via `pages:update`.\n- Improved status handling for `pages:list`, clarifying vocabulary and mapping.\n- Updated and expanded SKILL.md documentation for new commands, options, and field explanations.\n- Removed legacy `skill-card.md` file.\n- Added `server.json`; updated tests and source files for new features.\n\nv0.2.0 | 2026-07-20T23:21:37.406Z | auto\n\n- Added SKILL.md with comprehensive documentation for tokei-agent.\n- Introduced clear terminology mapping between API and UI concepts.\n- Detailed environment variable setup and error handling conventions.\n- Listed and explained all available commands for listing, updating, and managing Tokei campaigns, entries, stats, and webhooks.\n- Described support for running as a local MCP server for use as an MCP tool.\n\nArchive index:\n\nArchive v0.3.6: 23 files, 92184 bytes\n\nFiles: bin/tokei-agent.mjs (3225b), CHANGELOG.md (10016b), LICENSE (1073b), package.json (821b), README.md (9637b), server.json (1116b), skill-card.md (2661b), SKILL.md (49762b), src/__tests__/args.test.ts (1720b), src/__tests__/commands.test.ts (36931b), src/__tests__/http.test.ts (6498b), src/__tests__/mcp.test.ts (39214b), src/__tests__/media.test.ts (11228b), src/__tests__/ui.test.ts (17797b), src/__tests__/version.test.ts (1827b), src/args.ts (1352b), src/http.ts (6361b), src/index.ts (33029b), src/mcp.ts (34901b), src/media.ts (5141b), src/ui.ts (19384b), tsconfig.json (259b), _meta.json (130b)\n\nFile v0.3.6:SKILL.md\n\n---\nname: tokei-agent\ndescription: Tokei (tokei.io) is a pre-launch, waitlist and giveaway platform — launch pages, competition giveaways, sweepstakes, referral and viral-loop campaigns, Product Hunt launch drives, Gleam-style and KickoffLabs-style entry pages. This CLI controls them from the command line — list, clone, update, publish and unpublish pages, upload images and video, set prizes, reward tiers and deadlines, restyle pages, and read stats, leaderboards, top referrers, signups, survey responses, winner selections and the webhook event catalog, plus manage webhooks (all 5 events) — all via the Tokei v1 REST API.\nhomepage: https://tokei.io/agent\nmetadata: {\"openclaw\":{\"emoji\":\"⏱️\",\"requires\":{\"bins\":[],\"env\":[\"TOKEI_API_KEY\"]}}}\n---\n\n# tokei-agent\n\n`tokei-agent` is a zero-dependency CLI for the Tokei v1 REST API (`https://tokei.io/api/v1`). Every command prints JSON to stdout, so pipe it to `jq` or parse it directly.\n\n## Install tokei-agent if it isn't already there\n\n```sh\nnpm install -g tokei-agent\n# or run it without installing:\nnpx tokei-agent --help\n```\n\nRequires Node 22+. npm release: https://www.npmjs.com/package/tokei-agent — official website: https://tokei.io — agent docs: https://tokei.io/agent — API reference: https://tokei.io/docs/api\n\n---\n\n## ⚠️ Four hard rules (read first)\n\n**Rule 1 — Run `tokei-agent me` before anything else.** It proves the key is live and reports the account's **plan**. API access requires an active subscription or lifetime plan — **trial accounts get `403` on every command**, so a whole workflow can fail on its first call for a reason no other command explains.\n\n> `me` does **not** report the key's scope. There is no way to read a key's scope from the API — you discover a read-only key by getting `403 FORBIDDEN` on your first write. If the task involves changing anything, ask the human up front whether their key is read+write.\n\n**Rule 2 — Every media URL you write to a page MUST come from `tokei-agent media:upload`.** Raw filesystem paths (`hero.png`) and third-party URLs (`https://example.com/hero.png`) are **rejected** — the seven media fields on `pages:update` are guarded by a closed host allowlist that only accepts the app's own storage (and `res.cloudinary.com`). Always:\n\n```sh\nHERO=$(tokei-agent media:upload ./hero.png | jq -r '.data.public_url')\ntokei-agent pages:update \"$PAGE_ID\" --image-video \"$HERO\"\n```\n\nEvery `--image-video` / `--og-image` / `--background-image` example below assumes a `public_url` obtained this way — never a local file.\n\n**Rule 3 — List fields replace wholesale; always read before you write.** `prizes` (max 20) and `reward_thresholds` (max 50) are **not** merged — whatever array you send becomes the entire list, so sending one prize deletes the other nineteen. The pattern is always `pages:get` → modify the array → `pages:update` with the complete list.\n\n**Rule 4 — Get explicit human approval before any action that emails people or changes anything public.** Publishing a page, creating a webhook that fires on live events, sending entries/notifications, or anything else visible to entrants or third parties needs a human sign-off first — this CLI does not gate those calls for you, so you are the gate. Read-only commands (`me`, `pages:list`, `pages:get`, `stats`, `leaderboard`, `referrals:top`, `entries:list`, `surveys:list`, `winners:list`, `webhooks:list`, `templates:list`, `actions:catalog`, `events:catalog`) need no such approval.\n\n---\n\n## Terminology mapping (read this first)\n\nThe API and the UI use different words for the same objects. Do not treat these as different things.\n\n| API says | UI / humans say | Notes |\n| ---------------------- | ------------------ | ---------------------------------------------------------------- |\n| `contest` | page, campaign | The core object. `contestId` in paths = the page's id. |\n| `promotion` | page, campaign | Same object again — `POST /promotions` creates it, reads live under `/contests/{id}`. |\n| `entry` | signup, subscriber | One person joining a page. |\n| `entries:create` | add a signup | |\n\nCLI command names use the UI words (`pages:list`, `pages:update`); the JSON they return uses the API words (`contest`, `promotion`).\n\n## Setup\n\n| Env var | Required | Meaning |\n| --------------- | -------- | -------------------------------------------------------------------------------- |\n| `TOKEI_API_KEY` | Yes | Sent as `Authorization: Bearer `. Create one at tokei.io → Dashboard → Settings → API Keys. |\n| `TOKEI_API_URL` | No | Base URL override (default `https://tokei.io`). |\n\nKeys have a scope: **read-only** or **read+write**. Write commands need a read+write key; a read-only key gets `403`. Keys can also carry an expiry — an expired key gets `401`. Prefer a read-only key unless the task actually changes something.\n\n## Core workflow\n\nThe fundamental pattern, end to end:\n\n1. **Verify** — confirm the key and the plan (Rule 1)\n2. **Discover** — list your pages, and the platform's named starting points\n3. **Create** — clone a template (or one of your own pages) into a new draft\n4. **Prepare** — upload media and get back allowlisted URLs (Rule 2)\n5. **Shape** — PATCH copy, dates, prizes, appearance and media onto the page\n6. **Publish** — flip the draft live (needs a future `end_date`)\n7. **Monitor** — stats, leaderboard, top referrers, signups\n8. **Automate** — subscribe a webhook instead of polling\n\n```sh\n# 1. Verify — do this first, always\ntokei-agent me\n\n# 2. Discover\ntokei-agent pages:list --status active\ntokei-agent templates:list\n\n# 3. Create (returns a draft page)\nPAGE=$(tokei-agent pages:clone --title \"Spring Launch Waitlist\" \\\n --template product-hunt | jq -r '.data.id')\n\n# 4. Prepare media (Rule 2 — never pass a raw path)\nHERO=$(tokei-agent media:upload ./hero.png | jq -r '.data.public_url')\n\n# 5. Shape\ntokei-agent pages:update \"$PAGE\" \\\n --description \"Join the list for early access.\" \\\n --template showcase --dark-mode true --primary-color \"#7d78c6\" \\\n --image-video \"$HERO\"\n\n# 6. Publish (end_date must be in the future — set it in the same call if unset)\ntokei-agent pages:publish \"$PAGE\" --data '{\"end_date\":\"2026-09-01T00:00:00Z\"}'\n\n# 7. Monitor\ntokei-agent stats \"$PAGE\"\ntokei-agent leaderboard \"$PAGE\" --per-page 10\ntokei-agent referrals:top \"$PAGE\" --per-page 10\ntokei-agent entries:list \"$PAGE\"\n\n# 8. Automate — events:catalog lists all 5 subscribable events and their payloads\ntokei-agent webhooks:create --url https://yourserver.com/webhooks/tokei \\\n --events entry.created,winner.selected\n```\n\nConfirm every write by reading it back with `pages:get \"$PAGE\"` — everything writable is also readable.\n\n## Output envelope, exit codes\n\n- stdout: the API's JSON body, augmented with a top-level `\"rate_limit\"` object: `{\"limit\": n, \"remaining\": n, \"reset\": }`, or `null` when the headers were absent (e.g. network failure).\n- **Agents always get this JSON.** From 0.3.1 the CLI renders a human banner and summary *only* when stdout is an interactive terminal. A subprocess, pipe, redirect, CI environment or the `mcp` transport has no TTY, so the JSON envelope below is what you will receive, byte for byte. If you ever need to force it explicitly, set `TOKEI_OUTPUT=json`.\n- Exit code `0` — success (HTTP 2xx).\n- Exit code `1` — API or network error. The API's JSON error body (same envelope, with `rate_limit`) is still printed on stdout; pure network failures print `{\"ok\": false, \"error\": {\"type\": \"network_error\", \"message\": ...}}`.\n- Exit code `2` — usage error (bad flags, missing arguments, missing `TOKEI_API_KEY`). Printed as JSON on **stderr**: `{\"ok\": false, \"error\": {\"type\": \"usage_error\", \"message\": ...}}`. Nothing was sent to the API.\n\n**The shape, so you can `jq` it without guessing.** Success always nests the payload under `data` — it is never a bare top-level array:\n\n```jsonc\n// single-object reads (pages:get, me, media:upload, pages:clone, …)\n{ \"success\": true, \"data\": { … }, \"rate_limit\": { … } }\n\n// list reads (pages:list, leaderboard, referrals:top, entries:list,\n// surveys:list, templates:list, webhooks:list)\n// referrals:top adds a sibling \"totals\" object next to data + pagination\n{ \"success\": true, \"data\": [ … ],\n \"pagination\": { \"page\": 1, \"per_page\": 20, \"total_pages\": 3, \"total_count\": 47 },\n \"rate_limit\": { … } }\n\n// errors\n{ \"success\": false,\n \"error\": { \"code\": \"VALIDATION_ERROR\", \"message\": \"…\", \"status\": 422,\n \"details\": [{ \"field\": \"end_date\", \"message\": \"…\" }] },\n \"rate_limit\": { … } }\n```\n\nSo the idioms are:\n\n```sh\ntokei-agent pages:list | jq -r '.data[0].id' # first page's id\ntokei-agent pages:list | jq -r '.data[] | select(.status==\"active\") | .id'\ntokei-agent pages:list --per-page 100 | jq '.pagination.total_pages' # more to fetch?\ntokei-agent pages:get \"$PAGE\" | jq -r '.data.public_url'\ntokei-agent media:upload ./hero.png | jq -r '.data.public_url'\ntokei-agent pages:update \"$PAGE\" --title x | jq -r '.error.details[]?.field'\n```\n\n`templates:list`, `me` and `winners:list` are unpaginated — they return `data` with no `pagination` key (`winners:list`'s `data` is still an array, just capped rather than paged; see its entry below). `events:catalog` and `actions:catalog` return `data` as an object (or one entry, with `--type`), not an array at all.\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 (read — any key)\n\n**`me`** — verify the key, see plan and API usage. Returns `user_id`, `email`, `plan`, `active_contests` and an `api_usage` block (`requests_today`, `daily_limit`, `rate_limit_per_minute`). Not the key's scope — see Rule 1.\n\n```sh\ntokei-agent me\n```\n\n**`pages:list`** — list your pages. Flags: `--status draft|active|completed|deleted`, `--mode competition|gamification|sharing_only`, `--page `, `--per-page <1-100>`. The filter values are exactly the values a page's `status` field can hold, so what you read back is what you can filter on. There is no `ended` or `paused` status; those were accepted by older builds and always returned nothing.\n\n`status` — both the field and the filter — is the **effective** status, derived from the stored value **and the dates**: a page whose `end_date` has passed reads and filters as `completed`, and one whose `start_date` is still in the future reads as `draft`. A creator can mark a page completed by hand, but nothing does so when `end_date` passes, so before 2026-07-27 an ended page nobody closed manually reported `active` indefinitely. `status: \"active\"` now genuinely means live — trust it.\n\n```sh\ntokei-agent pages:list --status active --per-page 20\n```\n\n**`pages:get `** — one page, full object. `title` is the **visible page headline**, not the internal dashboard name, so what you read is what a visitor sees. The object also carries:\n\n| Field | Meaning |\n| ----- | ------- |\n| `total_entries` | Count of entry **actions** (`contest_entries` rows) — not people, and not points. **Never narrate this as \"signups.\"** |\n| `total_points_awarded` | Sum of points earned across all entry actions. Not a headcount either. |\n| `status` | The **effective** status (see `pages:list` above) — `completed` once `end_date` passes, whatever is stored. Safe to report as \"live\" / \"finished\" directly. |\n| `days_left` | Whole days remaining, computed from `end_date` at read time; **`0` means it has ended**, and the partial final day rounds up so a page closing tonight reads `1`. Only falls back to the stored column when there is no `end_date` at all. Before 2026-07-27 this replayed a stale stored value and could say `30` on a page with a day to go. |\n| `entry_methods[].points` | What each action **actually awards**, including any per-action override the owner configured. Safe to quote to a user. |\n| `description`, `prizes`, `reward_thresholds` | Everything `pages:update` can write, so you can read-modify-write. |\n| `public_url` | The live page URL — no second call needed. **Can be `null`** when the page has no slug yet (`contest_url` null); check before handing it to your user as a link. |\n| `primary_color` | Brand colour as a CSS value (e.g. `#7d78c6`); `null` means the template default. `settings.color` is a deprecated alias of it. |\n| `card_width` | `max-w-2xl` \\| `max-w-3xl` \\| `max-w-4xl` \\| `max-w-7xl`; `null` renders as `max-w-2xl`. |\n| `settings.template` | Page skin: `basic-new`, `showcase` or `future`. |\n| `image_video` | Hero media — an image **or** a video URL. May carry dimension hints as query params. Writable via `pages:update --image-video` (get the URL from `media:upload`). |\n| `secondary_image` … `fifth_image`, `background_image`, `og_image` | The page's other media slots; `null` when unset. Each writable via its own `pages:update` flag — see the media flags note under `pages:update` below. |\n| `campaign_name`, `project_name` | **Read-only.** `project_name` is the small subheading under the headline; `campaign_name` is the internal dashboard name and never appears on the page. |\n\n`primary_color`, `card_width`, `settings.template` and all seven media fields (`image_video`, `secondary_image`, `third_image`, `fourth_image`, `fifth_image`, `background_image`, `og_image`) are now writable via `pages:update` (see below); `dark_mode_enabled` writes through `--dark-mode` there too, though it isn't itself a field in this table. `campaign_name`/`project_name` remain read-only always. If your user wants a headcount (\"how many people entered\"), that's neither `total_entries` nor `total_points_awarded` — use `stats`'s `unique_participants` instead.\n\n```sh\ntokei-agent pages:get 4e7a1c0e-8b2d-4f6a-9c3e-2d5b8a7f1e90\n```\n\n**`stats `** — aggregated analytics for a page.\n\n```sh\ntokei-agent stats 4e7a1c0e-8b2d-4f6a-9c3e-2d5b8a7f1e90\n```\n\n**`leaderboard `** — participants ranked by points. Flags: `--page`, `--per-page <1-100>`.\n\n```sh\ntokei-agent leaderboard 4e7a1c0e-8b2d-4f6a-9c3e-2d5b8a7f1e90 --per-page 10\n```\n\n**`referrals:top `** — the page's top referrers, ranked by converted referrals then total referrals. Flags: `--page`, `--per-page <1-100>`.\n\nEach row carries `referrer_id`, `referral_code`, `full_name`, `email`, `total_referrals`, `converted_referrals` and `bonus_points_earned`. Alongside `data` and `pagination` the response adds a `totals` object: `total_referrers`, `total_referrals`, `total_clicks`, `converted_clicks`, `click_conversion_rate` (a percentage, one decimal place).\n\nThree things to know before you report these numbers:\n\n- Only entrants who have actually referred someone appear. Every participant is issued a referral code, so an unfiltered list would be almost entirely zero rows.\n- `converted_referrals` counts referred people who went on to complete at least one entry action *other than* sharing — it is the ranking key, and it is the number worth reporting as \"referrals that worked\".\n- `bonus_points_earned` is a **count of bonus entries, not a points total**, despite the name. The name matches the underlying data and the dashboard, so it is kept for consistency; do not present it as points.\n\n```sh\ntokei-agent referrals:top 4e7a1c0e-8b2d-4f6a-9c3e-2d5b8a7f1e90 --per-page 10\n```\n\n**`winners:list `** — selection-run history for a page, newest first, each run with its persisted winners nested. Read-only, no query params, no pagination (contest-scale run/winner counts, capped at 100 runs — headroom, not a pagination story). Finalize-via-API is deliberately out of scope (human-approval policy, Rule 4) — this is how an agent looks back at what a run actually selected, not how it draws one. Each run carries `id`, `created_at`, `seed`, `algorithm_version`, `status`, `requested_by_email`, `finalized_at`, `total_candidates`, `total_winners_selected`, `winners_count` and a `winners` array; each winner carries `id`, `contest_user_id`, `email`, `full_name`, `entry_points`, `created_at`, `country_name`, `city`, `prize_tier`, `prize_description`, `prize_value`, `selected_at`, `notified_at`, `notification_method`, `verified`, `claimed_at`.\n\n```sh\ntokei-agent winners:list 4e7a1c0e-8b2d-4f6a-9c3e-2d5b8a7f1e90\n```\n\n**`entries:list `** — signups for a page. Flags: `--page`, `--per-page <1-100>`, `--email ` (exact-match filter).\n\n```sh\ntokei-agent entries:list 4e7a1c0e-8b2d-4f6a-9c3e-2d5b8a7f1e90 --email fan@example.com\n```\n\n**`surveys:list `** — survey responses. Flags: `--page`, `--per-page <1-100>`.\n\n```sh\ntokei-agent surveys:list 4e7a1c0e-8b2d-4f6a-9c3e-2d5b8a7f1e90 --page 2\n```\n\n**`webhooks:list`** — list webhook subscriptions. Reading them needs no write scope (only `webhooks:create`/`webhooks:delete` do). Flags: `--page`, `--per-page <1-100>`. Watch `failure_count`: a subscription is auto-disabled after 10 consecutive failed deliveries.\n\n```sh\ntokei-agent webhooks:list\n```\n\n**`templates:list`** — the platform's named starting points, for cloning with `pages:clone --template `. Same list for every key — not scoped to your account (it's platform content, not the caller's). No flags, no pagination.\n\n```sh\ntokei-agent templates:list\n```\n\nExample response — an **excerpt** of the real menu at the time of writing (15 templates live, 5 shown). It grows as the platform publishes templates, so call `templates:list` and use the slugs it returns; never hardcode one.\n\n```json\n{\n \"success\": true,\n \"data\": [\n {\n \"id\": \"0e4de06c-8915-4e1c-ba3f-48f6c9a098f2\",\n \"slug\": \"collect-email-list\",\n \"name\": \"Collect email list — registration-first opt-in subscriber page\",\n \"skin\": \"future\",\n \"entry_method_count\": 0\n },\n {\n \"id\": \"06743256-2e8e-4ede-a431-f17866fae1f6\",\n \"slug\": \"competition-starter\",\n \"name\": \"Starter — Gleam-style competition giveaway (X, Instagram, TikTok, Facebook entries)\",\n \"skin\": \"basic-new\",\n \"entry_method_count\": 6\n },\n {\n \"id\": \"c0cc71a0-1ff5-46ab-8a23-c801aec30337\",\n \"slug\": \"instagram-engagement\",\n \"name\": \"Instagram engagement — follow & share photo giveaway\",\n \"skin\": \"showcase\",\n \"entry_method_count\": 3\n },\n {\n \"id\": \"6ca0bdbc-23d8-4c79-a894-857eea485fbe\",\n \"slug\": \"secret-codes\",\n \"name\": \"Secret Code — unlock entries with a code (QR codes, receipts, printed inserts, events)\",\n \"skin\": \"basic-new\",\n \"entry_method_count\": 0\n },\n {\n \"id\": \"88fde228-8baf-4b31-9b0e-cc243b3cc83d\",\n \"slug\": \"steam-promotion\",\n \"name\": \"A futuristic Steam template for Adding to Steam Wishlists and Playing Steam Games.\",\n \"skin\": \"future\",\n \"entry_method_count\": 6\n }\n ],\n \"rate_limit\": { \"limit\": 60, \"remaining\": 59, \"reset\": 1753000000 }\n}\n```\n\nRows come back sorted by `slug`, unpaginated. The other ten at the time of writing: `discord-community`, `facebook-promotion`, `family-friends`, `prelaunch-vips`, `product-hunt`, `survey-system`, `tiktok-growth`, `twitch-growth`, `x-followers`, `youtube-contest`.\n\n`skin` is the page skin (`basic-new`/`showcase`/`future`) — the same vocabulary `pages:update --template` writes. `entry_method_count` is how many entry actions the template ships with. For agents: **list templates first, then clone by slug** — don't guess a slug. A `0` there is not always a stub — two templates legitimately report `0` because their action lives on the page rather than in `entry_methods`: `secret-codes` (the single action *is* the secret code) and `survey-system` (a mandatory survey plus a photo upload). Cloning `secret-codes` gives you the code input switched on but **no codes** — codes are stored per page and are never copied, so the owner adds their own in the dashboard.\n\nWhat the skins look like — use this to match the user's reference point:\n\n- `basic-new` (\"Basic\") — the classic giveaway card: entry actions in a clean vertical list, soft pastel styling. This is the format popularized by Gleam — when a user asks for a Gleam-style (or KickoffLabs-style) campaign, this is the closest match. The platform default.\n- `showcase` — a dynamic two-column layout with warm colors and platform-styled buttons. Product-forward — the natural fit for a Product Hunt-style launch page.\n- `future` — a dark, immersive game-style skin for bold, high-impact pages (gaming and tech audiences).\n\n**`actions:catalog`** — every entry-action type Tokei supports: label, description, default points, platform, whether it's trust-based/verifiable, and — for the 26 types writable as an `entry_methods` row — the exact `config` fields `pages:update` accepts for that type. This is the **authoritative** per-type reference; nothing below restates it. Same list for every key (not scoped to your account, no pagination). Flags: `--type ` (a value matching no action type is `400`).\n\n```sh\ntokei-agent actions:catalog --type twitter_follow\n```\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"label\": \"Follow on X\",\n \"defaultPoints\": 3,\n \"platform\": \"twitter\",\n \"trustBased\": false,\n \"isEntryMethodRow\": true,\n \"fields\": [\n { \"key\": \"username\", \"type\": \"string\", \"required\": true,\n \"note\": \"X/Twitter handle. Checked for presence only — no format validation.\" }\n ],\n \"needs\": \"Requires participant X/Twitter OAuth to be configured on this deployment...\"\n }\n}\n```\n\nA field's `group` marks alternatives — write the FIRST field of the group; the rest are claim-validator aliases that satisfy validation but render a dead button on their own (each carries a `note` saying so). `isEntryMethodRow: false` means the type is not writable as an `entry_methods` row at all (it's enabled via a contest setting or a dedicated route instead) — `needs` says which.\n\n**`events:catalog`** — every webhook event Tokei's delivery engine understands: description, `payloadSchema` (the exact shape of the `data` field a subscriber receives), `emitSites` and whether it's `subscribable`. This is the **authoritative** payload reference for `webhooks:create` — read it before assuming a field exists in a delivery. Same list for every key (not scoped to your account, no pagination). Flags: `--type ` (a value matching no event type is `400`). All 5 events are `subscribable: true` this stage — every one has a real emit site (see Webhooks below).\n\n```sh\ntokei-agent events:catalog --type winner.selected\n```\n\n## Commands (write — need a read+write key)\n\n**`pages:clone`** — create a page by cloning one you own (`--source `), a named platform template by slug (`--template ` — get slugs from `templates:list`), or omit both to clone the platform starter template. `--template` and `--source` are **alternatives, not combinable** — sending both is `422`; a `--template` slug matching no template is `404`. Template, theme, and entry methods copy verbatim from the source — keep one polished master page per shape and clone it. Capped at **20 API-created pages per account per UTC day** (429 with `Retry-After`). Flags: `--title` (required), `--source`, `--template`, `--description`, `--prize`, `--end-date `, `--campaign-url`, `--image-url`, `--status draft|active`, `--idempotency-key`, `--data`.\n\n```sh\ntokei-agent pages:clone --title \"Spring Launch Waitlist\" \\\n --source 4e7a1c0e-8b2d-4f6a-9c3e-2d5b8a7f1e90 \\\n --prize \"Lifetime license\" --end-date 2026-09-01T00:00:00Z \\\n --idempotency-key spring-launch-2026\n```\n\nCloning from a named template instead — list first, then clone by slug:\n\n```sh\ntokei-agent templates:list\ntokei-agent pages:clone --title \"Spring Launch Waitlist\" --template product-hunt \\\n --prize \"Lifetime license\" --end-date 2026-09-01T00:00:00Z\n```\n\n`--status active` makes the page live immediately at the returned `public_url`; the default is `draft`. Reuse an `--idempotency-key` and you get `409` with the existing page's id in `error.details` instead of a duplicate.\n\n**`media:upload `** — upload an image or video and get back a `public_url` to feed into `pages:update`'s media flags (below). Two HTTP calls under the hood, both handled for you: (1) request a short-lived signed upload ticket from Tokei; (2) `PUT` the file bytes straight to a Supabase Storage host with **no `Authorization` header** — the signing token lives in that URL's own query string. Nothing is stored until step 2 succeeds, so a step-1 failure never burns anything. Content type is inferred from the file extension (`.jpg`/`.jpeg`/`.png`/`.gif`/`.webp`/`.mp4`/`.webm`/`.mov`); override it with `--content-type ` for an extensionless or misnamed file. `application/pdf` is not accepted — only image and video. Prints `{public_url, path, content_type, filename, size_bytes}` under `data`.\n\n```sh\ntokei-agent media:upload ./hero.png\ntokei-agent pages:update 4e7a1c0e-8b2d-4f6a-9c3e-2d5b8a7f1e90 \\\n --image-video https://media.tokei.io/api-uploads/u1/.png\n```\n\nThings that surprise agents:\n\n- **The 5MB bucket cap applies to the signed-upload bucket itself, not to image vs. video specifically — so video must be ≤5MB too.** This is thin for video; a real clip is likely to exceed it. There is no larger-upload path through this API today.\n- **The 50/day cap counts tickets issued (step 1), not completed uploads.** A step-1 call that never gets PUT still burns quota — don't loop calling `media:upload` speculatively.\n- **A file over 5MB fails at step 2 with a `413` from Supabase Storage, not from Tokei.** The CLI surfaces this as `{\"ok\": false, \"error\": {\"type\": \"upload_failed\", \"stage\": \"storage_put\", \"status\": 413, \"message\": \"...\"}}` — see the error-semantics note below; it is a different shape from the usual `error.code` envelope because it isn't a Tokei API response.\n- **The stored object name is always a server-generated UUID.** The `filename` you send (or that the CLI infers from your local path) is validated and echoed back in the response, but never used to name anything — so reusing a filename never collides or overwrites.\n\n**`pages:update `** — PATCH a page. Simple fields via flags: `--title`, `--description`, `--start-date `, `--end-date `, `--template basic-new|showcase|future|simple`, `--custom-css `, `--dark-mode true|false`, `--primary-color \"#7d78c6\"`, `--card-width narrow|medium|wide`, and the seven media flags below. Prizes, reward tiers, nulls, or a full body via `--data`. At least one field required; unknown fields are rejected (422). `prizes` (max 20) and `reward_thresholds` (max 50) each **replace the existing list wholesale** — read the current lists with `pages:get` first, modify, and send the complete list back (Rule 3). A future `start_date` pauses new entries until then; setting `end_date` recomputes `days_left` — but a page whose winners have already been drawn rejects any `end_date` write, **setting or clearing**, with `409 WINNERS_ALREADY_SELECTED`. Clearing the date via `--data '{\"end_date\": null}'` also requires the page to be unpublished: an **active** page must keep a deadline (otherwise it renders as live forever while every signup is rejected), so clearing one returns `422` on field `end_date` — send `{\"status\": \"draft\", \"end_date\": null}` together, or a replacement date. `--title` sets the visible page headline (and the dashboard name), and `--description` accepts basic rich-text HTML which is sanitized on write, so unsupported tags come back stripped.\n\nAppearance flags: `--template` is the page skin (`basic-new`, `showcase` or `future`), stored verbatim as `settings.template` — see the skin guide under `templates:list` for what each looks like and when to pick it. `--dark-mode` is a plain creator-side toggle (column `dark_mode_enabled`) — there is no visitor `prefers-color-scheme` behavior, so this is the only thing that controls it. `--primary-color` must be a hex colour only (3, 4, 6 or 8 digits, e.g. `\"#7d78c6\"`) — other CSS colour formats (`rgb()`, named colours) are rejected because the value is interpolated into the page's server-rendered `