Clockify Unofficial CLI

Unofficial. This project is not affiliated with, endorsed by, or supported by CAKE.com d.o.o. "Clockify" is a trademark of CAKE.com d.o.o.

Unofficial command-line interface for Clockify, built on clockify-unofficial-sdk.

Table of contents

• About
• Key features
• Architecture
• Getting started
  • Prerequisites
  • Installation
• Agent skills
• Usage
  • Commands
  • Global options
  • Exit codes
• Configuration
• Development
• Platform notes
• Roadmap
• Open items
• Contributing
• Security
• License

About

clockify provides a terminal and scripting interface to Clockify. The CLI handles profiles, credential storage, name-to-ID resolution, output formatting, and stable exit codes. The SDK owns HTTP, retries, pagination, typed models, and API error mapping.

1.0.0 covers every Clockify operation that the SDK offers: 105 of the 166 non-deprecated operations. The authoritative endpoint mapping is in docs/coverage.md, and what comes next is in docs/ROADMAP.md.

Key features

• Profile-based configuration - Store region, workspace, and user metadata per profile.
• Safe authentication - Validate keys before storage and use the OS keyring by default.
• Script-friendly output - Render data as table, json, jsonl, csv, or one identifier per line with id.
• Stable automation contract - Keep data on stdout, diagnostics on stderr, and use documented exit codes.
• CI support - Use CLOCKIFY_API_KEY without writing a credential to disk.
• Broad coverage - Manage time entries, projects, reports, time off, approvals, expenses, invoices and webhooks from the terminal.
• Typed API foundation - Build on the SDK's typed models, retries, and pagination instead of making HTTP requests in the CLI.

Architecture

The CLI is a thin product layer over the SDK. Commands use services and runtime components for application context, credentials, configuration, output, and error handling.

flowchart TD
    Main["main.py - root app"] --> Commands["commands/ - Typer apps"]
    Commands --> Services["services/ - product logic"]
    Commands --> Runtime["runtime/ - context and errors"]
    Runtime --> Auth["auth/ - credential stores"]
    Runtime --> Config["config/ - settings"]
    Runtime --> Output["output/ - renderers"]
    Services --> SDK["clockify-unofficial-sdk"]
    Runtime --> SDK
    SDK --> API["Clockify API"]

Read docs/ARCHITECTURE.md for the full design, security model, command conventions, and extension checklist.

Getting started

Prerequisites

• Python 3.14 or later
• A Clockify personal API key from Profile settings -> API
• mise for development from a repository checkout

Clockify does not provide OAuth2 for personal API access. The CLI uses a personal API key and supports regional profiles.

Installation

Install the published package with uv or pipx; it needs Python 3.14 or newer:

uv tool install clockify-unofficial-cli
# or
pipx install clockify-unofficial-cli

To work on the CLI, install it from a checkout instead:

git clone https://github.com/gajaguar/clockify-cli.git
cd clockify-cli
make install

make install installs the pinned toolchain, Python dependencies, Node-based documentation tools, and the pre-commit hook.

Agent skills

The repository is also a Claude Code plugin. Pick one channel:

# Claude Code
/plugin marketplace add gajaguar/clockify-cli
/plugin install clockify-cli@clockify-cli-skills

# Any Agent Skills-compatible agent
npx skills add gajaguar/clockify-cli

# opencode
npx skills add gajaguar/clockify-cli -a opencode -y

• clockify-time-tracking covers start, stop, status, log and entry.
• clockify-cli covers authentication, profiles, workspaces and the project, task, tag, client, group, custom-field, webhook, report, time-off, approval, expense and invoice commands.

The skills follow the Agent Skills format, so other agents can read skills/ directly. They require the CLI to be installed and a user to have run clockify auth login. See docs/agents/ for what each install channel does.

Usage

Log in interactively. The key is read from a hidden prompt, validated with Clockify, and stored in the OS keyring:

clockify auth login
clockify auth status

Use standard input for CI or other non-interactive environments. Global options must come before the command:

export CLOCKIFY_API_KEY=...
clockify -o json auth status | jq .email
printf '%s' "$KEY" | clockify -p work auth login --with-token --region EU_CENTRAL_1

Commands

