# Wakatime CLI

> Use this skill when working with WakaTime branch time, Jira-key-to-branch time lookup, or when the user asks which branches they worked on today or in a specific project such as soteria.

- Skill: `imprisonedmind/wakatime-cli` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add imprisonedmind/wakatime-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/imprisonedmind/wakatime-cli/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: imprisonedmind (https://skillmd.com/u/imprisonedmind)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/imprisonedmind/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`