tokenflex/ing
CLI · v1.16.0

The complete tokenflexing command glossary.

Every command, every flag, when to use it, and what it prints. The same scanner that powers the dashboard, runnable on its own. Reads local AI tool logs, prints per-source dollar + token breakdowns, ships an MCP server, and pairs your machine to your tokenflex.ing profile.

AI setup (recommended)

Primary path: paste the setup prompt from onboarding into Cursor / Claude Code / Command Code / Codex. The agent runs the command below; you only authenticate in the browser.

npx tokenflexing@latest connect --with-mcp --with-daemon

Advanced: raw connect, per-client install-hooks, or install-hooks --apply --all.

Quick start

Pick the row that matches your situation. Run the command. Done in under a minute on every path.

0 · Make sure Node.js is installed

Detected · your OS

Every tokenflexing command runs through npx, which ships with Node.js. Open a terminal and run this once to check what you have:

zsh
$node --version
→ expect v20 or higher
I don't have Node yet — show me how to install it⌃

Install Node.js

$# See https://nodejs.org/en/download for your platform
Download Node.js → nodejs.org/en/download
  • Brand-new machine — AI setup (recommended)
    npx tokenflexing@latest connect --with-mcp --with-daemon
    Or paste the AI setup prompt from /onboarding/device into your agent. Pairs, syncs, installs the daemon, wires MCP into every detected editor.
  • Already paired — push the latest scan
    tokenflexing sync
    Daemon-friendly. Pair this with `daemon --install` to make it automatic every hour.
  • Cursor user — one-time CSV import
    tokenflexing import-cursor ~/Downloads/usage.csv
    Cursor doesn't log tokens locally. CSV from cursor.com/dashboard → real numbers in your profile.
  • Cursor user — automate it hourly
    tokenflexing setup-cursor-auto
    Paste your cursor.com session cookie once. The hourly daemon refreshes Cursor data via CSV export — no more manual exports while the cookie stays valid.
  • Cursor user — instant pickup on each export
    tokenflexing watch-cursor
    Run in a terminal tab. Drop a fresh CSV into ~/Downloads and it imports within 500ms.
  • Multi-account on one machine
    tokenflexing profile use <name>
    Switch between personal and work accounts without re-pairing each time.
  • Set and forget — auto-stream every Claude Code tool call
    npx tokenflexing@latest install-hooks --apply
    Writes a PostToolUse hook into ~/.claude/settings.json. Every tool call your agent makes streams straight to your profile — no manual sync, no daemon. Pass --client cursor or --client claude-desktop to target other editors.
  • Let the agent run setup itself (MCP)
    npx tokenflexing@latest mcp
    Boots the tokenflexing MCP server. Register it in Command Code / Claude / Cursor / Claude Desktop so the agent itself can call setup_device, refresh_stats, install_daemon, install_hooks, and import_cursor_csv. Useful when you want the assistant to onboard you.

Reading data

Local-only commands. No network, no sign-in needed. Disk reads only.

  • tokenflexing

    Default. Prints all-time + window totals for every source with parsed usage data. Reads disk only — no network call.

    When · Quick check on the same machine. Aliased to `stats`.

    tokenflexing
  • tokenflexing stats

    Same as default. Explicit alias. Adds per-model breakdowns for measured sources, including Command Code and Claude Code.

    When · You want the explicit name in a script or alias.

    tokenflexing stats
  • tokenflexing scan

    Full device inventory. Walks 22 known AI-tool sources and reports three buckets: Measured (usage extracted), Detected (installed but no parser), Not found.

    When · First-time setup; auditing what you've actually installed; debugging why a tool isn't being counted.

    tokenflexing scan
  • tokenflexing flex

    Prints a shareable ASCII card with your all-time spend + token count + source mix + tokenflex.ing URL. Designed to drop into tweets, HN comments, or Slack standups.

    When · Brag rights. Or proof for a screenshot.

    tokenflexing flex

Setup & sync

