clockify-unofficial-cli 0.2.0__py3-none-any.whl

clockify_unofficial_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,278 @@
+Metadata-Version: 2.5
+Name: clockify-unofficial-cli
+Version: 0.2.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 :: 3 - Alpha
+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.0
+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)
+- [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.
+
+The CLI is being delivered in phases. The authoritative endpoint mapping is in
+[`docs/coverage.md`](docs/coverage.md), and the delivery plan 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.
+- **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.
+
+## 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.
+
+Resource commands arrive in phases. See the
+[roadmap](docs/ROADMAP.md) and [coverage matrix](docs/coverage.md) for their
+status.
+
+### 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.
+- The SDK is a `uv` git dependency pinned to a tag, so installation requires
+  access to GitHub.
+- Python 3.14 is the minimum version required by the CLI and SDK.
+
+## Roadmap
+
+- [x] Phase 0: foundation, authentication, profiles, renderers, and exit codes
+- [x] Phase 1: workspace, user, project, task, tag, group, and entry commands
+- [ ] Phase 2: core API completion
+- [ ] Phase 3: reports
+- [ ] Phase 4: time off, holidays, and approvals
+- [ ] Phase 5: expenses and invoices
+- [ ] Phase 6: scheduling, webhooks, and entity changes
+- [ ] Phase 7: release hardening for `1.0.0`
+
+See [`docs/ROADMAP.md`](docs/ROADMAP.md) for operation counts, dependencies,
+and completion criteria.
+
+## Open items
+
+- Only the `GLOBAL` region host is verified against a live account.
+- Plan-gated endpoints need a paid workspace for live verification.
+- 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.

clockify_unofficial_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+clockify_unofficial_cli/__init__.py,sha256=yJLWGpnUNp7fx-JPaj7UUcwqLduST3KrGtFsE17uBTw,84
+clockify_unofficial_cli/__main__.py,sha256=5rtGYz41aKZjC-wZ8R6j2glSYd92KlmO59jOXVz3YGw,52
+clockify_unofficial_cli/_version.py,sha256=oG_VizVo0Tpcm6c8z4J2w3dtAf0VYfOV6qDmjuwhPx8,89
+clockify_unofficial_cli/main.py,sha256=4KS9NnaPWcJsso_pf230hGEz9B0rGQ0XSVMkUyNU-rw,5485
+clockify_unofficial_cli/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clockify_unofficial_cli/auth/credentials.py,sha256=YaXAvy_mgjHaoGBXiSq-hcFX-xNwjgJ1btZY5Eu2DlM,1859
+clockify_unofficial_cli/auth/env_store.py,sha256=lCvJF4Tpthlu7Q5lXsNHfYMGCgA5woy2WyADGfo4Kcc,833
+clockify_unofficial_cli/auth/file_store.py,sha256=hzbwOk3yd8VpOoyW7SNrL71TJlPnpzDvAfLbH7Nk9gQ,1640
+clockify_unofficial_cli/auth/keyring_store.py,sha256=yKu07fGhvBrS9lthorU_BKeSpCNczbWKEGE5WlVbdRI,2048
+clockify_unofficial_cli/auth/resolver.py,sha256=_wYvcrEck_YcV4KV-cq9cb1xyQhWLCzpOqaAlU4SSCU,1336
+clockify_unofficial_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clockify_unofficial_cli/commands/auth.py,sha256=A_HRxU6XsNN6JOOHPjB5jQk1oR4HqVRRNLJHwjqIHeg,6159
+clockify_unofficial_cli/commands/client.py,sha256=fhvqfRWtJPE-M6yx8S-wtPX7lcc-d225AAq52cAQbkQ,4639
+clockify_unofficial_cli/commands/config.py,sha256=lpYaetBwQGJOOLTalnZ3xM-ylQtNk0HuetgpM6V8-TM,1913
+clockify_unofficial_cli/commands/custom_field.py,sha256=E-Yh0Dvu69D3zH-_c2cl5E_bPC6gDhGkCfJgk2Y4Ki8,5623
+clockify_unofficial_cli/commands/entry.py,sha256=p3_FSBknb-zT_13EqQw9RpBctPIceZRB3Tq4pheFY6w,10608
+clockify_unofficial_cli/commands/group.py,sha256=3eajCqay1ubZ3PB9flYmfdjJb7Pk3x197MSVds1fJSM,3173
+clockify_unofficial_cli/commands/project.py,sha256=hMURbxm_xT7M83D2iYjqXfcxd-yxThh8sCTFFKtrtiA,6612
+clockify_unofficial_cli/commands/tag.py,sha256=Wcwi6Fqx5YAmJ43PYV62vVpibuTI7hRPzpxyumpLnWQ,3669
+clockify_unofficial_cli/commands/task.py,sha256=JRLJYdlsbT2hhXTnQF5Rj9Bp3CmfzzSF_yvJnC3pSxw,7091
+clockify_unofficial_cli/commands/timer_shortcuts.py,sha256=Kofuyn51G6uSp05xJtjTyqKcy6Z5V0dtDyb_NOyyU2E,6649
+clockify_unofficial_cli/commands/user.py,sha256=bVzzHqlq3Ecfa2pDJD3a7tKYPjLHF6ZCfIcDAO8vbKE,1602
+clockify_unofficial_cli/commands/workspace.py,sha256=KNLde_V1k1hIM0hfY8pdvlqkxCy4PN8AanXctH03J30,3084
+clockify_unofficial_cli/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clockify_unofficial_cli/config/paths.py,sha256=S-pOEqu37uxpEWEeLiYRSdN4Z1UAr3XSfRnGHfuDurQ,550
+clockify_unofficial_cli/config/settings.py,sha256=ATR5iHVLxRS3sST8DbAsjN5bqEjJ4SwztwpGzKhBq8M,2267
+clockify_unofficial_cli/config/store.py,sha256=dr61u2csyPHC2HRgvMrdVs3dnbSnGMAyxXkNx2WCyXU,1993
+clockify_unofficial_cli/output/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clockify_unofficial_cli/output/columns.py,sha256=om8bShsirGSDdkEmkA3J5ZTRBoAeCuzp4PWcZ0CK0i4,2006
+clockify_unofficial_cli/output/formats.py,sha256=cyNvtQwHCpSN1dnmDg7ryfupYSVlP28eDb_UFNqKeE4,2741
+clockify_unofficial_cli/output/registry.py,sha256=CYEszlz6527sIxrqoFuEFbEa3lt6xtVZ59lGcL5D48s,1063
+clockify_unofficial_cli/output/renderer.py,sha256=MMHypFIbg4nl_lDv7A8pUb6yE0WFTZlh0XXo1xNpfHU,1971
+clockify_unofficial_cli/runtime/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clockify_unofficial_cli/runtime/client_factory.py,sha256=mnlBQPvpp4R3gKIxuzqyX8qojF1PfIsdBDX-ncVKB0Y,1429
+clockify_unofficial_cli/runtime/context.py,sha256=7Ydx0ht261l5Ucnf_1dZ31GvRlS6tym1DIQm0tXQ4Lk,3641
+clockify_unofficial_cli/runtime/errors.py,sha256=4cRM3nJ4wQVMELOmVP5S3nzLokKRmkOWa24GR4kMZkU,3071
+clockify_unofficial_cli/runtime/exit_codes.py,sha256=y0DqVZyc2Lj6bdkMozgY5Gr3TkvlCWdqcTpfJf05vxQ,305
+clockify_unofficial_cli/runtime/params.py,sha256=zxXphoRjqxn-CnauIyd4_LuVpi8d-g4AKsXGsZWkn1M,1720
+clockify_unofficial_cli/runtime/prompts.py,sha256=sRv1ILXvmAJK2ZKoqwkV9uOu7C7fG7mQoMGCeWlrcGE,754
+clockify_unofficial_cli/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clockify_unofficial_cli/services/listing.py,sha256=zO7LPYgkkSvPZzfQVF793XAdGp8QnSrGFZwg3Tqi0lQ,1715
+clockify_unofficial_cli/services/parsing.py,sha256=X1nYxLcJSBtSsVsYoFLH2OzECgpFb3kQyLJ3t0lRevE,4300
+clockify_unofficial_cli/services/resolve.py,sha256=i9p2KGftA-bnCHc-LoSPNcI0gstpSSjb_Hxq9DAGvj8,4309
+clockify_unofficial_cli/services/timer.py,sha256=qrlA2PZMFqrsuRnayao0VN5l4NYz2d_Sk4OQOhz6LDI,4231
+clockify_unofficial_cli-0.2.0.dist-info/METADATA,sha256=jWLAuF8SXp8LFIBkvc61UeOqyKcchwVVvKRvgRCHsro,9480
+clockify_unofficial_cli-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+clockify_unofficial_cli-0.2.0.dist-info/entry_points.txt,sha256=IWdqckOWVaZtCHzLKGkzubMhkURrAyFobCnBP5D8veg,62
+clockify_unofficial_cli-0.2.0.dist-info/licenses/LICENSE,sha256=AIJIXGHfD5sOG6LME47OMGdplzyYxbE4vaSXLcWOj-c,1113
+clockify_unofficial_cli-0.2.0.dist-info/RECORD,,

clockify_unofficial_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

clockify_unofficial_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clockify = clockify_unofficial_cli.main:run

clockify_unofficial_cli-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gerardo Antonio Gerónimo Vasconcelos <dev@gajaguar.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.