Your AI Thinking Partner

The local-first Rust CLI that powers the OneBrain personal AI OS for Obsidian.
_{Vault scaffolding · plugin sync · scheduled skills · diagnostics · self-update — across Claude Code and Gemini CLI.}

---

What is OneBrain CLI?

onebrain is the local-first Rust binary at the heart of OneBrain — a personal AI operating system that lives in your Obsidian vault. It scaffolds new vaults, syncs the OneBrain plugin from GitHub, wires AI-harness hooks, runs scheduled skills through the OS scheduler, diagnoses vault health, and updates itself.

The CLI is cross-harness: paired with the OneBrain plugin (slash commands, skills, agents), it runs under Claude Code and Gemini CLI against the same vault contract.

Why OneBrain CLI

Point an AI agent at a vault and it improvises — a different pile of grep / ls / find / sed each time, behaving differently on each harness and re-derived every session: slow, token-hungry, non-portable, sometimes wrong. OneBrain CLI replaces that improvisation with one deterministic binary.

• Same behavior on every harness & model — Claude Code and Gemini CLI both run onebrain <noun> <verb> and get identical output; switch harness without re-testing how your vault gets touched.
• Cross-platform, one command — the same onebrain <noun> <verb> runs on macOS, Linux, and Windows (Apple Silicon & Intel, x86_64 & ARM down to a Pi Zero) and returns the same typed result on every OS. Write a hook or script once; it behaves identically everywhere — no per-platform shell quirks (sed/find/path-separator differences) to work around.
• Yours to extend, no waiting — add a capability the harness/LLM doesn't have yet and every agent can use it immediately; they only learn the command, not implement the feature.
• No re-deriving solved workflows — search, capture, consolidate, checkpoint live in the binary, so the agent calls one command instead of re-reasoning the recipe each session. Fewer tokens, no drift.
• Deterministic & safe — a typed command with a frozen Envelope can't half-finish or quietly differ like an ad-hoc rm / sed pipeline. Same input → same output, scriptable by hooks.
• Fast — a ~5 MB binary returns in under 50 ms, skipping the latency of several tool calls for what's already one operation.
• Local-first — your vault, your data, your AI memory; no cloud round-trip.
• Trustworthy install — self-update verifies the binary's SHA-256 before swapping.

Status

v3.2.0 — stable & production-ready, in active maintenance. GA since v3.0.0 (2026-05-22), shipping ~weekly themed minors. Version history + direction in the Roadmap; full detail in CHANGELOG.md.

Quickstart

From zero to a working OneBrain vault in three steps.

# 1. Install (macOS — Homebrew is the canonical channel)
brew install onebrain-ai/onebrain/onebrain

# 2. Verify
onebrain --version
# → onebrain 3.2.17

# 3. Scaffold a vault and let init pull the OneBrain plugin
mkdir my-vault && cd my-vault
onebrain init --yes

Then open the vault in your AI harness (Claude Code, Gemini CLI, …) and run /onboarding to finish setup.

On Linux/Windows, grab the matching binary from the latest release (table below) or npm install -g @onebrain-ai/cli. init runs an embedded vault sync step that downloads the plugin tarball; if the network step fails, the scaffold (onebrain.yml, PARA folders, Stop hook, schedule preset) stays intact and the binary prints an onebrain vault sync retry hint. Pass --no-sync for offline / CI scaffolding.

Install

Pre-built binaries

Pick the archive that matches your machine from the latest release:

Platform	Architecture	File
	Apple Silicon (M1–M5)	onebrain-aarch64-apple-darwin.tar.gz
	Intel	onebrain-x86_64-apple-darwin.tar.gz
	ARM64 (glibc · Pi 3/4/5 64-bit OS · Pi Zero 2 W)	onebrain-aarch64-unknown-linux-gnu.tar.gz
	ARMv7 32-bit (Pi 2 v1.1+ · Pi 3/4/5 32-bit OS)	onebrain-armv7-unknown-linux-gnueabihf.tar.gz
	ARMv6 32-bit (Pi 1 · Pi Zero · Pi Zero W)	onebrain-arm-unknown-linux-gnueabihf.tar.gz
	x86_64 (glibc)	onebrain-x86_64-unknown-linux-gnu.tar.gz
	x86_64 (musl / Alpine / static)	onebrain-x86_64-unknown-linux-musl.tar.gz
	ARM64	onebrain-aarch64-pc-windows-msvc.zip
	x86_64	onebrain-x86_64-pc-windows-msvc.zip

