@cpenned/cli

ob - a terminal client for Open Brain. It is a thin, full-coverage wrapper over the /v1 HTTP API: every command maps to one endpoint, so the API + guard layer stay the single source of truth. Same contract as the MCP server, different front end.

Install

The CLI is published to npm. Install it globally and you have the ob bin on your PATH - no clone or build required:

npm install -g @cpenned/cli
ob --help

From source (development)

Building from the monorepo instead:

npm run build -w @cpenned/cli   # emits packages/cli/dist/index.js
node packages/cli/dist/index.js --help
npm link -w @cpenned/cli        # …or link it onto PATH, then: ob --help

Configure

ob needs the deployment origin and an obr_ API key. Mint the key from the web app (Settings → New API key) so the CLI hits the same vault as the web UI and email. Then save it:

ob config set --url https://<deployment>.convex.site --key obr_...

This writes ~/.open-brain/config.json (chmod 600). Resolution order is environment over file, so you can override per-command or in CI without touching the file:

| Variable | Meaning | | --- | --- | | OPEN_BRAIN_API_URL | Deployment origin (.convex.site on Convex) | | OPEN_BRAIN_API_KEY | obr_ API key | | OPEN_BRAIN_CLIENT_TYPE | Stamped as X-Client (default cli) |

Inspect with ob config show (the key is masked) or ob config path.

Usage

Every command prints a calm, human-readable summary. Add --json to any command to get the raw API payload for piping into jq or scripts. Date flags (--defer, --deadline, and the deadline bounds on find) take calendar days (YYYY-MM-DD) or relative shorthand like today/+3d, and the API returns them as YYYY-MM-DD.

# Views
ob today
ob view upcoming --tz America/New_York

# Tasks
ob task create "Email the landlord" --garden <gardenId> --deadline today --priority high
ob task list --garden <gardenId> --status todo in_progress
ob task get <taskId>
ob task update <taskId> --deadline 2026-07-01
ob task done <taskId>
ob task rm <taskId>
ob task tag-add <taskId> --tag <tagId> <tagId>
echo '[{"gardenId":"...","title":"a"},{"gardenId":"...","title":"b"}]' \
  | ob task create-batch --partial

# Projects / gardens / tags (same create|list|get|update|rm shape)
ob project create "Q3 launch" --garden <gardenId>
ob garden create "Health" --context "fitness, doctor, meds"
ob tag create urgent --color "#c1502e"

# People (personal CRM)
ob person create "Megan" --relationship wife --alias Meg --contact-every 1 --contact-unit week
ob person link <personId> --garden <gardenId> --task <taskId>
ob person link <chrisId> --person "<christinaId>=wife"   # connect two people (symmetric)
ob person contacted <personId>            # reached out -> restarts the contact clock
ob person contacted <personId> --at -3d   # backdate a touch that happened earlier
ob person update <personId> --detail "Kids=Silas, Jude" --clear contactInterval
ob person restore <personId>              # undo a person rm (archive)
ob person list
ob person list christina                  # search name/alias/company/notes
ob task create "Send book rec" --garden <gardenId> --person <personId>
ob task list --person <personId>          # tasks linked to a person

# Reading list (only the url is required; title/description are fetched from the page)
ob read create https://example.com/article
ob read list --status unread
ob read status <itemId> read              # stamps readAt
ob person link <personId> --reading <itemId>

# Habits
ob habits create "Meditate" --garden <gardenId> --schedule '{"kind":"daily"}'
ob habits create "Gym" --garden <gardenId> --schedule '{"kind":"weekly","times":3}'
ob habits list --garden <gardenId>
ob habits complete <habitId> --day today
ob habits uncomplete <habitId> --day 2026-07-05
ob habits update <habitId> --status paused --clear pausedUntilDay
ob habits archive <habitId>
ob habits unarchive <habitId>

# Strava activities (connect an account first, from the web app's Settings page)
ob strava sync --since-days 30    # backfill/fallback (webhook covers real-time)
ob strava list
ob strava update <activityId> --notes "felt great"

# Calendar (read-only mirror; connect a Google account from the web Settings page)
ob event calendars                                     # list synced calendars
ob event ls --start 2026-07-01 --end 2026-07-31        # ISO or epoch-ms; omit for a default window
ob event sync                                          # pull latest now

# Books (a personal library, distinct from the reading list above)
ob book search "project hail mary"                # or --isbn <isbn>
ob book create "Project Hail Mary" --isbn 9780593135204 --status reading
ob book log <bookId> --pages 40                    # logs a session, bumps currentPage
ob book status <bookId> read                       # stamps finishedDay
ob book habit <bookId> --habit <habitId>           # link a daily page-goal habit
ob book list --status reading
ob person link <personId> --book <bookId>          # "recommended by"
ob settings yearly-book-goal 24                    # reading-challenge target

# Reviews
ob review queue                  # incl. people due for contact
ob review garden <gardenId>      # deep review
ob review request <gardenId>     # force into the queue
ob review task <taskId>          # mark reviewed

# Default review period (applied to new tasks/projects; 2 weeks out of the box)
ob settings                                  # show vault settings
ob settings review --every 1 --unit month    # change the default
ob settings review --none                    # disable it
ob settings timezone America/Denver          # set the vault timezone
ob task create "One-off" --garden <gardenId> --no-review   # opt one item out

# AI (needs the relevant provider keys configured on the deployment)
ob find authentication bug
ob triage "call dentist, buy milk, draft the Q3 deck"

# API keys (needs the keys:manage scope)
ob key create "ci runner" --scope tasks:write reviews:*
ob key list
ob key rotate <keyId>
ob key revoke <keyId>

Run ob <group> --help (e.g. ob task --help) for the full option list of any command group.

Agent skills

The CLI ships with the open-brain-cli and open-brain-mcp agent skills so an assistant (e.g. Claude Code) can drive ob or the MCP tools on your machine. Install them into your skills directory:

ob skills list                 # what's bundled, and whether it's installed
ob skills install              # copy into ~/.claude/skills
ob skills install --force      # overwrite existing copies
ob skills uninstall            # remove them again

Skills install into ~/.claude/skills by default; pass --dir <path> to target another location, or name skills to act on a subset (e.g. ob skills install open-brain-mcp). Restart your agent afterwards so it picks up the new skills. (The MCP package can also install its own skill without this CLI: npx -y @cpenned/mcp install-skills.)

Develop

npm run typecheck -w @cpenned/cli
npm test -w @cpenned/cli       # vitest: client, config, format

The CLI is intentionally logic-light - it builds request bodies/queries and renders responses. All validation, the status machine, ownership, and rate limits are enforced server-side by /v1.

Publishing

MIT-licensed and publish-ready (files, publishConfig, prepublishOnly build). To cut a release: bump the version, then npm publish -w @cpenned/cli from the repo root (@cpenned is the owner's npm username scope, so no org is needed; you must be authenticated as that user). prepublishOnly runs the build (bundle skills + tsc) first.