Metadata

name: wakapi
description: Wakapi coding stats (summaries, projects, today status, totals) via a small Python CLI. Requires WAKAPI_URL. WAKAPI_API_KEY is HTTP Basic (Authorization Basic base64(key)) for all calls except health, which uses native GET /api/health (no key). Use for Wakapi / self-hosted coding time and project/language breakdowns.
homepage: https://github.com/chensoul/wakapi-skill
repository: https://github.com/chensoul/wakapi-skill
metadata: {"openclaw":{"requires":{"env":["WAKAPI_URL","WAKAPI_API_KEY"]},"primaryEnv":"WAKAPI_API_KEY"}}

Wakapi API query

When to use

The user wants read-only stats from a Wakapi instance: time ranges, projects/languages, today’s status line, all-time total, or project list.

Documentation map

Document	Use it for
This file	Env vars, subcommand overview, copy-paste CLI examples
references/wakapi-api.md	Full URLs (`/api/health` vs compat prefix), `stats` path vs `summaries` query `range`, preset table, optional summaries filters, curl, timeouts

Requirements

Category	Detail
Runtime	Python 3, stdlib only. Entry: `scripts/wakapi_query.py`. Run from the skill root (directory that contains `SKILL.md`).
Environment	`WAKAPI_URL` — instance origin, no trailing `/` (required). `WAKAPI_API_KEY` — required for every subcommand except `health`.
Network	Outbound HTTPS (or `http://` if your instance uses it) to `WAKAPI_URL`.
Authentication	HTTP Basic: `Authorization: Basic` + base64(API key only).
Registry	`metadata.openclaw`: `requires.env` = `["WAKAPI_URL", "WAKAPI_API_KEY"]`, `primaryEnv` = `WAKAPI_API_KEY`.

No other environment variables are read by the CLI.

Subcommands at a glance

Subcommand	API key?	What it calls
`health`	No	Native `GET {WAKAPI_URL}/api/health` (JSON if `Content-Type: application/json`)
`projects`	Yes	Compat `…/compat/wakatime/v1/users/current/projects`
`status-bar`	Yes	`{WAKAPI_URL}/api/v1/users/current/statusbar/today`
`all-time-since`	Yes	Compat `…/all_time_since_today`
`stats <range>`	Yes	Compat `…/stats/{range}` — `{range}` is a URL path segment
`summaries`	Yes	Compat `…/summaries` — `--range` or `--start` + `--end`; optional `--project`, `--branches`, `--timezone`, `--timeout` (API), `--writes-only`

stats vs summaries: different meanings of “range”; see references/wakapi-api.md.

Prerequisites

Set WAKAPI_URL. Set WAKAPI_API_KEY for all commands except health.
Do not paste secrets into chat. If the key is missing, ask the user to configure the environment.

Usage

Run from the skill root. --help / summaries --help list all flags.

# WAKAPI_URL required always; WAKAPI_API_KEY required for all subcommands except health.
export WAKAPI_URL="https://your-wakapi.example"
export WAKAPI_API_KEY="…"

# --- Help ---
python3 scripts/wakapi_query.py --help
python3 scripts/wakapi_query.py summaries --help

# --- health: native GET /api/health (no API key); JSON body if Content-Type: application/json ---
python3 scripts/wakapi_query.py health
python3 scripts/wakapi_query.py health --timeout 30   # HTTP socket timeout (default 15s)

# --- projects / all-time-since: compat …/compat/wakatime/v1/... | status-bar: /api/v1/... ---
python3 scripts/wakapi_query.py projects
python3 scripts/wakapi_query.py projects --timeout 120
python3 scripts/wakapi_query.py status-bar
python3 scripts/wakapi_query.py all-time-since

# --- stats: compat path …/stats/{range} — Wakapi named intervals only (see models/interval.go), NOT YYYY / YYYY-MM ---
python3 scripts/wakapi_query.py stats today
python3 scripts/wakapi_query.py stats yesterday
python3 scripts/wakapi_query.py stats week
python3 scripts/wakapi_query.py stats month
python3 scripts/wakapi_query.py stats year              # this calendar year (not "stats 2026")
python3 scripts/wakapi_query.py stats last_7_days
python3 scripts/wakapi_query.py stats last_30_days
python3 scripts/wakapi_query.py stats last_6_months
python3 scripts/wakapi_query.py stats last_year         # rolling ~12 months in Wakapi
python3 scripts/wakapi_query.py stats all_time
python3 scripts/wakapi_query.py stats last_7_days --timeout 300   # API keystroke query param, not HTTP socket
# Fixed calendar month/year → use summaries --start/--end, e.g. March 2026:
# python3 scripts/wakapi_query.py summaries --start 2026-03-01 --end 2026-03-31

# --- summaries --range: compat ?range= (Wakapi interval aliases; snake_case and Title Case) ---
# Calendar day / week / month / year (lowercase tokens)
python3 scripts/wakapi_query.py summaries --range today
python3 scripts/wakapi_query.py summaries --range yesterday
python3 scripts/wakapi_query.py summaries --range week
python3 scripts/wakapi_query.py summaries --range month
python3 scripts/wakapi_query.py summaries --range year
# Rolling windows
python3 scripts/wakapi_query.py summaries --range last_7_days
python3 scripts/wakapi_query.py summaries --range "Last 7 Days"          # same interval as last_7_days
python3 scripts/wakapi_query.py summaries --range "Last 7 Days from Yesterday"
python3 scripts/wakapi_query.py summaries --range last_14_days
python3 scripts/wakapi_query.py summaries --range last_30_days
# Previous week / month; rolling 12 months (not calendar year)
python3 scripts/wakapi_query.py summaries --range last_week
python3 scripts/wakapi_query.py summaries --range last_month
python3 scripts/wakapi_query.py summaries --range last_year
python3 scripts/wakapi_query.py summaries --range all_time              # epoch → now; can be large/slow

# --- summaries: optional filters (with --range or with --start/--end) ---
python3 scripts/wakapi_query.py summaries --range last_7_days --timezone Asia/Shanghai
python3 scripts/wakapi_query.py summaries --range week --project myapp --branches main,develop
python3 scripts/wakapi_query.py summaries --range today --writes-only true --timeout 300

# --- summaries: --start + --end (cannot use with --range) ---
python3 scripts/wakapi_query.py summaries --start 2026-03-01 --end 2026-03-07
python3 scripts/wakapi_query.py summaries --start 2026-03-01 --end 2026-03-07 --timezone America/New_York
python3 scripts/wakapi_query.py summaries --start 2026-03-01 --end 2026-03-07 --branches main,develop
python3 scripts/wakapi_query.py summaries --start 2026-03-18 --end 2026-03-18 \
  --project myapp --branches main,develop --timezone Asia/Shanghai --writes-only false

# --- Debug ---
python3 scripts/wakapi_query.py -d projects

More --range values and interval semantics: references/wakapi-api.md.

Interpreting output

Responses are JSON on stdout. Summarize totals and human-readable fields for the user.

On HTTP errors the CLI prints JSON to stderr and exits non-zero. health uses GET /api/health: stdout is {"healthy": true|false} and may include detail when unhealthy (Wakapi app/db flags).

If something fails

WAKAPI_URL reachable? WAKAPI_API_KEY set (except health)?
Summaries: use --range or both --start and --end (same calendar day → same date twice). Optional --project, --branches, --timezone, --timeout (API), --writes-only. Run summaries --help.
Debug: -d / --debug. --timeout on health / projects / status-bar / all-time-since = HTTP socket time. On stats / summaries, --timeout = API keystroke parameter; HTTP stays 60 s.

Wakapi Query

安装技能