mvanhorn 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:
- Install via the Printing Press installer. It defaults binaries to
$HOME/.local/binon macOS/Linux and%LOCALAPPDATA%\Programs\PrintingPress\binon Windows:npx -y @mvanhorn/printing-press-library install clockify --cli-only - Verify:
clockify-pp-cli --version - Ensure the reported install directory is on
$PATHfor 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.6 or newer):
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.
clockify-pp-cli timesheet week --agenttimesheet 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 --agentteam 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 --agentbackfill— 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 --agentbillable 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 --agentprojects 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 --agentsearch— 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
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 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...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 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...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...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-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
Finding the right command
When you know what you want to do but not which command does it, ask the CLI directly:
clockify-pp-cli which "<capability in your own words>"
which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.
Recipes
Reconstruct this week's timesheet
clockify-pp-cli timesheet week
Pivots every synced entry into the project/task by weekday grid with per-day and weekly totals.
Catch under-logged days before Friday
clockify-pp-cli timesheet gaps --workday 8h
Reports each day below the 8-hour target and how much time is missing.
Narrow the week grid for an agent
clockify-pp-cli timesheet week --agent --select projects.project,projects.total_hours,total_hours
Narrows the weekly grid JSON to just project names and totals with dotted-path selection, so an agent does not burn context on every daily cell.
Find what is invoice-ready
clockify-pp-cli billable pending
Sums billable time not yet covered by a synced invoice, grouped by client.
Summarize last month
clockify-pp-cli recap --range last-month
Ranked project/client/tag breakdown with the billable split for the prior month.
Auth Setup
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.
Run clockify-pp-cli doctor to verify setup.
Agent Mode
Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.
Pipeable — JSON on stdout, errors on stderr
Filterable —
--selectkeeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:clockify-pp-cli approval-requests get mock-value --agent --select id,name,statusPreviewable —
--dry-runshows the request without sendingOffline-friendly — sync/search commands can use the local SQLite store when available
Non-interactive — never prompts, every input is a flag
Explicit retries — use
--idempotentonly when an already-existing create should count as success, and--ignore-missingonly when a missing delete target should count as success
Response envelope
Commands that read from the local store or the API wrap output in a provenance envelope:
{
"meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
"results": <data>
}
Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.
Agent Feedback
When you (or the agent) notice something off about this CLI, record it:
clockify-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
clockify-pp-cli feedback --stdin < notes.txt
clockify-pp-cli feedback list --json --limit 10
Entries are stored locally at ~/.clockify-pp-cli/feedback.jsonl. They are never POSTed unless CLOCKIFY_FEEDBACK_ENDPOINT is set AND either --send is passed or CLOCKIFY_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.
Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
Output Delivery
Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
| Sink | Effect |
|---|---|
stdout |
Default; write to stdout only |
file:<path> |
Atomically write output to <path> (tmp + rename) |
webhook:<url> |
POST the output body to the URL (application/json or application/x-ndjson when --compact) |
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
Named Profiles
A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.
clockify-pp-cli profile save briefing --json
clockify-pp-cli --profile briefing approval-requests get mock-value
clockify-pp-cli profile list --json
clockify-pp-cli profile show briefing
clockify-pp-cli profile delete briefing --yes
Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.
Async Jobs
For endpoints that submit long-running work, the generator detects the submit-then-poll pattern (a job_id/task_id/operation_id field in the response plus a sibling status endpoint) and wires up three extra flags on the submitting command:
| Flag | Purpose |
|---|---|
--wait |
Block until the job reaches a terminal status instead of returning the job ID immediately |
--wait-timeout |
Maximum wait duration (default 10m, 0 means no timeout) |
--wait-interval |
Initial poll interval (default 2s; grows with exponential backoff up to 30s) |
Use async submission without --wait when you want to fire-and-forget; use --wait when you want one command to return the finished artifact.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 2 | Usage error (wrong arguments) |
| 3 | Resource not found |
| 4 | Authentication required |
| 5 | API error (upstream issue) |
| 7 | Rate limited (wait and retry) |
| 10 | Config error |
Argument Parsing
Parse $ARGUMENTS:
- Empty,
help, or--help→ showclockify-pp-cli --helpoutput - Starts with
install→ ends withmcp→ MCP installation; otherwise → see Prerequisites above - Anything else → Direct Use (execute as CLI command with
--agent)
MCP Server Installation
Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:
claude mcp add clockify-pp-mcp -- clockify-pp-mcp
Verify: claude mcp list
Direct Use
- Check if installed:
which clockify-pp-cliIf not found, offer to install (see Prerequisites at the top of this skill). - Match the user query to the best command from the Unique Capabilities and Command Reference above.
- Execute with the
--agentflag:clockify-pp-cli <command> [subcommand] [args] --agent - If ambiguous, drill into subcommand help:
clockify-pp-cli <command> --help.