Click a platform badge to download that file from the latest release. Each archive ships with a matching .sha256 for manual verification. Filenames use canonical Rust target triples, so installer scripts can parse them unmodified.

# Manual install (any Unix)
curl -L -o onebrain.tar.gz \
  https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-aarch64-apple-darwin.tar.gz
tar xzf onebrain.tar.gz
sudo install onebrain /usr/local/bin/

Channels

Channel	Command	Notes
Homebrew (macOS, canonical)	brew install onebrain-ai/onebrain/onebrain	Formula at onebrain-ai/homebrew-onebrain, bumped on every tag.
npm wrapper	npm install -g @onebrain-ai/cli	Source at npm-wrapper/; CI publishes on every stable tag via npm Trusted Publishers + --provenance. Verifies the release SHA-256 before extracting.
Direct download	table above	Pick your triple, drop the binary on PATH.

All channels resolve to the same per-platform binary published in the matching GitHub Release.

Self-update

After the initial install, refresh in place:

onebrain update                # prompt-and-confirm
onebrain update --check        # dry-run (compare current vs latest)
onebrain update --plan         # machine-readable JSON plan

On an interactive terminal, update shows a framed 🧠 OneBrain Update header and a braille spinner while it checks for (and downloads) a new version; piped / --json / --plan runs stay plain.

onebrain update auto-detects how the binary was installed and uses the right path so package-manager metadata never desyncs:

• Homebrew (binary under the Cellar) — refreshes the onebrain-ai/onebrain tap, then runs brew upgrade onebrain. The tap refresh (added v3.2.17) means a freshly-released version applies in one onebrain update with no manual brew update.
• npm (under node_modules/@onebrain-ai/) — runs npm install -g @onebrain-ai/cli@<version> (added v3.2.17).
• Direct download (a plain file we own) — resolves the current target triple, downloads the matching GitHub Release tarball over HTTPS (rustls TLS), verifies its SHA-256, and atomically swaps the running binary (Unix single-rename; Windows rustup-style two-step with rollback on failure).

After any path, a post-install guard runs onebrain --version from PATH and confirms the upgrade actually took effect.

Build from source

git clone https://github.com/onebrain-ai/onebrain-cli
cd onebrain-cli
cargo build --release -p onebrain-cli
# → target/release/onebrain

Requires a recent stable Rust toolchain (rustup default stable). The only unsafe in OneBrain crates is a single libc::getuid() call (the launchd plist UID); the workspace otherwise builds cleanly on Linux, macOS, and Windows.

Command surface

v3.1 locks a singular-noun, two-level grammar — onebrain <noun> <verb> — so every command path is predictable. Three root verbs handle the common flow; eight resource groups cluster the rest.

onebrain
├── init                       create / re-scaffold a vault (--yes · --force · --no-sync)
├── update                     self-update the binary (--check · --plan)
├── doctor [--fix]             9 health checks + auto-repair recipes
│
├── vault       sync · current
├── session     init
├── checkpoint  stop · reset · orphans
├── qmd         reindex · embed · status
├── plugin      install · update · migrate
├── schedule    register
├── skill       run
└── harness     detect

Group	Verbs	Purpose
Setup	init, plugin install, vault sync	Scaffold onebrain.yml + PARA folders, register the plugin with the harness, overlay the latest plugin tarball.
Runtime (hook protocol)	session init, checkpoint stop · reset · orphans, qmd reindex	Called by the harness SessionStart / Stop / PostToolUse hooks. Emit hard-wired JSON; banner suppressed for clean machine stdio.
Search	qmd reindex · embed · status	Rebuild the qmd index, re-embed documents, report index + embedding health.
Maintenance	doctor [--fix], plugin update · migrate, schedule register	Nine read-only checks + --fix recipes, self-update the binary + rewrite hooks + rebind launchd plists, compile the onebrain.yml schedule: block into OS scheduler artifacts.
Diagnostics	vault current, harness detect	Report which mechanism resolved the active vault, and which AI harness is running.

