pp-clockify

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/productivity/clockify/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Clockify — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `clockify-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install clockify --cli-only
   ```
2. Verify: `clockify-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/productivity/clockify/cmd/clockify-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Use this CLI when an agent or user needs to work with Clockify time data programmatically: filling or reviewing a weekly timesheet, checking that all hours are logged before submission, auditing billable time before invoicing, summarizing where time went over a range, or driving any Clockify resource (projects, clients, expenses, invoices, time-off, approvals) from the terminal. Prefer the offline commands (timesheet, recap, audit, search) after a sync — they are instant and need no network.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Timesheet intelligence
- **`timesheet week`** — Rebuild your whole weekly timesheet grid offline — every project and task across each weekday, with per-day, per-project, and weekly totals.

  _Reach for this when an agent needs the full week at a glance instead of paging raw time-entry JSON._

  ```bash
  clockify-pp-cli timesheet week --agent
  ```
- **`timesheet gaps`** — Find the days you are short — compares each day's tracked hours against your workday target and reports the missing time before you submit.

  _Use this before submitting a timesheet so an agent can flag under-logged days instead of the user discovering them at month-end._

  ```bash
  clockify-pp-cli timesheet gaps --workday 8h --agent
  ```
- **`team timesheets`** — See who has not submitted — diffs the full workspace user list against the week's approval requests so the people who forgot are visible, not invisible.

  _Use this for a manager's Monday approval sweep to chase non-submitters without clicking through every member._

  ```bash
  clockify-pp-cli team timesheets --agent
  ```
- **`backfill`** — Reconstruct the time you forgot to track — turn a CSV export, your shell history, or a CLI session log into draft time entries, review them, then commit them to Clockify.

  _Reach for this when the timer was never started — an agent can draft entries from logs the user already has instead of losing the time._

  ```bash
  clockify-pp-cli backfill --from session-log --file ./session.jsonl --agent
  ```

### Billable revenue protection
- **`audit billable`** — Catch the misfiled entries that silently drop off invoices — billable time with no project, billable tasks marked non-billable, and untagged billable entries.

  _Run this at invoice time so an agent surfaces revenue leakage before the billing period closes._

  ```bash
  clockify-pp-cli audit billable --agent
  ```
- **`billable pending`** — The invoice-ready number — sums billable time not yet covered by any synced invoice, grouped by client.

  _Use this before raising an invoice so an agent knows exactly how much uninvoiced billable time exists per client._

  ```bash
  clockify-pp-cli billable pending --agent
  ```
- **`projects burn`** — Estimate vs actual per project — hours logged against the project's budget or time estimate, with percent consumed.

  _Reach for this when an agent needs to flag projects about to blow their estimate before the overrun happens._

  ```bash
  clockify-pp-cli projects burn --agent
  ```

### Local time database
- **`recap`** — A ranked breakdown of where your tracked time went — by project, client, and tag, with the billable vs non-billable split and percentage of the total.

  _Reach for this for a fast time-allocation summary instead of running and parsing a Clockify web report._

  ```bash
  clockify-pp-cli recap --range last-month --agent
  ```
- **`search`** — Full-text search across every synced time-entry description and project, task, client, and tag name.

  _Use this to locate a past entry by description without paginating the live API._

  ```bash
  clockify-pp-cli search "client onboarding" --agent
  ```

## Command Reference

**addons** — Manage addons


**approval-requests** — Manage approval requests

- `clockify-pp-cli approval-requests create-approval-for-other` — Submit an approval request for a user
- `clockify-pp-cli approval-requests create-apprroval-request` — Submit approval request
- `clockify-pp-cli approval-requests get` — Get approval requests
- `clockify-pp-cli approval-requests resubmit` — Submit non pending/approved entries/expenses for approval to an existing approval request
- `clockify-pp-cli approval-requests resubmit-for-other` — Re-submit rejected/withdrawn entries/expenses for an approval of a user
- `clockify-pp-cli approval-requests update-approval-status` — Update an approval request

**clients** — Manage clients

- `clockify-pp-cli clients create` — Add a new client
- `clockify-pp-cli clients delete` — Delete a client
- `clockify-pp-cli clients get` — Find clients on a workspace
- `clockify-pp-cli clients get-workspaces` — Get a client by ID
- `clockify-pp-cli clients update` — Update a client

**cost-rate** — Manage cost rate

- `clockify-pp-cli cost-rate <workspaceId>` — Update workspace cost rate

**custom-fields** — Manage custom fields

- `clockify-pp-cli custom-fields create` — Create custom fields on a workspace
- `clockify-pp-cli custom-fields delete` — Delete a custom field
- `clockify-pp-cli custom-fields edit` — Update custom field on workspace
- `clockify-pp-cli custom-fields of-workspace` — Get custom fields on a workspace

**entities** — Manage entities

- `clockify-pp-cli entities get-created-entity-info` — Retrieves records from the database collection that were created within a specified date range. The date range is...
- `clockify-pp-cli entities get-deleted-entity-info` — Retrieves a list of record(s) that were deleted within a specified date range. The date range is determined by the...
- `clockify-pp-cli entities get-updated-entity-info` — Retrieves records that were updated within the specified date range. The date range is determined by the two...

**expenses** — Manage expenses

- `clockify-pp-cli expenses create` — Create an expense
- `clockify-pp-cli expenses create-category` — Add an expense category
- `clockify-pp-cli expenses delete` — Delete an expense
- `clockify-pp-cli expenses delete-category` — Delete an expense category
- `clockify-pp-cli expenses get` — Get all expenses on a workspace
- `clockify-pp-cli expenses get-categories` — Get all expense categories
- `clockify-pp-cli expenses get-workspaces` — Get an expense by ID
- `clockify-pp-cli expenses update` — Update an expense
- `clockify-pp-cli expenses update-category` — Update an expense category
- `clockify-pp-cli expenses update-category-status` — Archive an expense category

**file** — Manage file

- `clockify-pp-cli file` — Add a photo

**holi