dots-cli — v1 design

Date: 2026-07-29 Status: Approved pending user review Repos touched: this repo (new, Go CLI) + humdrum-tiv/dots (small server PR)

Purpose

A local command-line client for Dots (dots.humdrum.one) optimized for reflex-speed logging from the terminal: paint a block, add a day note, glance at today — faster than reaching for the phone. Third client after web and iOS; rides the same API surface.

Explicitly not an offline client: no local store, no sync engine, no outbox. Every command is one or two HTTP calls against the production API. If the network is down the command fails fast and says so.

Command surface (v1)

dots auth                          Link CLI to account (one-time token paste)
dots log [time|range] [activity]   Paint logged block(s)
dots clear <time|range>            Clear logged block(s)
dots note "text" [--date D]        Append a day note
dots today [--date D] [--json]     Day grid readout
dots types                         List active activity types

Global flags: --date YYYY-MM-DD where noted (defaults to today, device timezone), --yes/-y to skip confirmation prompts, DOTS_URL env var to override the server (dev/testing; defaults to https://dots.humdrum.one).

Time syntax

Dots blocks are blockSize-minute slots, where blockSize is a per-day setting of 15, 30, or 60 (blockIndex = minutesSinceMidnight / blockSize). The CLI reads day.blockSize from the day payload and does all slot math against it. Accepted forms (examples at blockSize 30):

• (omitted) — the slot containing the current device time
• 14:30 (also 9:00, 09:00) — the single slot containing that time; times snap down to the slot boundary (14:47 → 14:30)
• 13:00-15:00 — range, end-exclusive: slots 13:00, 13:30, 14:00, 14:30. Ranges do not cross midnight.

Argument parsing: the first positional arg is treated as a time/range only when it matches the time syntax (H:MM, HH:MM, or a --joined pair); otherwise it is the activity. So dots log archer = current slot + archer, dots log 14:30 = that slot + plan-fill.

Logging semantics

• dots log <time> <activity> paints each target slot with the matched activity type.
• Plan-fill rule: activity omitted → each target slot takes the activity of its plan block. Slots in the target with no plan block cause an error listing those slots, and nothing is painted (all-or-nothing). This mirrors the native app's long-press plan-fill gesture.
• No silent overwrite (hard rule): before any write, the CLI fetches the day and diffs targets against existing logged blocks. If any target slot is already logged, it prints a change table (14:30 archer → foofaraw) and prompts y/N. Declining aborts with no write. --yes skips the prompt. Non-TTY without --yes aborts with an error — scripts must opt in explicitly.
• dots clear shows the same table (what will be cleared) with the same confirm rule.
• Painting empty slots needs no confirmation.

Activity matching

Client-side fuzzy match against the active types returned by the day payload: case-insensitive prefix match first, then substring. Multiple hits → numbered pick prompt (error under non-TTY). Zero hits → error listing closest names. The CLI cannot create activity types (same v1 rule as the native app); dots types shows what exists.

dots today output

• TTY: truecolor dot strip in activity-type colors rendered with lipgloss; planned blocks shown dim/hollow; legend of the day's types below; current slot marked.
• Not a TTY or --json: raw JSON of the day payload (blocks, plan blocks, types) for scripting (tock, Raycast). Color output auto-degrades on non-truecolor terminals.

Auth

• Server page dots.humdrum.one/cli (Clerk-authenticated) shows generate / copy / revoke for a long-lived CLI token.
• dots auth opens that page in the browser, prompts for a paste, verifies the token with one API call, then stores it in the macOS Keychain (zalando/go-keyring; fallback ~/.config/dots/token, chmod 600, on other platforms).
• All requests send Authorization: Bearer <token>. A 401 response prints "not linked — run dots auth".
• Never prompts for Clerk credentials in the terminal.

Server changes (humdrum-tiv/dots, one small PR)

Modeled on the existing widget-token machinery (lib/db/widgetTokens.ts, /api/widget/token, /api/widget/data):

1. cli_tokens table — clone of widget_tokens (user id, token, created at). Separate row so revoking the widget token doesn't kill the CLI and vice versa.
2. /cli page — signed-in page with generate/copy/revoke, mirroring the widget token UI.
3. Shared auth helper resolveUserId(request) — tries Clerk auth() first, falls back to Bearer → getUserIdByCliToken. Applied to exactly:
   • GET /api/widget/data (additionally accept CLI tokens)
   • POST/PUT /api/days/[date]/blocks
   • POST /api/days/[date]/notes
4. Nothing else changes. Block-write business logic is reused exactly as web/iOS use it.

GET /api/widget/data?date=D&tz=TZ already returns blocks, plan blocks, activity types, and events — everything the CLI reads. One GET feeds today, type matching, plan-fill lookup, and the overwrite diff; write commands are 1 GET + 1 POST.

CLI internals

cmd/dots/main.go        cobra root + command wiring
internal/api/           HTTP client: GetDay, WriteBlocks, ClearBlocks, AddNote, VerifyToken
internal/auth/          keychain load/store, auth command flow
internal/day/           slot math (time→slot index, tz), range parsing, fuzzy match,
                        plan-fill resolution, overwrite diff
internal/render/        today grid (lipgloss truecolor), --json passthrough

• Go 1.23+. Dependencies: cobra, lipgloss, zalando/go-keyring. No local DB, no config file beyond the stored token.
• Timezone: device-local at call time, passed as tz to the API.
• internal/day is pure functions (no I/O) — the testable core.
• Structured for a later dots tui subcommand (Bubbletea) and an optional Wish/SSH wrapper over the same model; neither is in v1.

Errors

Plain one-line messages to stderr, exit code 1. Network unreachable → "can't reach dots.humdrum.one". No retry/backoff in v1 — it's a reflex tool; the user reruns.

Testing

• Table-driven unit tests for everything in internal/day: slot math, range parsing (including end-exclusivity and snap-down), fuzzy matching, plan-fill resolution, overwrite-diff computation.
• internal/api against httptest servers using fixture captures of real widget/data payloads.
• Server PR: route tests covering both auth kinds (Clerk session, CLI bearer) plus rejection of widget tokens on CLI-only paths and vice versa where applicable.

Release / repo

• go install from the repo for now; binary lands in PATH. No packaging in v1.
• Repo: jj-colocated, GitHub humdrum-tiv/dots-cli (private), Backlog.md initialized with the standard 4 statuses.

Out of scope (v1)

Offline queueing, plan-block editing, type creation, timeline/stats/week views, dots tui, SSH serving, non-macOS packaging, retry logic.