The tree shape is locked for v3.2+ — 200+ verbs beyond the working set above are stubbed with a stable E_NOT_IMPLEMENTED (exit 72) so the grammar can't drift while features land. Hidden v3.0 flat aliases (session-init, qmd-reindex, register-hooks, …) still dispatch, printing a one-time migration notice (silence with ONEBRAIN_QUIET_MIGRATION=1); they're removed no earlier than v4.

Output modes

Interactive commands default to human-readable text; pass a flag for structured output. Every structured payload is wrapped in the canonical Envelope<T>:

onebrain doctor                 # TTY: animated per-check report, colorized
onebrain doctor --json          # { version, command, ok, vault, data, warnings, error }
onebrain vault current --yaml   # same envelope, YAML
onebrain qmd status --json | jq .data

• --output {text,json,yaml,table,tsv} — full matrix on every command; --json / --yaml are shorthands.
• --pretty forces indented JSON even when stdout is piped; --no-color (or NO_COLOR) forces monochrome; -q drops info logs (errors still hit stderr).
• Output auto-adapts: piped/CI invocations drop color and the startup banner, so machine consumers get clean bytes with no flags. Closed-pipe writes (onebrain qmd reindex | head) exit 0, not a panic.

Security & trust model

onebrain update authenticates downloaded binaries two ways: GitHub's TLS chain (rustls validation, no opt-out) secures the transport, and since v3.1.4 a SHA-256 check verifies the archive against its published .sha256 before the swap — an unverifiable or mismatched asset is refused and the live binary is left untouched. The npm wrapper runs the same SHA-256 check before extracting. What's not yet done is cosign/signature verification: the checksum is an integrity check, not an authenticity one (an attacker who controls the serving origin could serve a matching archive + .sha256 pair), so signing is tracked as a follow-up.

On networks running a corporate MITM proxy, the trust boundary becomes whatever certificate the proxy presents. If that matters to your threat model, verify the published .sha256 files manually after each update.

Every operation that overwrites, migrates, or removes a config file first copies it to <vault>/.onebrain-backups/<file>.<YYYYMMDD-HHMMSS>.bak — the backup is a hard precondition, so the write is refused if the backup can't be made.

Report security issues privately via the channel documented in CONTRIBUTING.md.

Performance

The Rust rewrite milestone, measured against the v2.3.3 TypeScript/Bun CLI on the same hardware (Apple M1, macOS) running onebrain doctor warm:

Metric	v2.3.3 (Bun)	v3.0.0 (Rust)	Δ
Stripped binary size	57.8 MB	4.6 MB	−92%
Private memory per invocation (peak)	~21 MB	~2 MB	~10× less
Cold start	~120 ms	< 50 ms	~2.5× faster
Warm doctor wall time	~980 ms	~890 ms	~9% faster
update --check (warm cache)	~480 ms	~10 ms	~48× faster

Figures from the v3.0.0 rewrite-milestone dogfood; the binary has since grown to ~5 MB as v3.1 added the branded banner and qmd status/embed. Reproduce the size with the release profile (lto = "thin", strip = "symbols", codegen-units = 1, panic = "abort").

Architecture

Four-crate Cargo workspace:

onebrain-cli         Binary crate — clap dispatch over the v3.1 command tree
  │
  ├─ onebrain-fs     Vault walks · frontmatter parsing · plugin tarball overlay
  │                  · init bootstrap · doctor checks · update install path · backups
  │
  ├─ onebrain-cache  Session token resolution · launchd plist generation
  │                  · qmd status detection
  │
  └─ onebrain-core   Types · config parsing · path resolution (zero filesystem deps)

Workspace inheritance keeps [workspace.package] fields (version, edition, license, repository) in one place. The root sets publish = false; all four crates inherit it via publish.workspace = true — only the compiled binary ships.

Test pyramid (3 layers since v3.1.0): inline unit + assert_cmd integration + insta snapshots, 900+ tests passing. CI gates on fmt + clippy -D warnings + a 3-platform matrix (Ubuntu, macOS, Windows). The v2.x Bun golden-master parity layer was retired in v3.1.0; the v3.1 Envelope shape and the output-format matrix now own the canonical-contract role.

