tokei-agent

Control your Tokei 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.

Install

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

Requires Node 22+.

Related MCP server: substack-publisher-mcp

Quick start

1. Create an API key at tokei.io → Dashboard → Settings → API Keys. Pick read-only unless you need to change things; API access requires an active subscription or lifetime plan.

2. Export it — the syntax differs by 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. Try it:

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

Every 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).

Known issue — exit codes on Node 24 / Windows (fixed in 0.2.3). 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.

Commands

Read (any key):

Write (needs a read+write key):

Write 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 — the agent-oriented reference bundled in this package, with worked examples and error-handling guidance.

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>

MCP server

The 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.

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

Or in JSON config:

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

Environment

Agents, human in the loop

Tokei 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.

Docs

• API reference: https://tokei.io/docs/api

• OpenAPI spec: https://tokei.io/openapi.json

• Agent skill reference: SKILL.md

License

MIT