Token Dashboard Usage Uploader

Unified local uploader for Codex, Claude Code, and Typeless usage.

Install

npx -y @token-dashboard/usage-uploader@latest init

init detects local Codex / Claude Code / Typeless sources, asks which services to enable, migrates existing standalone uploaders, binds required identities, runs an initial catch-up, starts one unified background service, and removes the old local commands.

After initialization, use the installed local command:

token-usage-uploader status
token-usage-uploader doctor

Command Design

This package exposes one binary:

token-usage-uploader <global-command>
token-usage-uploader <service> <service-command>

Commands

| Command | Purpose | | --- | --- | | init | Install or upgrade the unified runtime, select enabled services, migrate old uploaders, bind identities, run the first catch-up, and start the background service. | | status | Show a concise service summary: running state, backend URL, enabled services, queue counts, and the next action when service is stopped. | | doctor | Run health checks for the unified service, legacy service residue, old commands, state DBs, identities, and local source paths. | | logs | Print unified service stdout/stderr logs for troubleshooting. | | restart | Restart the unified background service after config or local environment changes. | | uninstall | Remove the unified launchd service and command link. Local data is preserved. | | codex usage | Print local Codex usage for a selected date range. | | codex bind | Rebind Codex identity with email/name/employee ID. | | claude-code usage | Print local Claude Code usage for a selected date range. | | claude-code bind | Rebind Claude Code identity with email/name/employee ID. |

Common examples:

token-usage-uploader status
token-usage-uploader doctor
token-usage-uploader logs --lines 200
token-usage-uploader restart
token-usage-uploader codex usage --period 7d
token-usage-uploader codex bind --email [email protected]
token-usage-uploader claude-code usage --period 7d
token-usage-uploader claude-code bind --email [email protected]

claude, claudecode, and claude-code all resolve to the Claude Code service.

Removed redundant commands:

• start / stop: use init, restart, or uninstall instead.
• clear and per-service clear: re-run init --force only when a full state recopy is needed.
• per-service status: use the single aggregated status command.
• typeless status: covered by the aggregated status command.

Init Flow

init is the only migration entrypoint:

1. Detect existing unified config, old standalone uploaders, local data sources, backend URL settings, and identity readiness.
2. Show a local detection summary.
3. Select enabled services. Existing unified config wins; otherwise old standalone uploaders and local data sources are recommended by default.
4. Install or upgrade the unified runtime.
5. Stop old standalone services, copy old state databases, remove old plists, and remove old local commands.
6. Reapply the selected service set so migrated legacy config cannot re-enable a service the user disabled.
7. Bind Codex / Claude Code identity when those services are enabled.
8. Run an initial catch-up for enabled services only.
9. Start the unified launchd service and run doctor.

Non-interactive examples:

token-usage-uploader init --yes --enable codex,typeless --email [email protected]
token-usage-uploader init --yes --disable claude-code
token-usage-uploader init --backend-url http://localhost:8086

If --yes is used and Codex / Claude Code identity cannot be inferred from local account files, pass --email, --employee-name, or --employee-id.

Migration Notes

The old standalone commands are intentionally removed:

• codex-usage-uploader
• claude-code-usage-uploader
• typeless-usage-uploader

Their state databases are copied into the unified runtime under ~/.token-dashboard-uploader/state/, and the old launchd services are stopped.

There is no separate migration command. init performs migration internally before installing and starting the unified service.

Use this command to verify migration health:

token-usage-uploader doctor