clockify-cli

A small command-line client for Clockify.

This tool manages local Clockify profiles, stores API keys in macOS Keychain, and wraps common Clockify API operations for workspaces, projects, clients, tags, tasks, time entries, and timers.

Requirements

• Node.js 20 or newer
• pnpm 10.33.0 or newer for local development
• macOS Keychain access for storing Clockify API keys
• A Clockify API key

Development

pnpm install
pnpm check
pnpm build

Build output is written to dist/.

The build uses tsgo from @typescript/native-preview; pnpm check runs both tsgo --noEmit and tsc --noEmit.

Run the CLI locally:

node dist/index.js --help

Release

Publishing is handled by GitHub Actions when a v* tag is pushed. The tag must match package.json exactly, for example v0.2.0 for version 0.2.0.

The publish workflow requires the NPM_TOKEN repository secret.

pnpm release:check
git tag -a v0.2.0 -m "v0.2.0"
git push origin v0.2.0

Configuration

Create or update a profile:

clockify config set --profile default

The command prompts for a Clockify API key. Profile metadata is saved to:

~/.config/clockify-cli/config.json

API keys are stored separately in macOS Keychain under the clockify-cli service.

For regional or subdomain Clockify deployments, override the base URLs:

clockify config set \
  --profile eu \
  --api-base-url https://euc1.clockify.me/api/v1 \
  --reports-base-url https://euc1.clockify.me/report/v1

List profiles:

clockify config list

Set the default profile:

clockify config use default

Set the default workspace for the current profile:

clockify workspaces use <workspace-id>

Commands

Test authentication:

clockify auth test

Show the current user:

clockify me
clockify me --format csv

List workspaces:

clockify workspaces list

List workspace resources:

clockify projects list
clockify projects list --name "Product" --strict-name-search
clockify clients list
clockify tags list
clockify tasks list --project-id <project-id>

Use explicit paging:

clockify projects list --page 2 --page-size 100

List time entries:

clockify time-entries list \
  --from 2026-06-19T00:00:00.000Z \
  --to 2026-06-20T00:00:00.000Z

Show currently running timers:

clockify timer current

Start and stop a timer:

clockify timer start --description "Implementation work" --project-id <project-id>
clockify timer stop

Create, update, and delete complete time entries:

clockify time-entries create \
  --start 2026-06-19T00:00:00.000Z \
  --end 2026-06-19T01:00:00.000Z \
  --description "Implementation work" \
  --project-id <project-id>

clockify time-entries update <time-entry-id> \
  --start 2026-06-19T00:00:00.000Z \
  --end 2026-06-19T01:00:00.000Z \
  --description "Implementation work" \
  --project-id <project-id>

clockify time-entries delete <time-entry-id>

Manage projects and project custom fields:

clockify projects create --name "New project" --client-id <client-id>
clockify projects update <project-id> --archived
clockify projects custom-fields update <project-id> <field-id> \
  --default-value '"Internal"' \
  --status VISIBLE

Manage workspace users and user groups:

clockify users list --email [email protected]
clockify users invite [email protected]
clockify user-groups list
clockify user-groups add-user <group-id> <user-id>
clockify user-groups remove-user <group-id> <user-id>

Use a non-default profile or workspace:

clockify projects list --profile staging --workspace-id <workspace-id>

Design

See docs/design.md.

Agent Plugins

This repository includes shareable plugins for Codex and Claude Code. Both plugins package the same clockify-cli skills:

• clockify-cli-dev: repository development, tests, package metadata, plugin skills, and release preparation.
• clockify-cli-setup: first-time setup from source or from the published npm package.
• clockify-cli-usage: day-to-day use of the installed clockify command.

The skills live under:

plugins/clockify-cli/skills/

They are packaged as plugins instead of standalone project skills so other users can install only these clockify-cli workflows from a marketplace.

Codex

Codex uses:

• Plugin manifest: plugins/clockify-cli/.codex-plugin/plugin.json
• Marketplace manifest: .agents/plugins/marketplace.json

Install the marketplace and plugin:

codex plugin marketplace add urugus/clockify-cli
codex plugin add clockify-cli@clockify-cli

Start a new Codex thread after installing so Codex can discover the plugin skills.

Claude Code

Claude Code uses:

• Plugin manifest: plugins/clockify-cli/.claude-plugin/plugin.json
• Marketplace manifest: .claude-plugin/marketplace.json

Install the marketplace and plugin:

claude plugin marketplace add urugus/clockify-cli
claude plugin install clockify-cli@clockify-cli

Plugin skills are namespaced in Claude Code:

/clockify-cli:clockify-cli-usage
/clockify-cli:clockify-cli-setup
/clockify-cli:clockify-cli-dev

For local Claude Code plugin development, load the plugin directly:

claude --plugin-dir ./plugins/clockify-cli

Validate the Claude Code marketplace and plugin:

claude plugin validate .