dots-cli

A command-line client for Dots 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. Not an offline client — every command is one or two HTTP calls against the production API. If the network is down the command fails fast.

Installation

Via Homebrew from the codex tap:

brew tap humdrum/tap https://codex.humdrum.me/git/homebrew-tap.git
brew install dots

Or build from a clone directly to your PATH:

go build -o ~/bin/dots ./cmd/dots

Releases are cut with custard release vX.Y.Z (tag push publishes the formula automatically).

Commands

dots auth                      Link CLI to account (one-time token paste)
dots log [time|range] [type]   Paint logged block(s); omit the type to fill from plan
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

Time syntax

Blocks are 30-minute slots (the CLI reads the day's blockSize from the API, so other sizes would work too — Dots uses 30). Accepted time forms:

(omitted) — the slot containing the current device time
14:30 — 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

Plan-fill

Omit the activity and dots log paints each target slot with its planned activity:

dots log              # current slot ← its plan block
dots log 13:00-15:00  # each slot in the range ← its plan block

All-or-nothing: if any target slot has no plan block, the command errors listing those slots and paints nothing. Overwriting an already-logged slot always shows a diff table and asks y/N (--yes skips; non-interactive runs without --yes abort).

Auth flow

Run dots auth (opens https://dots.humdrum.one/cli in your browser)
Copy your CLI token from the page
Paste it in the terminal prompt
Token is stored securely in macOS Keychain (or ~/.config/dots/token on other platforms)

All commands require an active auth token. Requests send Authorization: Bearer <token>.

Environment variables

DOTS_URL — override the server URL (defaults to https://dots.humdrum.one; use for dev/testing)

Details

Full specification, auth details, logging semantics, activity matching, and CLI internals: see docs/superpowers/specs/2026-07-29-dots-cli-design.md.

Development

go build ./...          # compile all packages
go test ./...           # run all tests
go run ./cmd/dots       # run the CLI

Written in Go 1.23+ with cobra, lipgloss, and zalando/go-keyring.