Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

fix: add install-cli command to publish o2b to PATH after plugin install (v0.5.5)

Sol Aitkendf5275a71407
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 705269f3..aa4ec82f 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.5.4",
+ "version": "0.5.5",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": "Open Second Brain contributors",
"license": "MIT",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 38352a43..201fa614 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.5.4",
+ "version": "0.5.5",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"keywords": ["second-brain", "obsidian", "agents", "skills", "event-log", "mcp"]
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9d818ac1..c14f8cff 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+## [0.5.5] - 2026-05-08
+
+### Added
+
+- `o2b install-cli` subcommand: creates symlinks for `o2b` and `vault-log`
+ in `~/.local/bin` pointing to the wrapper scripts inside the plugin
+ checkout. Run once after `hermes plugins install` to make bare `o2b`
+ available on PATH. Symlinks survive `hermes plugins update` because they
+ point into the git-managed checkout.
+- `o2b uninstall --remove-cli` flag: removes the symlinks created by
+ `install-cli` during uninstall.
+
+### Fixed
+
+- Installation instructions (`install.md`, `after-install.md`, `README.md`)
+ now include the `install-cli` step between `hermes plugins install` and
+ `o2b init`, closing the gap where bare `o2b` was not found on PATH after
+ a clean plugin install.
+
## [0.5.4] - 2026-05-07
### Fixed
diff --git a/README.md b/README.md
index afe03ac3..adb44087 100644
--- a/README.md
+++ b/README.md
@@ -49,9 +49,10 @@ hermes plugins install itechmeat/open-second-brain --enable
hermes gateway restart
```
-Then initialize the vault, register the MCP server, and verify:
+Then publish the CLI commands to PATH, initialize the vault, register the MCP server, and verify:
```bash
+~/.hermes/plugins/open-second-brain/scripts/o2b install-cli
o2b init --vault /path/to/vault --name "My Second Brain"
hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault
hermes gateway restart
@@ -114,16 +115,17 @@ scripts/o2b index --vault /path/to/vault
```text
o2b status Show config/vault status
o2b init Bootstrap the vault profile
+o2b install-cli Symlink o2b and vault-log into ~/.local/bin
o2b doctor Run vault and adapter checks
o2b append-event Append one daily event-log entry
o2b index Rebuild the Markdown page index
o2b export-config Write a redacted config snapshot
o2b mcp Run the optional MCP tool server (stdio)
-o2b uninstall Print an uninstall plan; --apply-local removes only local config
+o2b uninstall Print an uninstall plan; --apply-local removes config; --remove-cli removes symlinks
vault-log Compatibility wrapper around append-event
```
-The local checkout can be used without installing the Python package. Run commands through `scripts/o2b` and `scripts/vault-log`, or set `PYTHONPATH=src` for module execution.
+After running `o2b install-cli`, the bare `o2b` and `vault-log` commands are available on PATH. The local checkout can also be used without installing the Python package β€” run commands through `scripts/o2b` and `scripts/vault-log`, or set `PYTHONPATH=src` for module execution.
## Optional MCP tool server
@@ -174,15 +176,16 @@ OpenSecondBrain treats your vault as the source of truth and never removes Markd
The plan tells you which Hermes commands to run yourself, where the machine-local config directory lives, and reminds you that the vault is untouched. The dry-run never modifies the filesystem.
-2. Deregister the MCP server and remove the Hermes plugin (Hermes-owned state):
+2. Deregister the MCP server, clean up CLI symlinks, and remove the Hermes plugin (Hermes-owned state):
```bash
hermes mcp remove open-second-brain
+ o2b uninstall --apply-local --remove-cli
hermes plugins remove open-second-brain
hermes gateway restart
```
- `hermes mcp remove` deletes the MCP registration and any OAuth tokens. `hermes plugins remove` deletes only the installed plugin directory. OpenSecondBrain itself never edits `~/.hermes/config.yaml` β€” these commands are run by you against Hermes.
+ `hermes mcp remove` deletes the MCP registration and any OAuth tokens. `o2b uninstall --remove-cli` removes the CLI symlinks β€” run it *before* `hermes plugins remove` so the plugin directory still exists for symlink verification. `hermes plugins remove` deletes the installed plugin directory. OpenSecondBrain itself never edits `~/.hermes/config.yaml` β€” these commands are run by you against Hermes.
3. Optionally remove the machine-local config directory (typically `~/.config/open-second-brain` or `$OPEN_SECOND_BRAIN_CONFIG`'s parent):
@@ -190,7 +193,7 @@ OpenSecondBrain treats your vault as the source of truth and never removes Markd
o2b uninstall --apply-local
```
- `--apply-local` only removes that one config directory. It refuses to act if the directory name is not a recognized Open Second Brain config dir, if it lives inside a Hermes-owned path, or if it looks like a git repository. It never touches the vault, Hermes config, or anything else.
+ `--apply-local` only removes that one config directory. It refuses to act outside its intended scope β€” it never touches the vault, Hermes config, or anything else.
To delete the vault you must do that yourself with normal filesystem tools β€” OpenSecondBrain will not do it for you, even with `--apply-local`.
diff --git a/after-install.md b/after-install.md
index d03ff4ea..bc3b4193 100644
--- a/after-install.md
+++ b/after-install.md
@@ -3,7 +3,21 @@
Thanks for installing Open Second Brain. The plugin is now on disk; finish
the setup with the steps below.
-## 1. Initialise a vault
+## 1. Publish CLI commands to PATH
+
+`hermes plugins install` clones the repository but does not pip-install it,
+so the `o2b` and `vault-log` commands are not on PATH yet. Create symlinks:
+
+```bash
+~/.hermes/plugins/open-second-brain/scripts/o2b install-cli
+```
+
+This creates symlinks in `~/.local/bin` pointing to the wrapper scripts inside
+the plugin checkout. The symlinks survive `hermes plugins update` because they
+point into the git-managed checkout. After this step, `o2b` and `vault-log`
+will be available as bare commands.
+
+## 2. Initialise a vault
Pick (or create) the Obsidian-compatible folder you want as your second
brain, then bootstrap the agent-owned files:
@@ -15,7 +29,7 @@ o2b doctor --vault /path/to/vault --repo .
`o2b doctor` should print `[OK]` for every check.
-## 2. Register the MCP server (optional but recommended)
+## 3. Register the MCP server (optional but recommended)
Open Second Brain ships an optional stdio MCP server. Register it with
Hermes so the deterministic tools are routable:
@@ -35,7 +49,7 @@ Hermes pass a single concatenated argument to the MCP server. Edit
The CLI works on its own; the MCP server is opt-in. See `docs/mcp.md` for
tool schemas, per-tool arguments, and Claude Code / Codex notes.
-## 3. Updating
+## 4. Updating
```bash
hermes plugins update open-second-brain
@@ -44,8 +58,10 @@ hermes gateway restart
`hermes plugins update` runs `git pull` inside the plugin directory. Your
MCP registration in `~/.hermes/config.yaml` is preserved across updates.
+The CLI symlinks do not need to be recreated β€” they point into the same
+checkout that gets updated.
-## 4. Uninstalling
+## 5. Uninstalling
Run a dry-run first to see exactly what will happen and which Hermes
commands you need to run:
@@ -54,24 +70,26 @@ commands you need to run:
o2b uninstall
```
-Then deregister the MCP server and remove the plugin (Hermes-owned state):
+Then deregister the MCP server, clean up the CLI symlinks, and remove the plugin:
```bash
hermes mcp remove open-second-brain
+o2b uninstall --apply-local --remove-cli
hermes plugins remove open-second-brain
hermes gateway restart
```
-Optional: remove the machine-local config directory only:
+> **Order matters:** run `o2b uninstall --remove-cli` *before* `hermes plugins remove`,
+> because the plugin directory (and its `scripts/o2b`) must still exist for the symlink
+> removal to verify its targets.
-```bash
-o2b uninstall --apply-local
-```
+`--apply-local` removes the machine-local config directory
+(`~/.config/open-second-brain`). `--remove-cli` removes the `o2b` and
+`vault-log` symlinks from `~/.local/bin`.
-`--apply-local` only touches `~/.config/open-second-brain` (or the parent
-of `$OPEN_SECOND_BRAIN_CONFIG`). Your vault, `Daily/`, `AI Wiki/`, and
-Markdown notes are never removed by Open Second Brain β€” delete them
-yourself with normal filesystem tools if that is what you want.
+Your vault, `Daily/`, `AI Wiki/`, and Markdown notes are never removed by
+Open Second Brain β€” delete them yourself with normal filesystem tools if
+that is what you want.
## More
diff --git a/install.md b/install.md
index 548d6ba7..fa23d5d8 100644
--- a/install.md
+++ b/install.md
@@ -1,6 +1,6 @@
# open-second-brain β€” Agent Installation Guide
-> **Version 0.5.2**
+> **Version 0.5.5**
> Repository: https://github.com/itechmeat/open-second-brain
This guide is written for an **AI agent**, not a human. It contains the exact commands and decision logic needed to install and configure the **open-second-brain** plugin autonomously. Follow exactly one of the two branches below based on the target runtime (Hermes or OpenClaw). Complete every step in the chosen branch.
@@ -29,7 +29,19 @@ After install, restart the gateway:
hermes gateway restart
```
-### 2. Initialize the vault
+### 2. Publish CLI commands to PATH
+
+`hermes plugins install` clones the repository but does not pip-install the package, so the `o2b` and `vault-log` commands are not on PATH yet. Run this step to create symlinks:
+
+```bash
+~/.hermes/plugins/open-second-brain/scripts/o2b install-cli
+```
+
+This creates symlinks in `~/.local/bin` pointing to `scripts/o2b` and `scripts/vault-log` inside the plugin checkout. The symlinks survive `hermes plugins update` because they point into the git-managed checkout.
+
+After this step, the bare commands `o2b` and `vault-log` will be available on PATH.
+
+### 3. Initialize the vault
Replace `/path/to/vault` with the actual vault path.
@@ -37,14 +49,14 @@ Replace `/path/to/vault` with the actual vault path.
o2b init --vault /path/to/vault --name "My Second Brain"
```
-### 3. Register the MCP server
+### 4. Register the MCP server
```bash
hermes mcp add open-second-brain --command o2b --args mcp --vault /path/to/vault
hermes gateway restart
```
-### 4. Verify the installation
+### 5. Verify the installation
```bash
o2b doctor --vault /path/to/vault --repo .
@@ -52,7 +64,7 @@ o2b doctor --vault /path/to/vault --repo .
All checks must pass. If any check fails, report the failure output to the user before continuing.
-### 5. Update
+### 6. Update
```bash
hermes plugins update open-second-brain
@@ -60,7 +72,9 @@ hermes gateway restart
o2b doctor --vault /path/to/vault --repo .
```
-### 6. Uninstall
+The CLI symlinks created in step 2 do not need to be recreated after an update β€” they point into the git checkout, which `hermes plugins update` refreshes via `git pull`.
+
+### 7. Uninstall
Run in this order:
@@ -68,13 +82,11 @@ Run in this order:
# Step 1 β€” dry-run review
o2b uninstall
-# Step 2 β€” deregister MCP and remove plugin
+# Step 2 β€” deregister MCP, clean up CLI symlinks, remove plugin
hermes mcp remove open-second-brain
+o2b uninstall --apply-local --remove-cli
hermes plugins remove open-second-brain
hermes gateway restart
-
-# Step 3 β€” optionally remove local config directory
-o2b uninstall --apply-local
```
The vault and its Markdown files are never deleted by the uninstall process.
@@ -88,7 +100,7 @@ The vault and its Markdown files are never deleted by the uninstall process.
From Git (pin to a version tag):
```bash
-openclaw plugins install git:github.com/itechmeat/[email protected]
+openclaw plugins install git:github.com/itechmeat/[email protected]
```
Or from a local checkout:
@@ -103,7 +115,19 @@ After install, restart the gateway:
openclaw gateway restart
```
-### 2. Initialize the vault
+### 2. Publish CLI commands to PATH
+
+The `o2b` and `vault-log` commands are not on PATH after OpenClaw plugin
+install. Run this step to create symlinks:
+
+```bash
+./scripts/o2b install-cli
+```
+
+This creates symlinks in `~/.local/bin`. After this, bare `o2b` and
+`vault-log` work on PATH.
+
+### 3. Initialize the vault
Replace `/path/to/vault` with the actual vault path.
@@ -111,7 +135,7 @@ Replace `/path/to/vault` with the actual vault path.
o2b init --vault /path/to/vault --name "My Second Brain"
```
-### 3. Configure the vault path
+### 4. Configure the vault path
Tools are registered natively by the JS plugin entry β€” no MCP registration is needed. Set the vault path in the OpenClaw plugin config:
@@ -120,7 +144,7 @@ openclaw config set plugins.entries.open-second-brain.config.vault '"/path/to/va
openclaw config set plugins.entries.open-second-brain.config.instanceName '"My Second Brain"'
```
-### 4. Verify the installation
+### 5. Verify the installation
```bash
o2b doctor --vault /path/to/vault --repo .
@@ -129,7 +153,7 @@ openclaw plugins inspect open-second-brain --runtime --json
Both commands must succeed. If any check fails, report the failure output to the user before continuing.
-### 5. Update
+### 6. Update
```bash
openclaw plugins update open-second-brain
@@ -137,17 +161,19 @@ openclaw gateway restart
o2b doctor --vault /path/to/vault --repo .
```
-### 6. Uninstall
+The CLI symlinks created in step 2 do not need to be recreated after an update.
+
+### 7. Uninstall
```bash
openclaw plugins uninstall open-second-brain
openclaw gateway restart
```
-Optionally remove the local config directory:
+Optionally remove the local config directory and CLI symlinks:
```bash
-o2b uninstall --apply-local
+o2b uninstall --apply-local --remove-cli
```
The vault and its Markdown files are never deleted by the uninstall process.
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 1db2ae55..783a91e5 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,7 +2,7 @@
"id": "open-second-brain",
"name": "Open Second Brain",
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",
- "version": "0.5.4",
+ "version": "0.5.5",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index b02f5456..49ad460d 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.5.4",
+ "version": "0.5.5",
"type": "module",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
diff --git a/plugin.yaml b/plugin.yaml
index 70ec07bb..4c6e25d4 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.5.4"
+version: "0.5.5"
description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/pyproject.toml b/pyproject.toml
index 68c0cfd8..e219b0d3 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "open-second-brain"
-version = "0.5.4"
+version = "0.5.5"
description = "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/scripts/o2b b/scripts/o2b
index eddbb05e..e9f153f0 100755
--- a/scripts/o2b
+++ b/scripts/o2b
@@ -1,7 +1,10 @@
#!/usr/bin/env bash
set -euo pipefail
-SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# Follow symlink so PYTHONPATH is correct even when invoked through
+# a symlink from ~/.local/bin (created by 'o2b install-cli').
+SELF=$(realpath -- "${BASH_SOURCE[0]}")
+SCRIPT_DIR=$(cd -- "$(dirname -- "$SELF")" && pwd)
REPO_ROOT=$(cd -- "$SCRIPT_DIR/.." && pwd)
export PYTHONPATH="$REPO_ROOT/src${PYTHONPATH:+:$PYTHONPATH}"
exec python3 -m open_second_brain.cli "$@"
diff --git a/scripts/vault-log b/scripts/vault-log
index dcfefcf6..1285b482 100755
--- a/scripts/vault-log
+++ b/scripts/vault-log
@@ -1,7 +1,10 @@
#!/usr/bin/env bash
set -euo pipefail
-SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# Follow symlink so PYTHONPATH is correct even when invoked through
+# a symlink from ~/.local/bin (created by 'o2b install-cli').
+SELF=$(realpath -- "${BASH_SOURCE[0]}")
+SCRIPT_DIR=$(cd -- "$(dirname -- "$SELF")" && pwd)
REPO_ROOT=$(cd -- "$SCRIPT_DIR/.." && pwd)
export PYTHONPATH="$REPO_ROOT/src${PYTHONPATH:+:$PYTHONPATH}"
exec python3 -m open_second_brain.vault_log "$@"
diff --git a/src/open_second_brain/cli.py b/src/open_second_brain/cli.py
index dac10b3e..1a74fc62 100644
--- a/src/open_second_brain/cli.py
+++ b/src/open_second_brain/cli.py
@@ -12,6 +12,12 @@ from open_second_brain.config import default_config_path, discover_config, redac
from open_second_brain.doctor import doctor
from open_second_brain.event_log import append_event
from open_second_brain.init import bootstrap_vault
+from open_second_brain.install_cli import (
+ install_cli,
+ render_install_result,
+ render_uninstall_result,
+ uninstall_cli,
+)
from open_second_brain.mcp import MCPServer, run_cli_command as run_mcp_server
from open_second_brain.uninstall import plan_uninstall, render_plan
from open_second_brain.vault import list_vault_pages, write_frontmatter
@@ -62,15 +68,33 @@ def build_parser() -> argparse.ArgumentParser:
mcp_cmd.add_argument("--config", type=Path, default=None, help="Config file path")
mcp_cmd.add_argument("--repo", type=Path, default=None, help="Repository root for plugin checks")
+ install_cli_cmd = subcommands.add_parser(
+ "install-cli",
+ help="Create symlinks for o2b and vault-log in ~/.local/bin",
+ description=(
+ "Symlink the CLI wrapper scripts (scripts/o2b, scripts/vault-log) into "
+ "~/.local/bin so that bare 'o2b' and 'vault-log' commands work on PATH. "
+ "Run this once after 'hermes plugins install'. The symlinks survive "
+ "'hermes plugins update' because they point into the git checkout."
+ ),
+ )
+ install_cli_cmd.add_argument(
+ "--bindir",
+ type=Path,
+ default=None,
+ help="Target directory for symlinks (default: ~/.local/bin)",
+ )
+
uninstall_cmd = subcommands.add_parser(
"uninstall",
- help="Print an uninstall plan and (optionally) clean local config",
+ help="Print an uninstall plan and (optionally) clean local config and CLI symlinks",
description=(
"Read-only by default. Prints the Hermes commands you must run yourself "
"(this tool never touches ~/.hermes/config.yaml or the installed plugin). "
"With --apply-local it may remove the machine-local Open Second Brain "
"config directory only. Your vault, Daily/, AI Wiki/, and Markdown notes "
- "are never removed."
+ "are never removed. With --remove-cli it also removes the o2b/vault-log "
+ "symlinks created by 'o2b install-cli'."
),
)
uninstall_cmd.add_argument("--config", type=Path, default=None, help="Config file path")
@@ -83,6 +107,15 @@ def build_parser() -> argparse.ArgumentParser:
"are never touched."
),
)
+ uninstall_cmd.add_argument(
+ "--remove-cli",
+ action="store_true",
+ dest="remove_cli",
+ help=(
+ "Remove the o2b and vault-log symlinks from ~/.local/bin "
+ "(created by 'o2b install-cli')."
+ ),
+ )
tool_call_cmd = subcommands.add_parser(
"tool-call",
@@ -236,7 +269,25 @@ def command_uninstall(args: argparse.Namespace) -> int:
config = args.config or default_config_path()
plan = plan_uninstall(config_path=config, apply_local=args.apply_local)
sys.stdout.write(render_plan(plan))
+ return_code = 0
+
+ if getattr(args, "remove_cli", False):
+ cli_result = uninstall_cli()
+ sys.stdout.write("\n")
+ sys.stdout.write(render_uninstall_result(cli_result))
+ if cli_result.errors:
+ return_code = 1
+
if plan.errors:
+ return_code = 1
+ return return_code
+
+
+def command_install_cli(args: argparse.Namespace) -> int:
+ bindir = getattr(args, "bindir", None)
+ result = install_cli(bindir=bindir)
+ sys.stdout.write(render_install_result(result))
+ if result.errors:
return 1
return 0
@@ -289,6 +340,8 @@ def main(argv: list[str] | None = None) -> int:
return command_index(args)
if args.command == "mcp":
return command_mcp(args)
+ if args.command == "install-cli":
+ return command_install_cli(args)
if args.command == "uninstall":
return command_uninstall(args)
if args.command == "tool-call":
diff --git a/src/open_second_brain/install_cli.py b/src/open_second_brain/install_cli.py
new file mode 100644
index 00000000..61348224
--- /dev/null
+++ b/src/open_second_brain/install_cli.py
@@ -0,0 +1,203 @@
+"""Install (and optionally remove) CLI symlinks for o2b and vault-log.
+
+After ``hermes plugins install`` (or ``pip install``), the ``o2b`` and
+``vault-log`` entry-points may not be on PATH. This module creates
+symlinks from ``~/.local/bin/o2b`` β†’ ``scripts/o2b`` (and the same for
+vault-log) so the bare commands work immediately.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+CLI_SCRIPTS: tuple[str, ...] = ("o2b", "vault-log")
+
+
+@dataclass(frozen=True)
+class InstallResult:
+ """Outcome of an install-cli run."""
+
+ bindir: Path
+ outcomes: tuple[tuple[str, str], ...]
+ errors: tuple[str, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class UninstallResult:
+ """Outcome of a remove-cli run."""
+
+ bindir: Path
+ outcomes: tuple[tuple[str, str], ...]
+ errors: tuple[str, ...] = field(default_factory=tuple)
+
+
+def _repo_root() -> Path:
+ """Return the repository root (two directories above this module)."""
+ return Path(__file__).resolve().parent.parent.parent
+
+
+def _scripts_dir() -> Path:
+ """Return the ``scripts/`` directory inside the repo root."""
+ return _repo_root() / "scripts"
+
+
+def _find_script(name: str) -> Path | None:
+ """Return the absolute path to a script, or ``None`` if it is missing."""
+ script = _scripts_dir() / name
+ if script.is_file():
+ return script.resolve()
+ return None
+
+
+def _is_valid_symlink(link: Path, target: Path) -> bool:
+ """Return ``True`` when *link* points to *target*."""
+ try:
+ return link.resolve() == target.resolve()
+ except OSError:
+ return False
+
+
+def install_cli(bindir: Path | None = None) -> InstallResult:
+ """Create (or verify) symlinks for o2b and vault-log.
+
+ Args:
+ bindir: Target directory. Defaults to ``~/.local/bin``.
+
+ Returns an :class:`InstallResult`.
+ """
+ if bindir is None:
+ bindir = Path.home() / ".local" / "bin"
+
+ bindir.mkdir(parents=True, exist_ok=True)
+
+ outcomes: list[tuple[str, str]] = []
+ errors: list[str] = []
+
+ for name in CLI_SCRIPTS:
+ link = bindir / name
+ source = _find_script(name)
+
+ if source is None:
+ msg = f"error: script 'scripts/{name}' not found in {_scripts_dir()}"
+ outcomes.append((name, msg))
+ errors.append(msg)
+ continue
+
+ if link.is_symlink():
+ if _is_valid_symlink(link, source):
+ outcomes.append((name, f"exists: {link} β†’ {source}"))
+ else:
+ existing_target = "unknown"
+ try:
+ existing_target = str(link.readlink())
+ except OSError:
+ pass
+ msg = f"warning: {link} already points to {existing_target}, not overwriting"
+ outcomes.append((name, msg))
+ elif link.exists():
+ msg = f"warning: {link} exists and is not a symlink, not overwriting"
+ outcomes.append((name, msg))
+ else:
+ try:
+ link.symlink_to(source)
+ outcomes.append((name, f"created: {link} β†’ {source}"))
+ except OSError as exc:
+ msg = f"error: could not create symlink {link}: {exc}"
+ outcomes.append((name, msg))
+ errors.append(msg)
+
+ return InstallResult(
+ bindir=bindir,
+ outcomes=tuple(outcomes),
+ errors=tuple(errors),
+ )
+
+
+def uninstall_cli(bindir: Path | None = None) -> UninstallResult:
+ """Remove the symlinks created by :func:`install_cli`.
+
+ Only removes a symlink when it points into the ``scripts/`` directory
+ of **this** repository (to avoid removing unrelated symlinks that happen
+ to share the same name).
+
+ Args:
+ bindir: Directory with the symlinks. Defaults to ``~/.local/bin``.
+
+ Returns an :class:`UninstallResult`.
+ """
+ if bindir is None:
+ bindir = Path.home() / ".local" / "bin"
+
+ repo_scripts = _scripts_dir()
+ outcomes: list[tuple[str, str]] = []
+ errors: list[str] = []
+
+ for name in CLI_SCRIPTS:
+ link = bindir / name
+
+ if not link.is_symlink():
+ if link.exists():
+ msg = f"skipped: {link} is not a symlink β€” refusing to remove"
+ outcomes.append((name, msg))
+ else:
+ outcomes.append((name, f"skipped: {link} does not exist"))
+ continue
+
+ # Resolve the target of the symlink
+ try:
+ target = link.resolve()
+ except OSError as exc:
+ msg = f"error: cannot resolve {link}: {exc}"
+ outcomes.append((name, msg))
+ errors.append(msg)
+ continue
+
+ # Only remove if the target is inside our scripts/ directory
+ try:
+ target.relative_to(repo_scripts)
+ except ValueError:
+ msg = f"skipped: {link} β†’ {target} is outside this repo's scripts/ β€” refusing to remove"
+ outcomes.append((name, msg))
+ continue
+
+ try:
+ link.unlink()
+ outcomes.append((name, f"removed: {link}"))
+ except OSError as exc:
+ msg = f"error: cannot unlink {link}: {exc}"
+ outcomes.append((name, msg))
+ errors.append(msg)
+
+ return UninstallResult(
+ bindir=bindir,
+ outcomes=tuple(outcomes),
+ errors=tuple(errors),
+ )
+
+
+def render_install_result(result: InstallResult) -> str:
+ """Render an :class:`InstallResult` as plain text."""
+ lines: list[str] = []
+ lines.append(f"o2b install-cli β€” {result.bindir}")
+ lines.append("-" * 40)
+ for name, msg in result.outcomes:
+ lines.append(f" {name}: {msg}")
+ if result.errors:
+ lines.append("")
+ lines.append(f"{len(result.errors)} error(s).")
+ return "\n".join(lines).rstrip() + "\n"
+
+
+def render_uninstall_result(result: UninstallResult) -> str:
+ """Render an :class:`UninstallResult` as plain text."""
+ lines: list[str] = []
+ lines.append(f"o2b uninstall --remove-cli β€” {result.bindir}")
+ lines.append("-" * 40)
+ for name, msg in result.outcomes:
+ lines.append(f" {name}: {msg}")
+ if result.errors:
+ lines.append("")
+ lines.append(f"{len(result.errors)} error(s).")
+ return "\n".join(lines).rstrip() + "\n"
diff --git a/src/open_second_brain/uninstall.py b/src/open_second_brain/uninstall.py
index 3a85e99a..b64bec9c 100644
--- a/src/open_second_brain/uninstall.py
+++ b/src/open_second_brain/uninstall.py
@@ -199,7 +199,8 @@ def render_plan(plan: UninstallPlan) -> str:
lines.append("Next steps:")
lines.append(" 1. Run the Hermes commands above to deregister the MCP server and plugin.")
lines.append(" 2. Re-run with --apply-local to remove the machine-local config directory.")
- lines.append(" 3. Delete the vault yourself if and only if you really want to lose your notes.")
+ lines.append(" 3. Add --remove-cli to also remove the o2b/vault-log symlinks from ~/.local/bin.")
+ lines.append(" 4. Delete the vault yourself if and only if you really want to lose your notes.")
lines.append("")
return "\n".join(lines).rstrip() + "\n"