• auth login [--region] [--with-token] [--insecure-storage] validates and stores an API key.

• auth status shows the user, workspace, and credential source.

• auth logout removes the stored key and profile.

• auth token prints the raw key when explicitly requested.

• config path prints the settings file location.

• config list lists configured profiles.

• config use NAME sets the default profile.

• start, stop, status and log track time.

• workspace, user, client, project, task, tag, group, custom-field, entry and webhook manage resources.

• report and shared-report summarize tracked time.

• time-off and approval handle leave and timesheet approvals.

• expense and invoice handle expenses, receipts, invoices and payments.

Run clockify COMMAND --help for the verbs of each group. Clockify operations that the SDK does not offer yet are listed as planned in the coverage matrix and in the roadmap.

Commands that download a file (expense receipt, invoice export) write it to --save PATH, or to a pipe with --save -, and never through -o. Amounts are typed in major units (120.50) and shown in Clockify's minor units. Time off, approvals, expenses and invoices need a paid Clockify plan.

Global options

• -p, --profile: select a stored profile. Environment variable: CLOCKIFY_PROFILE.
• -w, --workspace: override the profile's workspace. Environment variable: CLOCKIFY_WORKSPACE.
• -o, --output: select table, json, jsonl, csv, or id. Environment variable: CLOCKIFY_OUTPUT.
• --version: print the installed version.

Exit codes

Exit codes are stable for shell scripts:

• 0: success.
• 1: unexpected failure.
• 2: invalid usage.
• 3: configuration error.
• 4: authentication failure.
• 5: forbidden.
• 6: resource not found.
• 7: validation failure.
• 8: rate limited.
• 9: service unavailable.

Configuration

The settings file is stored in the platform-specific configuration directory. Run clockify config path to locate it. On Linux, the default is usually ~/.config/clockify-cli/config.toml.

• CLOCKIFY_API_KEY: read-only credential source for automation.
• CLOCKIFY_PROFILE: select the active profile.
• CLOCKIFY_WORKSPACE: override the profile's workspace.
• CLOCKIFY_OUTPUT: select the default output format.
• CLOCKIFY_CLI_CONFIG_DIR: override the configuration directory.
• CLOCKIFY_TEST_API_KEY: enable live test authentication.

Credential resolution uses environment, then the OS keyring, then the opt-in plaintext fallback. The fallback requires auth login --insecure-storage and writes a file with 0600 permissions.

Development

Run these commands from the repository root:

make install          # toolchain, dependencies, and git hooks
make check            # read-only quality gate
make fix              # apply safe automated fixes
make test             # pytest with a 90% coverage floor
make openapi-fetch    # download Clockify's OpenAPI document
make coverage-report  # compare coverage.md with the OpenAPI document

Use make help for every target. Most targets accept FILES="..." to limit their scope, for example:

make md-lint FILES="README.md"

Live tests are excluded from make test. They require CLOCKIFY_TEST_API_KEY and a test workspace.

Platform notes

• Headless Linux hosts may not provide a Secret Service keyring backend. Use CLOCKIFY_API_KEY or the explicit --insecure-storage fallback.
• Python 3.14 is the minimum version required by the CLI and SDK.

Roadmap

• 0.2.0: foundation, workspaces, users, projects, tasks, tags, entries
• 0.3.0: group membership and webhooks
• 0.4.0: reports
• 0.5.0: time off and approvals
• 0.6.0: expenses and receipts
• 0.7.0: invoices
• 1.0.0: exit codes, JSON output and command grammar are a stable contract
• 1.x: the 61 operations the SDK does not offer yet, as it adds them

See docs/ROADMAP.md for operation counts and what is frozen from 1.0.0.

Open items

• Only the GLOBAL region host is verified against a live account.
• Time off, approvals, expenses and invoices are tested against mocked responses; they have not been run against a paid workspace.
• Clockify's per-plan rate limits are not fully documented upstream.

Contributing

Bug reports, ideas and pull requests are welcome; see CONTRIBUTING.md for the workflow.

Security

Report suspected vulnerabilities to dev@gajaguar.com instead of opening a public issue. A Clockify API key grants access to a workspace. Never commit a key, and rotate it immediately if it is exposed.

License

Distributed under the MIT License. See LICENSE for details.