Every Clockify feature, plus a local time database that reconstructs your weekly timesheet, finds untracked gaps, and audits billable hours — none of which any other Clockify tool can do.
Other Clockify CLIs are timers with a thin reporting bolt-on, and none of them remember anything. This one keeps a local SQLite mirror of every time entry, project, client, and tag, so reports, timesheet reconstruction, gap detection, and billable audits run offline and instantly. It also covers the half of Clockify no terminal tool touches — invoices, expenses, time-off, approvals, and scheduling.
Created by @melanson633 (melanson633).
Authentication
Authenticate with a personal API key from the Clockify web app (Profile Settings -> API). Export it as CLOCKIFY_API_KEY; the CLI sends it as the X-Api-Key header. The key is read-only-safe for listing and reporting and is required for any write.
Quick Start
# Confirm the API key works and Clockify is reachable before anything else.
clockify-pp-cli doctor
# Pull workspaces, projects, clients, tags, and time entries into the local store — every offline command reads from here.
clockify-pp-cli sync
# Reconstruct this week's grid from the synced entries — the headline view.
clockify-pp-cli timesheet week
# Find the days you are short before you submit the timesheet.
clockify-pp-cli timesheet gaps
# See where your tracked time actually went.
clockify-pp-cli recap
Unique Features
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.
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.
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.
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.
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.
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.
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.
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.
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.
clockify-pp-cli search "client onboarding" --agent
Usage
Run clockify-pp-cli --help for the full command reference and flag list.
Commands
addons
Manage addons
approval-requests
Manage approval requests
clockify-pp-cli approval-requests create-approval-for-other - Submit an approval request for a userclockify-pp-cli approval-requests create-apprroval-request - Submit approval requestclockify-pp-cli approval-requests get - Get approval requestsclockify-pp-cli approval-requests resubmit - Submit non pending/approved entries/expenses for approval to an existing approval requestclockify-pp-cli approval-requests resubmit-for-other - Re-submit rejected/withdrawn entries/expenses for an approval of a userclockify-pp-cli approval-requests update-approval-status - Update an approval request
clients
Manage clients
clockify-pp-cli clients create - Add a new clientclockify-pp-cli clients delete - Delete a clientclockify-pp-cli clients get - Find clients on a workspaceclockify-pp-cli clients get-workspaces - Get a client by IDclockify-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 workspaceclockify-pp-cli custom-fields delete - Delete a custom fieldclockify-pp-cli custom-fields edit - Update custom field on workspaceclockify-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 determined by two parameters: start and end.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 two parameters start and end.
💡 Note
Deleted entities will be updated and reflected in this endpoint approximately one minute after the deletion occurs. Also, entities that are created and deleted within the request date range will not appear in the /deleted endpoint.
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 parameters: start and end.
💡 Note
If an entity is both created and updated within the requested date range, it will be excluded from the /updated endpoint results.
expenses
Manage expenses
clockify-pp-cli expenses create - Create an expenseclockify-pp-cli expenses create-category - Add an expense categoryclockify-pp-cli expenses delete - Delete an expenseclockify-pp-cli expenses delete-category - Delete an expense categoryclockify-pp-cli expenses get - Get all expenses on a workspaceclockify-pp-cli expenses get-categories - Get all expense categoriesclockify-pp-cli expenses get-workspaces - Get an expense by IDclockify-pp-cli expenses update - Update an expenseclockify-pp-cli expenses update-category - Update an expense categoryclockify-pp-cli expenses update-category-status - Archive an expense category
file
Manage file
clockify-pp-cli file - Add a photo
holidays
Manage holidays
clockify-pp-cli holidays create - Create a holidayclockify-pp-cli holidays delete - Delete a holidayclockify-pp-cli holidays get - Get holidays on a workspaceclockify-pp-cli holidays get-in-period - Get holidays in a specific periodclockify-pp-cli holidays update - Update a holiday
hourly-rate
Manage hourly rate
clockify-pp-cli hourly-rate <workspaceId> - Update workspace billable rate
invoices
Manage invoices
clockify-pp-cli invoices create - Add an invoiceclockify-pp-cli invoices delete - Delete an invoiceclockify-pp-cli invoices get - Get all invoices on a workspaceclockify-pp-cli invoices get-info - Filter out invoicesclockify-pp-cli invoices get-settings - Get an invoice in another languageclockify-pp-cli invoices get-workspaces - Get an invoice by IDclockify-pp-cli invoices update - Update an invoiceclockify-pp-cli invoices update-settings - Change an invoice language
member-profile
Manage member profile
clockify-pp-cli member-profile get - Get a member's profileclockify-pp-cli member-profile update-with-additional-data - Update a member's profile
projects
Manage projects
clockify-pp-cli projects create-from-template - Create project from a templateclockify-pp-cli projects create-new - Add a new projectclockify-pp-cli projects delete - Delete a project from a workspaceclockify-pp-cli projects get - Get all projects on a workspaceclockify-pp-cli projects get-workspaces - Find a project by IDclockify-pp-cli projects update - Update a project on a workspace
scheduling
Manage scheduling
clockify-pp-cli scheduling copy-assignment - Copy a scheduled assignmentclockify-pp-cli scheduling create-recurring - Create a recurring assignmentclockify-pp-cli scheduling delete-rrecurring-assignment - Delete a recurring assignmentclockify-pp-cli scheduling edit-recurring - Update a recurring assignmentclockify-pp-cli scheduling edit-recurring-period - Change the recurring periodclockify-pp-cli scheduling get-all-assignments - Get all assignmentsclockify-pp-cli scheduling get-filtered-project-totals - Get all scheduled assignments per projectclockify-pp-cli scheduling get-project-totals - Get all scheduled assignments per projectclockify-pp-cli scheduling get-project-totals-for-single-project - Get all scheduled assignments on projectclockify-pp-cli scheduling get-user-totals - Get total of users' capacity on workspaceclockify-pp-cli scheduling get-user-totals-for-single-user - Get total capacity of a userclockify-pp-cli scheduling publish-assignments - Publish assignments
tags
Manage tags
clockify-pp-cli tags create-new - Add a new tagclockify-pp-cli tags delete - Delete a tagclockify-pp-cli tags get - Find tags on a workspaceclockify-pp-cli tags get-workspaces - Get a tag by IDclockify-pp-cli tags update - Update a tag
templates
Manage templates
clockify-pp-cli templates create-many - Create templates on a workspaceclockify-pp-cli templates delete-1 - Delete a templateclockify-pp-cli templates get - Get all templates on a workspaceclockify-pp-cli templates get-workspaces - Get template by ID on a workspaceclockify-pp-cli templates update - Update a template
time-entries
Manage time entries
clockify-pp-cli time-entries create-time-entry - Add a new time entryclockify-pp-cli time-entries delete-time-entry - Delete a time entry from a workspaceclockify-pp-cli time-entries get-in-progress - Get all in progress time entries on a workspaceclockify-pp-cli time-entries get-time-entry - Get a specific time entry on a workspaceclockify-pp-cli time-entries update-invoiced-status - Mark time entries as invoicedclockify-pp-cli time-entries update-time-entry - Update time entry on a workspace
time-off
Manage time off
clockify-pp-cli time-off change-request-status - Change a time off request statusclockify-pp-cli time-off create-policy - Create a time off policyclockify-pp-cli time-off create-request - Create a time off requestclockify-pp-cli time-off create-request-for-other - Create a time off request for a userclockify-pp-cli time-off delete-policy - Delete a policyclockify-pp-cli time-off delete-request - Delete a time off requestclockify-pp-cli time-off find-policies-for-workspace - Get policies on a workspaceclockify-pp-cli time-off get-balances-for-policy - Get balances for a policyclockify-pp-cli time-off get-balances-for-user - Get balance for a userclockify-pp-cli time-off get-policy - Get a time off policyclockify-pp-cli time-off get-request - Get all time off requests on a workspaceclockify-pp-cli time-off update-balance - Update a balanceclockify-pp-cli time-off update-policy - Update a policyclockify-pp-cli time-off update-policy-status - Change a policy status
user
Manage user
clockify-pp-cli user - Get currently logged-in user's info
user-groups
Manage user groups
clockify-pp-cli user-groups create - Add a new groupclockify-pp-cli user-groups delete - Delete a groupclockify-pp-cli user-groups get - Find all groups on a workspaceclockify-pp-cli user-groups update - Update a group
users
Manage users
clockify-pp-cli users add - You can add users to a workspace via API only if that workspace has a paid subscription. If the workspace has a paid subscription, you can add as many users as you want but you are limited by the number of paid user seats on that workspace.clockify-pp-cli users filter-of-workspace - Filter workspace usersclockify-pp-cli users get-of-workspace - Find all users on a workspaceclockify-pp-cli users remove-member - This endpoint is not functional and has been deprecated. A user can be removed/deleted on the CAKE.com Account Members page after deactivating all their existing memberships on all workspaces within an organization.clockify-pp-cli users update-status - Update a user's status
webhooks
Manage webhooks
clockify-pp-cli webhooks create - Creating a webhook generates a new token which can be used to verify that the webhook being sent was sent by Clockify, as it will always be present in the header.clockify-pp-cli webhooks delete - Delete a webhookclockify-pp-cli webhooks get - Get all webhooks on a workspaceclockify-pp-cli webhooks get-workspaces - Get a specific webhook by idclockify-pp-cli webhooks update - Update a webhook
workspaces
Manage workspaces
clockify-pp-cli workspaces create - Add a workspaceclockify-pp-cli workspaces get-of-user - Get all my workspacesclockify-pp-cli workspaces get-of-user-workspaceid - Get workspace info
Output Formats
# Human-readable table (default in terminal, JSON when piped)
clockify-pp-cli approval-requests get mock-value
# JSON for scripting and agents
clockify-pp-cli approval-requests get mock-value --json
# Filter to specific fields
clockify-pp-cli approval-requests get mock-value --json --select id,name,status
# Dry run — show the request without sending
clockify-pp-cli approval-requests get mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
clockify-pp-cli approval-requests get mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
clockify-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/clockify-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
CLOCKIFY_API_KEY | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
clockify-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $CLOCKIFY_API_KEY
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 Unauthorized on every call — CLOCKIFY_API_KEY is missing or stale — regenerate it in the Clockify web app under Profile Settings -> API and re-export it.
- timesheet or recap output is empty — Run
clockify-pp-cli sync first — the offline commands read the local store, not the live API.
- commands return data from the wrong workspace — Pass the workspace id explicitly: the
timesheet, recap, audit, team, and billable commands accept --workspace <id>, and the generated endpoint commands take it as the first positional argument.
- 429 Too Many Requests during a large sync — Clockify rate-limits at roughly 50 requests/second; the client backs off and retries automatically — just let the sync finish.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press