# dots-cli

A command-line client for [Dots](https://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. 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:

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

Or build from a clone directly to your PATH:

```bash
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

1. Run `dots auth` (opens `https://dots.humdrum.one/cli` in your browser)
2. Copy your CLI token from the page
3. Paste it in the terminal prompt
4. 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`](docs/superpowers/specs/2026-07-29-dots-cli-design.md).

## Development

```bash
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.