clockodo-cli

CLI for the Clockodo time tracking API. Human-friendly tables and colors, machine-friendly JSON output for AI agents and scripts.

Usage: clockodo [options] [command]

Options:
  -V, --version          output the version number
  -j, --json             Output as JSON
  -p, --plain            Output as plain text (no colors)
  --no-color             Disable colors
  --no-input             Disable interactive prompts
  -v, --verbose          Verbose output

Commands:
  config                 Manage CLI configuration
  status [options]       Show running clock and today's summary
  start [options]        Start time tracking
  stop                   Stop time tracking
  edit [options]         Edit the running clock entry
  extend <minutes>       Extend the running clock by N minutes
  entries                Manage time entries
  customers              Manage customers
  projects               Manage projects
  services               Manage services
  users                  User management
  report                 Aggregated time reports
  absences               Manage absences
  worktimes [options]    Show work time intervals
  userreport [options]   Show user report (overtime, holidays, absences)
  userreports [options]  Show user reports for all users
  schema                 Output machine-readable CLI structure (for AI agents)

Every command supports --help for full usage details.

Installation

npm install -g @liebig-technology/clockodo-cli

Requires Node.js >= 22.

Setup

clockodo config set        # configure API credentials interactively
clockodo status            # verify it works

Credentials are stored in ~/.config/clockodo-cli/config.json. Environment variables CLOCKODO_EMAIL and CLOCKODO_API_KEY take precedence.

Usage

# Time tracking
clockodo start --customer 123 --service 456 --text "Working on feature"
clockodo start --customer 123 --service 456 --billable   # explicit billability
clockodo stop
clockodo status
clockodo edit --text "New description" --billable         # edit running entry
clockodo extend 30                                        # extend running clock by 30 minutes

# Entries
clockodo entries                                         # list today's entries
clockodo entries --since 2026-01-01 --until 2026-01-31   # date range
clockodo entries --billable                              # only billable entries
clockodo entries create --from "09:00" --to "12:30" --customer 123 --service 456
clockodo entries update 42 --text "New description" --customer 789 --service 456

# Customers, projects, services
clockodo customers                                   # list all customers
clockodo customers create --name "Acme Corp"         # create a customer
clockodo customers update 42 --name "Acme Inc"       # rename customer 42
clockodo customers delete 42 --force                 # delete without confirmation
clockodo projects create --name "Website" --customer 42
clockodo services create --name "Development"

# Reports
clockodo report                          # today, grouped by project
clockodo report week --group customer    # this week by customer
clockodo report month --group text       # this month by description

# Absences, work times, user reports
clockodo absences list --year 2026
clockodo worktimes --since 2026-02-17 --until 2026-02-21
clockodo userreport --year 2026

When --customer or --service is not provided, start and entries create launch an interactive picker (disable with --no-input). You can also set defaults via clockodo config set.

Shell Prompt Integration

clockodo status --prompt outputs a single plain-text line for embedding in your terminal prompt:

clockodo status --prompt              # "Working on feature 1h 23m" or empty if idle
clockodo status --prompt --json       # {"data":{"running":true,"text":"...","elapsed":4980,"formatted":"1h 23m"}}

Example for Starship:

# ~/.config/starship.toml
[custom.clockodo]
command = "clockodo status --prompt"
when = true
symbol = "⏱ "

AI Agent Integration

# JSON output for structured parsing
clockodo status --json
clockodo entries --json | jq '.data[].text'

# Auto-JSON when piped (disable with CLOCKODO_AUTO_JSON=0)
result=$(clockodo status)

# Discover all commands and options programmatically
clockodo schema | jq '.cli.subcommands[].name'

Every error maps to a specific exit code (0=success, 2=invalid args, 4=auth failure, etc.) so agents can branch on the code rather than parsing messages.

Development

pnpm install
pnpm dev -- status         # run without building
pnpm build                 # compile to dist/
pnpm test                  # vitest
pnpm typecheck             # tsc --noEmit
pnpm lint                  # biome

License

MIT