Anything that touches ~/.config/tokenflexing/ or tokenflex.ing. Token storage is per-profile and chmod 600.

  • tokenflexing connect

    One-command setup. Runs scan → opens a browser tab for device pairing → saves the cloud token → pushes the first sync. Bundles login, scan, and sync.

    When · First-ever install on a new machine. Also re-pair a device that lost its token.

    npx tokenflexing@latest connect
  • tokenflexing login [--token <tok>]

    Pairs THIS machine to your tokenflex.ing account. Default flow: prints a one-time URL + 6-char code; you confirm in the browser; CLI polls until authorized and stores the token at `~/.config/tokenflexing/profiles/default/token` (chmod 600).

    When · Manually pairing a device (no scan or sync). Or migrating a token between machines.

    • --token <tok>Skip the browser flow and save the token directly. Useful for headless servers and CI.
    tokenflexing login --token tf_live_abc123...
  • tokenflexing logout

    Drops the local token from the active profile. Server-side `devices` row stays alive until revoked from /devices.

    When · Lending the machine. Resetting auth state. Switching between unrelated accounts.

    tokenflexing logout
  • tokenflexing profile <list|use> [name]

    Multi-account switcher. Each profile stores its own token under `~/.config/tokenflexing/profiles/<name>/token`. Active pointer at `~/.config/tokenflexing/active`.

    When · Running personal + work accounts on the same Mac. CI bots that pair as a service account.

    • listShow every saved profile and mark the active one.
    • use <name>Switch the active profile. Creates an empty profile if missing.
    tokenflexing profile use work
  • tokenflexing sync

    Pushes the latest scan output to `/api/sync/device` on tokenflex.ing. Updates `device_stats` rollup (all-time + today/week/month). Idempotent.

    When · After a manual scan when the daemon hasn't run yet. After importing a Cursor CSV.

    tokenflexing sync
  • tokenflexing import-cursor <csv>

    Reads a Cursor usage CSV exported from cursor.com/dashboard, parses v1/v2/v3 header formats, copies it to `~/.config/tokenflexing/cursor-usage.csv` (chmod 600), and folds it into the next scan as real tokens + cost.

    When · Cursor doesn't write per-message tokens to disk (subscription). CSV is the only path to real numbers when you don't want to set up cookie auth.

    tokenflexing import-cursor ~/Downloads/usage.csv
  • tokenflexing watch-cursor

    Foreground process. Watches `~/Downloads` for `cursor*.csv` / `usage*.csv` drops via fs.watch and auto-imports the moment one lands. 500ms debounce. Daemon picks up the import on its next hourly run.

    When · You want a Cursor CSV refresh to take effect within seconds rather than waiting for the next hourly sync. Leave it running in a tab while you click Export.

    tokenflexing watch-cursor
  • tokenflexing setup-cursor-auto

    One-time interactive flow. Asks for your `WorkosCursorSessionToken` cookie (you copy it from DevTools on cursor.com), stores it chmod 600 at `~/.config/tokenflexing/cursor-cookie`, then verifies it by fetching Cursor's usage-events CSV export. The hourly daemon refreshes that export while the cookie remains valid, so manual exports are unnecessary.

    When · You want fully automatic Cursor sync with no manual CSV export. Re-run when sync starts failing with 401.

    tokenflexing setup-cursor-auto

Agents & automation

MCP server, editor integrations, and hourly refresh scheduling.

  • tokenflexing mcp

    Starts a Model Context Protocol stdio server (protocol 2024-11-05). Exposes eight tools: three read-only local-stat tools (`get_my_stats`, `get_device_scan`, `get_flex_card`) plus five user-directed setup and refresh actions. The read tools work offline.

    When · You want an agent inside your editor to answer 'how much have I spent this week' without leaving chat. Usually wired in via `install-hooks` rather than run by hand.

    tokenflexing mcp
  • tokenflexing install-hooks --apply [--all|--client <name>]

    Edits the MCP servers list inside Command Code, Claude Code, Cursor, or Claude Desktop so `tokenflexing` shows up as a callable MCP. Without `--apply` it prints a dry-run diff. Prefer AI setup (`connect --with-mcp`) for first-time install.

    When · Advanced re-wire, or when an agent already has MCP and you want every editor updated in one shot.

    • --applyWrite changes. Without this, just print what would change.
    • --allWire Command Code, Claude Code, Cursor, and Claude Desktop in one pass.
    • --client <name>One of `command-code`, `claude-code` (default), `cursor`, `claude-desktop`, or `all`.
    tokenflexing install-hooks --apply --all
  • tokenflexing daemon [--install|--uninstall]

    Schedules an hourly refresh that runs `sync` and pushes to your profile. macOS uses a LaunchAgent at `~/Library/LaunchAgents/com.tokenflexing.sync.plist` and runs once when the agent loads at login; Windows uses Task Scheduler and Linux uses a systemd user timer. Logs go to `/tmp/tokenflexing-sync.log`.

    When · Set it once and forget it. Your dashboard stays current without you opening a terminal.

    • (no flag)Preview the plist / task command without writing anything.
    • --installBootouts any prior agent, writes the plist, bootstraps fresh.
    • --uninstallRemove the daemon + plist.
    tokenflexing daemon --install

Meta

  • tokenflexing --version | -V

    Prints the CLI version string. Useful for `--help` / bug reports.

    When · Confirming an upgrade landed. Filing an issue.

    tokenflexing --version
    1.16.0
  • tokenflexing --help | -h | help

    Single-screen reference of every command and a one-line blurb. This page is the long version.

    When · Forgot a flag mid-shell.

    tokenflexing --help

