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.

Clock Commands

Clock commands let you record when you start and stop working.

Bash

clocktopus clock in

Record a clock-in signal for today. Marks the start of your work session.

Bash

clocktopus clock out

Record a clock-out signal for today. Marks the end of your work session.

Bash

clocktopus clock status

Show clock signals for today. See your current clock-in/out status.

Bash

clocktopus clock status -d 2024-01-10

Show clock signals for a specific date (use YYYY-MM-DD format).