CLI Installation & Usage

v0.1

The Clocktopus CLI lets you record clock signals (clock-in/out) directly from your terminal. Perfect for developers who prefer command-line tools.

Installation

Bash

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

Verify Installation

Bash

clocktopus --version

Authentication

Before using the CLI, you need to authenticate with your Clocktopus account. The CLI uses secure device authorization (OAuth 2.0 Device Flow).

Step 1: Start Login

Bash

clocktopus login

Step 2: Authorize in Browser

The CLI will display a URL and authorization 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...

Step 3: Confirm

Open the URL in your browser, sign in (if needed), and approve the authorization. The CLI will automatically detect when you've authorized:

Waiting for authorization.....
Logged in as John Doe (john@example.com)

Secure Storage — Your access token is stored in your system's configuration directory. You only need to log in once per device.

Commands Reference

Authentication Commands

Bash

clocktopus login

Authenticate with your Clocktopus account using device authorization.

Bash

clocktopus logout

Log out and clear stored credentials from this device.

Bash

clocktopus whoami

Display the currently logged-in user.

`clocktopus clock (in|out)`

Bash

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

Record the start or end of a work session. Defaults to “now” when no flag is passed.

Option	Description
--ago <duration>	Backdate by a duration from now (`15m`, `1h`, `1h30m`). Mutually exclusive with `--at`.
--at <time>	Backdate to an absolute wall-clock time today (`HH:mm` or `HH:mm:ss`).

`clocktopus clock status`

Bash

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

Show clock signals for a given date.

Option	Description
-d, --date <date>	Show signals for a specific date in `YYYY-MM-DD` format. Defaults to today.

Common errors

Clock commands exit with code 1 on any failure and print a message to stderr. The most common ones:

Not logged in: You are not logged in. Use ‘clocktopus login’ to authenticate first.
Session expired: Session expired. Use ‘clocktopus login’ to authenticate again.
Both flags passed: Cannot use --ago and --at together. Pick one.
Bad --ago: Invalid duration “…”. Use formats like 15m, 1h, or 1h30m.
Bad --at: Invalid time “…”. Use HH:mm or HH:mm:ss format.