CLI Tracker

The DevClocked CLI tracks your terminal sessions, automatically detecting git repositories and syncing activity to your dashboard. Perfect for developers who spend significant time in the terminal.

Built for AI-Assisted Development

The CLI tracker times any terminal work, including sessions driven by an AI coding tool. SSH sessions, Docker builds, debugging, deployment scripts and shell-heavy work all count, whichever assistant you run.

Time tracked vs AI usage captured

These are two different things and it is worth being precise about which you get:

• Time tracked - the CLI tracker records the terminal session regardless of what you run inside it.
• AI usage captured - agent turns, token spend and the AI-vs-human split are only read for the tools DevClocked has a parser for: Claude Code, Codex CLI and Cursor.

Reading agent session files needs the Mac app's daemon, which ships on macOS only. On Windows and Linux, use the hook plugin for Claude Code, Codex or Cursor instead; the CLI tracker still records terminal time everywhere. Settings > Integrations lists every agent, what it needs, and whether DevClocked has seen it report work on your account.

Requirements

• Node.js 18 or higher
• npm or yarn

Installation

Install the CLI globally via npm:

npm install -g @devclocked/cli

Verify the installation:

devclocked --version

Authentication

Before tracking, you need to authenticate with your API key:

1. Go to your DevClocked Dashboard → Settings → API Keys
2. Generate a new API Key (name it something like "Terminal CLI")
3. Run the login command:

devclocked login

Paste your API key when prompted. Your credentials are stored locally at ~/.config/devclocked/cli.json.

Starting a Tracked Session

Launch a tracked terminal session:

devclocked session

This spawns a wrapped shell that tracks your activity. Use it like your normal terminal — all commands work as expected. When you're done, just type exit or press Ctrl+D.

Available Commands

Command	Description
devclocked login	Authenticate with your API key
devclocked session	Start a tracked terminal session
devclocked status	Check authentication and session state
devclocked flush	Force sync queued activity to server
devclocked summary	Show today's coding activity from the terminal
devclocked setup	Authenticate and register the MCP server for supported AI tools
devclocked mcp-server	Start the local MCP server used by AI assistants
devclocked mcp-list-tools	List the MCP tools exposed by DevClocked
devclocked mcp-health	Run MCP auth, connectivity, and tool checks
devclocked logout	Clear stored credentials

How It Works

The CLI uses a "wrapped shell" approach:

• Your default shell (zsh, bash, fish, etc.) runs inside a pseudo-terminal
• Activity timing is detected based on input/output events
• The current working directory is monitored to detect git repositories
• Ticks are batched and synced to DevClocked every 30 seconds

Privacy

The CLI tracker is designed with privacy in mind:

• No command logging — We never record what commands you type
• No argument logging — Command arguments and flags are not stored
• No output capture — Terminal output is not stored or transmitted
• Timing only — We only track when activity occurs, not what it is
• Local storage — Credentials are stored locally, never in the cloud

Troubleshooting

CLI not found after install?

Ensure your npm global bin directory is in your PATH. Run npm bin -g to find the location.

Session not syncing?

Run devclocked status to check if you're authenticated and devclocked flush to force a sync.