Metadata-Version: 2.5
Name: clockify-unofficial-cli
Version: 1.1.0
Summary: Unofficial command-line interface for Clockify, built on clockify-unofficial-sdk.
Author-email: "G.A.JAGUAR" <dev@gajaguar.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,clockify,time-tracking
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: clockify-unofficial-sdk<2,>=1.10
Requires-Dist: keyring>=25.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic>=2.9
Requires-Dist: rich>=14.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.16
Description-Content-Type: text/markdown

# Clockify Unofficial CLI

[![CI](https://github.com/gajaguar/clockify-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/gajaguar/clockify-cli/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue.svg)](pyproject.toml)
[![Topics](https://img.shields.io/badge/topics-python%20%7C%20cli%20%7C%20clockify%20%7C%20typer%20%7C%20time--tracking-informational)](https://github.com/gajaguar/clockify-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`](https://github.com/gajaguar/clockify-sdk).

## Table of contents

- [About](#about)
- [Key features](#key-features)
- [Architecture](#architecture)
- [Getting started](#getting-started)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
- [Agent skills](#agent-skills)
- [Usage](#usage)
  - [Commands](#commands)
  - [Global options](#global-options)
  - [Exit codes](#exit-codes)
- [Configuration](#configuration)
- [Development](#development)
- [Platform notes](#platform-notes)
- [Roadmap](#roadmap)
- [Open items](#open-items)
- [Contributing](#contributing)
- [Security](#security)
- [License](#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`](docs/coverage.md), and what comes next is in
[`docs/ROADMAP.md`](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.

```mermaid
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`](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](https://mise.jdx.dev) 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](https://docs.astral.sh/uv/) or
[pipx](https://pipx.pypa.io/); it needs Python 3.14 or newer:

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

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

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

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

```bash
# 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](https://agentskills.io/specification)
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/`](docs/agents/index.md) 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:

```bash
clockify auth login
clockify auth status
```

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

```bash
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](docs/coverage.md) and in the [roadmap](docs/ROADMAP.md).

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:

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

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

- [x] `0.2.0`: foundation, workspaces, users, projects, tasks, tags, entries
- [x] `0.3.0`: group membership and webhooks
- [x] `0.4.0`: reports
- [x] `0.5.0`: time off and approvals
- [x] `0.6.0`: expenses and receipts
- [x] `0.7.0`: invoices
- [x] `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`](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`](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`](LICENSE) for details.
