Wakatime CLI

WakaTime CLI

Use the local wrapper commands instead of calling the WakaTime CLI freehand. They are wired to the installed CLI at ~/.wakatime/wakatime-cli, the user's existing ~/.wakatime.cfg, and the WakaTime summaries API.

Command map

• ~/bin/wakatime-branches [extra args] Lists branch time for the requested day or date range, optionally filtered by project name.
• ~/bin/wakatime-ticket-time KEY-123 [extra args] Resolves local branches matching the Jira key, infers the WakaTime project from the repo name, and fetches branch-specific time from the summaries API using both project and branches.

Intent mapping

• Requests like what branches did I work on today should use ~/bin/wakatime-branches.
• Requests like what branches did I work on in soteria today should use ~/bin/wakatime-branches --project-match soteria.
• Requests like how much time did I spend on SOT-829 or fetch WakaTime for SOT-829 should use ~/bin/wakatime-ticket-time SOT-829.
• Requests for machine-readable ticket time should use ~/bin/wakatime-ticket-time SOT-829 --json.
• Requests to prepare a Jira update from tracked time should use branch rows or ticket-specific branch time, then use the Jira skill or Jira wrappers to inspect the target ticket.
• Requests that name both $wakatime-cli and $jira-acli should fetch ticket-specific WakaTime first, then pass time_text, total_seconds, date range, project, and branch into the Jira branch-ticket update workflow.

Output guidance

• For branch-list summaries, report project, branch, and time, ordered by time descending.
• For ticket-related summaries, report the ticket key, project, matched branch, and time.
• If JSON is requested for ticket time, use wakatime-ticket-time ... --json.
• Do not print API keys or config secrets.
• For Jira handoffs, preserve both the human-readable time and exact seconds. Jira timeSpent should be rounded to practical Jira syntax such as 1h 48m; keep the wrapper's exact seconds only for audit context if needed.

Workflow

1. For branch discovery by day, run ~/bin/wakatime-branches.
2. For branch discovery within a project, run ~/bin/wakatime-branches --project-match soteria.
3. For ticket-specific time, run ~/bin/wakatime-ticket-time KEY-123.
4. For structured ticket time, run ~/bin/wakatime-ticket-time KEY-123 --json.
5. If the user wants the time reflected on Jira, pass the branch rows or ticket-specific branch time into the Jira workflow.

Jira Handoff Workflow

Use this flow when the user asks to update the associated Jira ticket with branch time.

1. Infer the Jira key from the branch when the user does not provide one.
2. Run ~/bin/wakatime-ticket-time KEY-123 --json.
3. Use the row whose branch matches the current branch and whose project matches the repo.
4. Convert time_text into Jira timeSpent syntax, such as 1 hr 48 mins to 1h 48m.
5. Pass the ticket key, branch, project, date range, time_text, total_seconds, and Jira timeSpent string to the Jira worklog workflow.
6. After Jira creates a worklog, include the returned worklog id in any ticket description update.

Guardrails

• Do not read or print secret values from ~/.wakatime.cfg.
• Prefer the wrapper commands over calling ~/.wakatime/wakatime-cli directly.
• Ticket-to-time matching depends on branch names containing the Jira key, such as sot-829-browser-map-toggle for SOT-829.
• Branch-specific totals should be fetched with both project and branches; using only branches returned misleading results during verification.
• If the CLI is missing or errors, report that clearly and stop rather than guessing.
• Do not guess time when the wrapper returns no matching row; report the miss and continue Jira updates without worklogging unless the user gives a duration.
• Do not double-log previously recorded Jira time. Inspect existing Jira worklogs when updating a ticket that already has logged time for the same branch/date.

Useful raw commands

• ~/bin/wakatime-branches
• ~/bin/wakatime-branches --project-match soteria
• ~/bin/wakatime-ticket-time SOT-829
• ~/bin/wakatime-ticket-time SOT-829 --json