CLI

The terminal side of Clocktopus. It signs this machine in, corrects the clock when a day needs it, and connects your AI coding agents — the last of which can only be set up from here.

Install

npm install -g @blastin-dev/clocktopus-cli
clocktopus --version

Sign in

clocktopus login

The CLI uses the OAuth 2.0 device flow. It prints a URL and a code:

Starting device authorization...

Open this link to authorize:

  https://clocktopus.app/auth/device?user_code=ABCD1234

Or visit https://clocktopus.app/auth/device and enter code: ABCD-1234

Waiting for authorization...

Open the link, approve it, and the CLI picks it up on its own:

Waiting for authorization.....
Logged in as John Doe ([email protected])

The token is stored in your system's configuration directory. You log in once per device.

Command	What it does
clocktopus login	Authorise this machine
clocktopus logout	Clear stored credentials from this device
clocktopus whoami	Show who this machine is signed in as

Clock in and out

clocktopus clock (in|out) [--ago <duration> | --at <time>]

Records the start or end of a work session. Defaults to now.

Option	Description
--ago <duration>	Backdate by a duration from now: 15m, 1h, 1h30m. Cannot be combined with --at
--at <time>	Backdate to a wall-clock time today: HH:mm or HH:mm:ss

clocktopus clock status [-d <YYYY-MM-DD>]

Shows the clock signals for a date, defaulting to today.

What the signals actually change is covered in clock signals.

Agent telemetry

Records what your AI coding agents cost, so the cost of a piece of work is human time × rate plus agent spend. AI agents covers what is recorded and what is never collected.

clocktopus agent setup

clocktopus agent setup [--name <label>] [--force] [-a <ids>]

Mints an ingest token for this machine, configures every supported agent it finds installed, installs the session hooks, and confirms the receiver accepts the token before reporting success.

Run it from a checkout of the repository you work in — it also checks that repository is attached to a project, since spend from an unattached repo lands in the unattributed row rather than against a client.

Option	Description
--name <label>	Label for this machine's token. Defaults to the hostname. Keep it recognisable, since revocation is per token
--force	Mint a replacement token instead of reusing the one already installed
-a, --agent <ids>	Configure only these agents: claude, codex, opencode. Repeatable or comma-separated

Re-running without --force is safe and idempotent. Restart your agent afterwards — the exporter and the hooks read their configuration once, at startup, so an open session picks up none of it. On Codex, also approve the hooks trust prompt in its own interface, or telemetry arrives without any repository context.

clocktopus agent status

Shows what the receiver has actually received, not what this machine believes it sent.

clocktopus agent doctor

Checks every link in the chain — token, exporter config, hooks, repository mapping — and names the one that is broken. Start here when the report is empty.

clocktopus agent disable

clocktopus agent disable [--revoke] [-a <ids>]

Removes this machine's telemetry configuration. Add --revoke to invalidate the token everywhere, which is what you want if the machine is lost rather than just being turned off. -a narrows it to one agent, with the same ids as setup.

Common errors

Clock commands exit with code 1 on failure and print to stderr.

Message	Cause
You are not logged in. Use 'clocktopus login' to authenticate first.	No credentials on this machine
Session expired. Use 'clocktopus login' to authenticate again.	The stored token is no longer valid
Cannot use --ago and --at together. Pick one.	Both backdating flags passed
Invalid duration "…". Use formats like 15m, 1h, or 1h30m.	Unparseable --ago
Invalid time "…". Use HH:mm or HH:mm:ss format.	Unparseable --at