Tool support

What we parse, what's manual, what's on the roadmap. 25+ tools are detected by scan; only a subset has a parser today.

ToolHow it syncsStatus
Command CodeAuto · reads ~/.commandcode/**/*.jsonlMeasured
Claude CodeAuto · reads ~/.claude/projects/*.jsonlMeasured
Codex CLIAuto · reads ~/.codex/sessions/*.jsonMeasured
OpenCode (sst/opencode)Auto · reads ~/.local/share/opencode/storage/message/*.jsonMeasured
ClineAuto · reads local API events (tokens only; no cost)Measured
Roo CodeAuto · reads local API events (tokens + cost)Measured
Gemini CLIAuto · reads local chat logs (tokens incl. thoughts; no per-message cost)Measured
CursorCSV import or cookie-backed export required before usage is measuredSetup required
Aider · Kilo Code · Windsurf · Continue · Zed · Amp · Antigravity · Copilot · Goose · Kiro · Mux · Crush · Kimi · HermesDetected only — no usage parser yetDetected only
Claude Desktop · ChatGPT DesktopNo local usage parser in the current CLI (MCP installation is separate from measurement)Not scanned

Storage paths

Where the CLI writes things. All token files are chmod 600. Nothing leaves your machine unless you run sync or connect.

  • ~/.commandcode/mcp.jsonCommand Code user-scoped MCP servers (after install-hooks --client command-code).
  • ~/.config/tokenflexing/profiles/<name>/tokenPer-profile cloud-sync token (chmod 600).
  • ~/.config/tokenflexing/activeActive profile pointer. Edit via `profile use <name>`.
  • ~/.config/tokenflexing/cursor-usage.csvMost recent Cursor CSV (chmod 600). Re-parsed on every scan.
  • ~/.config/tokenflexing/cursor-cookieCursor session cookie for API replay (chmod 600). Set via `setup-cursor-auto`.
  • ~/.config/tokenflexing/cursor-api.jsonNormalized snapshot of last successful Cursor API fetch. Parser picks newer of this vs cursor-usage.csv.
  • ~/Library/LaunchAgents/com.tokenflexing.sync.plistmacOS daemon plist (after `daemon --install`).
  • /tmp/tokenflexing-sync.log + .errDaemon stdout / stderr.

Troubleshooting

  • `Unknown command: import-cursor`Your `tokenflexing` is older than 1.5.0. Run `npx tokenflexing@latest connect` or pin: `npx tokenflexing@1.16.0`. (Clear stale cache first: `rm -rf ~/.npm/_npx`.)
  • `launchctl bootstrap gui/501 ... file exists` on `daemon --install`Old agent is already loaded. Run `npx tokenflexing@latest daemon --uninstall`, then `npx tokenflexing@latest daemon --install`. (Fixed in 1.5.1 — bootout now runs first automatically.)
  • `Sync failed: invalid payload / token maybe expired. Re-run tokenflexing login.` (Windows + macOS)Two distinct causes share this message in older CLIs. (1) Token cleared or never written — re-run `npx tokenflexing@latest login`, then `npx tokenflexing@latest sync`. (2) On Windows the CLI sometimes reads the token from the wrong path when run from a non-default shell — re-run inside PowerShell instead of CMD, and confirm `%USERPROFILE%\.config\tokenflexing\auth.json` exists. (3) If you're on CLI <1.7, upgrade: `npx tokenflexing@latest --version` should print 1.8.x or newer.
  • `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src/win/async.c, line 94` (Windows)Node.js / libuv version mismatch — happens on Node 18.x or earlier on Windows. Upgrade to Node 20 LTS or 22: `winget install OpenJS.NodeJS.LTS`, restart your terminal, then `node --version` should print v20+. If you use `nvm-windows`: `nvm install 22 && nvm use 22`. Retry the command after upgrading.
  • Browser tab opens but pairing never completesOpen the URL the CLI printed in your default browser; the auth code is short-lived (~5 min). Retry the command if expired.
  • Cursor card on the dashboard shows `—`Cursor is subscription-billed; no local logs exist. Export the CSV from cursor.com/dashboard then run `npx tokenflexing@latest import-cursor <path>` followed by `npx tokenflexing@latest sync`.
  • MCP tools don't show up in Command Code / Claude Code / CursorPrefer AI setup, or run `npx tokenflexing@latest install-hooks --apply --all` (or `--client command-code` / `claude-code` / `cursor`). Restart the agent afterwards.

Still stuck? Open an issue at github.com/khadinakbarlabs/tokenflexing with the output of tokenflexing --version and tokenflexing scan.

Ready to wire it up?

npx tokenflexing@latest connect