npm package: @liebig-technology/clockodo-cli
Description: AI-friendly CLI for the Clockodo time tracking API
Author: Florian Liebig
Latest version: 0.3.3

# clockodo-cli

CLI for the [Clockodo](https://www.clockodo.com) 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

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

Requires Node.js >= 22.

## Setup

```bash
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

```bash
# 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:

```bash
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](https://starship.rs/):

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

## AI Agent Integration

```bash
# 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

```bash
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