Mental CLI reference

I type mental. After mental install, agents write on your behalf (journal, decisions, residue). You type mental when you want the pulse yourself. Agents always pass --json. Named commands are one-shot: print or write, then exit.

mental                 # heartbeat on a TTY; help + exit 2 otherwise
mental -h              # Daily commands
mental --help          # all commands, grouped
mental heartbeat --json
mental where --json
mental schema --json

Non-TTY (pipes, agents) with no args prints help and exits 2. mental --json with no command is a heartbeat.

Global flags

MENTAL_ASCII=1 strips emoji from TTY output. --json is always ASCII. MENTAL_SKIP_UPDATE_CHECK=1 skips the npm newest-version check. When npm is ahead, every --json envelope includes a sibling update (current, latest, hint). Ordinary commands read ${XDG_CACHE_HOME:-~/.cache}/mental/npm-latest.json: 24h TTL while this CLI matches cache (so a ship is visible by the next day), 7d TTL only while already behind. A failed npm view backs off 15 minutes without burning that TTL. TTY prints the hint at most once per day. doctor still checks live. install recopies skills; it does not npm view.

Commands

Writes

Same --title updates the existing decision or attention file (paths are identities). --path targets a specific file.

Create for decide, attention, and note requires --tag (1–3 topic slugs). Omit --tag when the same title updates an existing file. Do not pass --tag on journal or park.

mental journal --title "What landed" --body "Evidence git cannot see." --resume "Exact next action — open loops: none" --against PLAN.md --via cursor
mental decide --title "Heartbeat only, no standing TUI" --body "Default TTY mental prints a one-shot heartbeat and exits." --status decided --tag continuity --via cursor
mental attention --title "Tom said ship the pointer not the dump" --kind direction --from Tom --tag continuity --via cursor
mental attention --title "Come back to MCP" --kind thread --status later --tag continuity --via cursor
mental attention --title "Resolver tests not reviewed" --kind verify --tag continuity --via cursor
mental attention --title "Tom said ship the pointer not the dump" --status resolved
mental note --title "Identity is a UUID in bindings.json" --tag continuity
mental track start --title-internal "Auth callback" --via cursor
mental park --resume "Exact next action — open loops: none"
mental track report --since 2026-08-01 --until 2026-08-31

Journal contract (one section per task, not per chat turn):

## HH:MM — <outcome>
<what changed, evidence, decisions git cannot explain>

Against: <optional repo-relative plan>
Resume: <one exact next action> — open loops: <none or list>

Lookup

mental status
mental heartbeat --json
mental where
mental search overlay
mental list --type Decision --kind direction
mental show notes/some-fact.md
mental show journal/2026-08-29.md#22:36

Typed filters (--type, --status, --tag, --kind) apply before the result cap. Search uses SQLite FTS5 with bm25 when Node’s node:sqlite includes FTS5; otherwise it uses SQLite LIKE (or a markdown scan if sqlite is missing). Title matches rank above buried body mentions; Decision/Note rank above Journal. Space-separated words are AND prefixes (overlay leftover must match both) unless --any (OR). Quotes are shell glue, not a phrase operator. JSON includes tokens and op. Journal hops index as journal/YYYY-MM-DD.md#HH:MM. Search one concept per query; before proposing an approach, search that name. MCP q may be a string array (union).

Exit codes

Layout

OKF files under ~/.mental/projects/<uuid>/ (or ./.mental after mental local):

journal/YYYY-MM-DD.md
decisions/YYYY-MM-DD-slug.md
attention/YYYY-MM-DD-slug.md
notes/slug.md
status/current.md          # disposable cache, not SoT
time.sqlite                # optional hours (off until `mental option track on`; never git)

Index: ${XDG_CACHE_HOME:-~/.cache}/mental/<uuid>.sqlite (rebuildable). Hours are not in the index — they live in bundle time.sqlite.

Optional timers are default off. When on, agents generate private and customer-ready title/body fields from current work and refresh them at park, journal, or handoff. track start is ensure-running (machine-wide); --new starts another clock; billable defaults to wall (--billable suggested uses last_seen). Report includes running clocks. Missing customer copy returns structured review JSON. Customer export rows contain date, work description, wall, and billable. TTY heartbeat and pulse never show hours. Full Track contract.

Pulse watermark: ${XDG_CACHE_HOME:-~/.cache}/mental/<uuid>.pulse.json ({ at: iso } — rebuildable, not SoT). Written after delta by pulse / park / handoff; heartbeat never writes it.

Heartbeat lists (attention and open decisions) are capped at 7; JSON includes attentionCount / openDecisionCount / laterCount. Extra later: mental list --type Attention --status later. Extra open decisions: mental list --type Decision --status open. JSON stale (and a Stale (> 14d) text block) lists open/deferred decisions and open/later attention untouched for 14+ days, oldest first, capped at 5 per kind with a true count.

See identity for UUID / local / leftover import, agents for the --json contract, dashboard for the localhost page, decision models for optional model assist, and optional time tracking for what hours can and cannot do.