Design notes & Rust patterns → docs/: an architecture deep-dive, decision records (ADRs), and a guided tour of the idiomatic Rust this codebase uses — written for contributors, people studying the source, and Rust learners.

Roadmap

Directional — themes are committed, timing flexes with the weekly-minor cadence (≈ one themed minor per week). The live public roadmap is at onebrain.run.

Major/minor only — see CHANGELOG for per-patch detail.

✅ Shipped

• v3.0 — Rust rewrite GA · 9-platform release pipeline · stable JSON contracts.
• v3.1 — Consistency standard: locked <noun> <verb> command tree · canonical Envelope output · branded banner · vault.yml → onebrain.yml · qmd embed · schedule register onebrain.yml support · self-update hardening (SHA-256 verify + Homebrew-aware).

🚧 Phase 1 · perceptual speed + skill alignment (v3.2–v3.7)

• v3.2 — note resource group (11 verbs) · grouped doctor UX with braille spinner + one-pass --fix · animated onebrain update · skill run --harness {claude,gemini} + --model <m> + headless startup-skip handshake + in-place spinner · harness run [PROMPT] --mode {with-context,ad-hoc} for ad-hoc prompts through claude / gemini (reads stdin when omitted) · auto-checkpoint hook fix (CLAUDE_CODE_SESSION_ID top-priority token + anchored last_ts so the time threshold actually fires) · --vault accepted everywhere.
• v3.3 — Daemon foundation: onebrain daemon start/stop/status + structured logging.
• v3.4 — RPC layer: stdio JSON-RPC 2.0 over a Unix socket with auto-spawn.
• v3.5 — Skill-speed rewrites (/daily, /wrapup) + checkpoint recover.
• v3.6 — Capture pipeline (/capture, /bookmark, /braindump).
• v3.7 — Inbox + tasks pipeline + /consolidate.

📦 Phase 2 · bundles (v3.8–v3.11)

• Bundle CLI (onebrain bundle install/list/info/lint/…) · four first-party bundles (dashboard · synthesis · research · scheduler) · core skills slimmed 32 → 18 · onebrain.run/bundles portal.

🔭 Signal-driven (Tier 2/3)

• Broader harness support — Codex, Qwen, and other agentic harnesses beyond today's Claude Code + Gemini CLI.
• Tiered memory + behavior tracking · proactive surfacing · daemon background synthesis · Avatar Mesh (one agent identity across machines) · Telegram / MCP gateway · OneBrain Studio + OneBrain Cloud federation.

🏁 v4.0 · breaking

• Drop vault.yml dual-read (canonical onebrain.yml only) · retire the hidden v3.0 aliases.

Development

rustup default stable
cargo install cargo-insta   # snapshot review

# Full check (matches CI)
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

# Snapshot workflow (insta)
cargo test                  # tests fail on snapshot mismatch
cargo insta review          # interactive approve/reject

The output contract is pinned by crates/onebrain-cli/tests/v31_envelope_snapshots.rs (Envelope shape · insta), tests/output_format_matrix.rs (default / --json / --json --pretty / --yaml), tests/user_flows.rs (new-user / hook-consumer / error-recovery), and tests/v31_integration.rs (v3.0 alias migration).

PR conventions: feature branch → git worktree → 3-round parallel review (correctness / behavior / security) → squash-merge with --delete-branch. English-only repo. One version bump per PR. See CONTRIBUTING.md for the full workflow.

Related projects

• onebrain-ai/onebrain — OneBrain plugin (slash commands, skills, agents, hooks). Pairs with this CLI.
• onebrain.run — Marketing site, install one-liner, public roadmap.
• OneBrain Cloud (waitlist) — Hosted agent runtime + multi-device sync. Planning phase.

Contributing

PRs welcome — see CONTRIBUTING.md for development setup, build + test commands, PR conventions, and the security-issue reporting channel. New contributors are encouraged to start with issues tagged good-first-issue.

License

AGPL-3.0-only. If you make a modified version of OneBrain CLI available to users over a network (AGPL §13 — including SaaS, internal APIs, and any networked interaction), you must release your modifications under the same license. For commercial licensing inquiries, contact hello@onebrain.run.