Agent CLI Reference

The claude-telemetry agent is a Python command-line tool that calls ccusage to extract usage data from Claude Code's logs and syncs it to Supabase.

Usage

cc-telemetry <command> [options]

Commands

setup

Interactive setup wizard. Configures Supabase credentials, hooks, MCP server, statusline, and daemon in one step.

cc-telemetry setup

Flag	Description
--minimal	Base config only (no hooks/MCP/statusline)
--non-interactive	Read configuration from environment variables

Wizard steps:

1. Checks Node.js, ccusage, and ccost (offers to install missing)
2. Prompts for Supabase URL, service key, and machine name
3. Configures statusline, hooks, MCP server, and daemon
4. Runs an initial sync
5. Shows summary with dashboard URL

Output: Creates ~/.claude-telemetry/config.json with a new machine UUID.

---

sync

Perform a one-time sync of new sessions since the last sync.

cc-telemetry sync [--verbose] [--force]

Flag	Description
--verbose	Show detailed output for each synced session
--force	Re-sync all data, not just new sessions since last sync

---

daemon

Run the agent in continuous sync mode (foreground). Since v0.3.0, the daemon interval defaults to 60 minutes as a backup for real-time hooks.

cc-telemetry daemon [--interval N]

Flag	Description
--interval N	Custom sync interval in minutes (default: 60)

Press Ctrl+C to stop. For background execution, use install-service instead.

---

install-service

Install the agent as a system background service.

cc-telemetry install-service

Creates the appropriate service for your OS:

• Linux: systemd user service
• macOS: launchd agent
• Windows: Task Scheduler task

See Agent Setup for OS-specific details.

---

uninstall-service

Remove the background service.

cc-telemetry uninstall-service

---

service-status

Check the status of the background daemon.

cc-telemetry service-status

---

status

Show the agent's current configuration and last sync time.

cc-telemetry status

---

local

View local usage data without syncing to Supabase.

cc-telemetry local --daily

Useful for inspecting data before syncing, or when you don't have network access.

---

setup-hooks

Configure real-time Claude Code hooks for instant data sync.

cc-telemetry setup-hooks

Sets up SessionEnd and Stop hooks that trigger a sync the moment a Claude Code session ends. Uses a detached process pattern for sub-100ms execution. See Real-time Hooks for details.

---

setup-mcp

Configure the MCP server for natural language usage queries.

cc-telemetry setup-mcp

Registers the MCP server in ~/.claude.json so you can ask Claude about your usage directly. See MCP Integration for details.

---

setup-statusline

Configure rate limit tracking via Claude Code's statusline feature.

cc-telemetry setup-statusline

Creates a statusline script that displays current rate limit usage in your terminal.

---

doctor

Run a 10-point health check to diagnose your installation.

cc-telemetry doctor

Checks: ccusage, ccost, config, Supabase connectivity, statusline, hooks, MCP server, daemon, last sync, hook activity. Each failed check includes an actionable fix hint.

---

uninstall

Remove the agent configuration and data from this machine.

cc-telemetry uninstall

This deletes ~/.claude-telemetry/ and all local agent data. It does not remove data already synced to Supabase.

Statusline cleanup

If you enabled statusline tracking, also remove:

• ~/.claude/statusline.sh (Linux/macOS) or ~/.claude/statusline.ps1 (Windows)
• The statusline entry from ~/.claude/settings.json

Complete Command Reference

Command	Description
cc-telemetry setup	Interactive setup wizard
cc-telemetry setup --minimal	Base config only
cc-telemetry setup --non-interactive	Non-interactive setup
cc-telemetry sync	Manual sync to Supabase
cc-telemetry sync --verbose	Sync with detailed output
cc-telemetry sync --force	Re-sync all data
cc-telemetry daemon	Run auto-sync in foreground
cc-telemetry daemon --interval 10	Custom interval (minutes)
cc-telemetry install-service	Install as system service
cc-telemetry uninstall-service	Remove system service
cc-telemetry service-status	Check daemon status
cc-telemetry status	Show config and last sync
cc-telemetry local --daily	View local data without syncing
cc-telemetry setup-hooks	Configure real-time hooks
cc-telemetry setup-mcp	Configure MCP server
cc-telemetry setup-statusline	Configure statusline
cc-telemetry doctor	10-point health check
cc-telemetry uninstall	Remove agent config from this machine

Environment Variables

Environment variables override config.json values:

Variable	Description
CC_TELEMETRY_SUPABASE_URL	Supabase project URL
CC_TELEMETRY_SUPABASE_KEY	Supabase API key
CC_TELEMETRY_MACHINE_NAME	Machine friendly name
CC_TELEMETRY_SYNC_INTERVAL	Sync interval in minutes
CC_TELEMETRY_LOG_DIR	Claude Code log directory

Config File

Location: ~/.claude-telemetry/config.json

{
  "supabase_url": "https://your-project.supabase.co",
  "supabase_key": "your-api-key",
  "machine_name": "work-laptop",
  "machine_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sync_interval_minutes": 60,
  "log_directory": "~/.claude/projects",
  "last_sync": "2026-04-08T12:00:00Z"
}

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error (missing config, invalid credentials)
3	Network error (cannot reach Supabase)
4	Log directory not found