tokenflex/ing
CLI · v1.8.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.

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, never used tokenflexing
    npx tokenflexing@latest connect
    Installs the CLI, pairs the device, scans, syncs. One command. Done.
  • Already paired — push the latest scan
    tokenflexing sync
    Daemon-friendly. Pair this with `daemon --install` to make it automatic at 6 AM.
  • 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 daily
    tokenflexing setup-cursor-auto
    Paste your cursor.com session cookie once. Daemon refreshes Cursor data daily via API — no more manual exports.
  • 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 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 per parsed source (Claude Code, Codex CLI, Cursor if you've imported the CSV). 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 a per-model breakdown for Claude Code (input / cached / output / thinking tokens, cost).

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

    tokenflexing stats
  • tokenflexing scan

    Full device inventory. Walks 25+ known AI-tool storage paths and reports three buckets: Measured (token counts 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 run.

    When · You want a Cursor CSV refresh to take effect within seconds rather than waiting for 6 AM. 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`, immediately verifies by hitting `cursor.com/api/auth/me` + `/api/usage`. Daemon then refreshes Cursor data daily via API — zero manual exports.

    When · You want fully automatic daily Cursor sync with no manual CSV export. Cookies live 30-90 days; re-run when sync starts failing with 401.

    tokenflexing setup-cursor-auto

Agents & automation

MCP server, editor integrations, and daily-refresh scheduling.

  • tokenflexing mcp

    Starts a Model Context Protocol stdio server (protocol 2024-11-05). Exposes three tools to an LLM client: `get_my_stats`, `get_device_scan`, `get_flex_card`. Reads disk on every call — no network, works 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 [--client <name>]

    Edits the MCP servers list inside Claude Code, Cursor, or Claude Desktop config so `tokenflexing` shows up as a callable MCP. Without `--apply` it prints a dry-run diff.

    When · First-time wire-up of the MCP server into an agent. Re-run after editor upgrades.

    • --applyWrite changes. Without this, just print what would change.
    • --client <name>One of `claude-code` (default), `cursor`, `claude-desktop`.
    tokenflexing install-hooks --apply --client cursor
  • tokenflexing daemon [--install|--uninstall]

    Schedules a daily 6:00 AM refresh that runs `scan` and pushes to your profile. macOS uses a LaunchAgent at `~/Library/LaunchAgents/com.tokenflexing.sync.plist`. Windows uses Task Scheduler. 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.8.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
Claude CodeAuto · reads ~/.claude/projects/*.jsonlAuto · parsed
Codex CLIAuto · reads ~/.codex/sessions/*.jsonAuto · parsed
OpenCode (sst/opencode)Auto · reads ~/.local/share/opencode/storage/message/*.jsonAuto · parsed
CursorCSV import, Downloads auto-pickup, or cookie API replayManual · CSV
Claude DesktopSubscription tool — declare tier in /settingsManual · declare
ChatGPT DesktopCSV import — roadmapRoadmap
AiderParser — roadmapRoadmap
Cline / Roo Code / Kilo CodeParser — roadmapRoadmap
Gemini CLIParser — roadmapRoadmap
Windsurf · Zed · Amp · OpenCode · Antigravity · Goose · Kiro · CopilotDetected only — no parser yetRoadmap

Storage paths

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

  • ~/.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.8.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 Claude Code / CursorRun `npx tokenflexing@latest install-hooks --apply --client cursor` (or `--client claude-code`). Restart the editor 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