Skip to content

Fastest way to scaffold your LLM powered personal knowledge base - Obsidian, Claude Code, qmd, Github

feat(cli): add use/exec/doctor, positional path, per-subcommand help

jessepinkman9900c4b20dccd209
diff --git a/.claude/skills/pack-test/SKILL.md b/.claude/skills/pack-test/SKILL.md
index 28f7032..62cd230 100644
--- a/.claude/skills/pack-test/SKILL.md
+++ b/.claude/skills/pack-test/SKILL.md
@@ -152,6 +152,39 @@ RESOLVED_B=$(npx -y claude-second-brain-$(node -p "require('./package.json').ver
[ "$RESOLVED_B" = "$HOME/.claude-second-brain/test-brain-b" ] && echo "PASS: --brain overrides default" || echo "FAIL: --brain returned '$RESOLVED_B'"
```
+### Step 9b — Verify new CLI surface (v1.1+)
+
+```bash
+CSB="npx -y claude-second-brain-$(node -p "require('./package.json').version").tgz"
+
+# `csb use` — switch default to brain-b, then back
+$CSB use test-brain-b > /dev/null && echo "PASS: csb use test-brain-b" || echo "FAIL: csb use test-brain-b"
+grep -q 'default = "test-brain-b"' ~/.claude-second-brain/config.toml && echo "PASS: default switched to brain-b" || echo "FAIL: default did not switch"
+$CSB use test-brain-a > /dev/null && echo "PASS: csb use test-brain-a (switch back)" || echo "FAIL: csb use test-brain-a"
+grep -q 'default = "test-brain-a"' ~/.claude-second-brain/config.toml && echo "PASS: default back to brain-a" || echo "FAIL: default did not revert"
+
+# `csb path qmd` (positional) should match legacy `csb path --qmd`
+POS_QMD=$($CSB path qmd)
+LEGACY_QMD=$($CSB path --qmd 2>/dev/null)
+[ "$POS_QMD" = "$LEGACY_QMD" ] && [ "$POS_QMD" = "$HOME/.claude-second-brain/test-brain-a/.qmd/index.sqlite" ] \
+ && echo "PASS: csb path qmd (positional = legacy flag)" \
+ || echo "FAIL: positional='$POS_QMD' legacy='$LEGACY_QMD'"
+
+# `csb path config` (positional) prints central config path
+[ "$($CSB path config)" = "$HOME/.claude-second-brain/config.toml" ] && echo "PASS: csb path config" || echo "FAIL: csb path config"
+
+# `csb exec -- pwd` runs inside the resolved brain's root
+PWD_OUT=$($CSB exec -- pwd)
+[ "$PWD_OUT" = "$HOME/.claude-second-brain/test-brain-a" ] && echo "PASS: csb exec -- pwd" || echo "FAIL: csb exec -- pwd returned '$PWD_OUT'"
+
+# `csb doctor` exits 0 on a fresh scaffold
+$CSB doctor > /dev/null 2>&1 && echo "PASS: csb doctor exits 0" || echo "FAIL: csb doctor exited non-zero"
+
+# Per-subcommand --help routes to topic help instead of falling through to createBrain
+$CSB rm --help 2>&1 | grep -q "csb rm —" && echo "PASS: csb rm --help" || echo "FAIL: csb rm --help fell through"
+$CSB path --help 2>&1 | grep -q "csb path —" && echo "PASS: csb path --help" || echo "FAIL: csb path --help fell through"
+```
+
### Step 10 — Final checklist
| Item | Expected | Pass? |
@@ -169,6 +202,12 @@ RESOLVED_B=$(npx -y claude-second-brain-$(node -p "require('./package.json').ver
| No unpatched tokens | No `__QMD_PATH__`, `__CSB_CONFIG__`, `__BRAIN_NAME__` anywhere in vault | |
| `~/.claude-second-brain/config.toml` | Present with `default = "test-brain-a"` and 2 `[[brains]]` entries | |
| Global skills (`~/.claude/skills/brain-{ingest,search,refresh}/SKILL.md`) | Present; reference `claude-second-brain path` + `claude-second-brain qmd`; `.csb-version` sidecar matches package version | |
+| `csb use <name>` | Rewrites `default = "…"` in config.toml | |
+| `csb path qmd` (positional) | Equal to `csb path --qmd` | |
+| `csb path config` (positional) | Prints `~/.claude-second-brain/config.toml` | |
+| `csb exec -- pwd` | Prints the resolved brain's directory | |
+| `csb doctor` | Exits 0 on a fresh scaffold | |
+| `csb <subcommand> --help` | Each subcommand routes to its own topic help (no fall-through to createBrain) | |
### Step 11 — Clean up
diff --git a/.github/workflows/pack-test.yml b/.github/workflows/pack-test.yml
index 3602069..e61b3af 100644
--- a/.github/workflows/pack-test.yml
+++ b/.github/workflows/pack-test.yml
@@ -109,6 +109,51 @@ jobs:
absent_check "global $skill has no unpatched tokens" '__QMD_PATH__\|__CSB_CONFIG__' "$HOME/.claude/skills/$skill/SKILL.md"
done
+ # New CLI surface (v1.1+): use, positional path, exec, doctor.
+ VERSION=$(node -p "require('./package.json').version")
+ CSB="npx -y claude-second-brain-${VERSION}.tgz"
+
+ cmd_check() {
+ local label="$1"; local expected="$2"; shift 2
+ local actual
+ actual=$("$@" 2>/dev/null | tail -1)
+ if [ "$actual" = "$expected" ]; then
+ echo "PASS: $label"
+ else
+ echo "FAIL: $label — expected '$expected', got '$actual'"
+ fail=1
+ fi
+ }
+
+ # `csb use` — setting current default is a no-op but must succeed
+ if $CSB use test-vault > /dev/null 2>&1; then
+ echo "PASS: csb use test-vault"
+ else
+ echo "FAIL: csb use test-vault exited non-zero"; fail=1
+ fi
+
+ # `csb path qmd` (positional) should match `csb path --qmd` (legacy)
+ POS_QMD=$($CSB path qmd 2>/dev/null)
+ LEGACY_QMD=$($CSB path --qmd 2>/dev/null)
+ if [ "$POS_QMD" = "$LEGACY_QMD" ] && [ "$POS_QMD" = "$HOME/.claude-second-brain/test-vault/.qmd/index.sqlite" ]; then
+ echo "PASS: csb path qmd (positional = legacy flag)"
+ else
+ echo "FAIL: csb path qmd — positional='$POS_QMD' legacy='$LEGACY_QMD'"; fail=1
+ fi
+
+ # `csb path config` (positional) prints central config path
+ cmd_check "csb path config" "$HOME/.claude-second-brain/config.toml" $CSB path config
+
+ # `csb exec -- pwd` runs inside the resolved brain's root
+ cmd_check "csb exec -- pwd" "$HOME/.claude-second-brain/test-vault" $CSB exec -- pwd
+
+ # `csb doctor` exits 0 on a freshly-scaffolded brain
+ if $CSB doctor > /dev/null 2>&1; then
+ echo "PASS: csb doctor exits 0"
+ else
+ echo "FAIL: csb doctor exited non-zero on fresh scaffold"; fail=1
+ fi
+
if [ "$fail" -ne 0 ]; then
echo ""
echo "One or more checks failed."
diff --git a/README.md b/README.md
index d678f15..348e147 100644
--- a/README.md
+++ b/README.md
@@ -245,16 +245,22 @@ All brains live under `~/.claude-second-brain/`. A central `config.toml` tracks
Run `npx claude-second-brain` again to create additional brains. Each gets its own folder, its own qmd index, and its own git remote — fully isolated. The global skills (`/brain-ingest`, `/brain-search`, `/brain-refresh`) always operate on the **default brain** declared in `config.toml`. The first brain you create is set as the default automatically.
-Manage brains from the CLI:
+Manage brains from the CLI (`csb` is the short alias — swap for `npx claude-second-brain` if not installed globally):
```bash
-npx claude-second-brain ls # list all brains (default marked with *)
-npx claude-second-brain rm <name> # remove a brain (deletes its folder + config entry)
-npx claude-second-brain path # print the default brain's directory
-npx claude-second-brain path --qmd # print the default brain's qmd index path
-npx claude-second-brain qmd -- query -c wiki "<terms>" # run qmd against the default brain
+csb ls # list all brains (default marked with *)
+csb use <name> # switch the default brain
+csb rm <name> # remove a brain (deletes its folder + config entry)
+csb path # print the default brain's directory
+csb path qmd # print the default brain's qmd index path
+csb path config # print ~/.claude-second-brain/config.toml
+csb qmd query -c wiki "<terms>" # run qmd against the default brain
+csb exec -- pnpm qmd:reindex # run any command inside the default brain
+csb doctor # verify tools, config, and each brain
```
+Every subcommand accepts `--help` for details (`csb rm --help`, `csb path --help`, …).
+
---
## Installing and updating skills
diff --git a/bin/create.js b/bin/create.js
index ad873e2..1cfd0b9 100755
--- a/bin/create.js
+++ b/bin/create.js
@@ -425,20 +425,131 @@ function parseConfig(content) {
return { defaultBrain: defaultMatch ? defaultMatch[1] : null, brains, header }
}
-function printHelp() {
- const lines = [
- `${pc.bold("claude-second-brain")} v${version}`,
- "",
- "Usage:",
- ` ${pc.cyan("claude-second-brain")} create a new brain (interactive)`,
- ` ${pc.cyan("claude-second-brain <name>")} create a new brain named <name>`,
- ` ${pc.cyan("claude-second-brain ls")} list all brains`,
- ` ${pc.cyan("claude-second-brain rm [<name>…]")} remove one or more brains (space to multi-select)`,
- ` ${pc.cyan("claude-second-brain path [--brain N] [flag]")} print a path (flags: --root, --qmd, --config)`,
- ` ${pc.cyan("claude-second-brain qmd [--brain N] -- …")} run qmd against the resolved brain`,
- ` ${pc.cyan("claude-second-brain help")} show this message`,
- ]
- console.log(lines.join("\n"))
+function hasHelpFlag(args) {
+ return args.some(a => a === "--help" || a === "-h")
+}
+
+async function readConfigStatus() {
+ try {
+ const content = await readFile(CSB_CONFIG, "utf8")
+ const { defaultBrain, brains } = parseConfig(content)
+ return { defaultBrain, brains }
+ } catch {
+ return { defaultBrain: null, brains: [] }
+ }
+}
+
+function printHelp(topic = "top") {
+ const c = pc.cyan
+ const topics = {
+ top: async () => {
+ const { defaultBrain, brains } = await readConfigStatus()
+ const lines = [
+ `${pc.bold("claude-second-brain")} v${version} ${pc.dim("(alias: csb)")}`,
+ "",
+ "Usage:",
+ ` ${c("csb")} create a new brain (interactive)`,
+ ` ${c("csb <name>")} create a new brain named <name>`,
+ ` ${c("csb ls")} list all brains (default marked with *)`,
+ ` ${c("csb use <name>")} set the default brain`,
+ ` ${c("csb rm [<name>…]")} remove brains + their folders`,
+ ` ${c("csb path [qmd|config|root]")} print a path (default: root)`,
+ ` ${c("csb qmd [--brain N] <qmd args…>")} run qmd against the resolved brain`,
+ ` ${c("csb exec [--brain N] -- <cmd…>")} run a command inside the resolved brain`,
+ ` ${c("csb doctor")} verify your setup and suggest fixes`,
+ ` ${c("csb help [<command>]")} show help for a command`,
+ "",
+ "Examples:",
+ ` ${c('csb qmd query -c wiki "distributed systems"')}`,
+ ` ${c("csb path qmd")}`,
+ ` ${c("csb use work")}`,
+ ` ${c("csb exec -- pnpm qmd:reindex")}`,
+ "",
+ `Config: ${pc.dim(CSB_CONFIG)}`,
+ brains.length === 0
+ ? pc.dim("No brains registered yet.")
+ : `Default brain: ${defaultBrain ? pc.cyan(defaultBrain) : pc.yellow("(none set — run `csb use <name>`)")} ${pc.dim(`(${brains.length} registered)`)}`,
+ ]
+ console.log(lines.join("\n"))
+ },
+ path: () => console.log([
+ `${pc.bold("csb path")} — print a path for the default (or named) brain`,
+ "",
+ "Usage:",
+ ` ${c("csb path [qmd|config|root] [--brain <name>]")}`,
+ "",
+ "Positional (canonical):",
+ ` ${c("root")} the brain's directory (default)`,
+ ` ${c("qmd")} the brain's qmd SQLite index`,
+ ` ${c("config")} the central config.toml`,
+ "",
+ "Flags:",
+ ` ${c("--brain <name>")} target a specific brain instead of the default`,
+ ` ${c("--root | --qmd | --config")} ${pc.dim("(deprecated — use positional form)")}`,
+ ].join("\n")),
+ qmd: () => console.log([
+ `${pc.bold("csb qmd")} — run qmd against the default (or named) brain`,
+ "",
+ "Usage:",
+ ` ${c("csb qmd [--brain <name>] [--] <qmd args…>")}`,
+ "",
+ `${pc.dim("`--` is optional; use it only to pass a literal `--brain` through to qmd.")}`,
+ "",
+ "Examples:",
+ ` ${c('csb qmd query -c wiki "kafka"')}`,
+ ` ${c("csb qmd --brain work search -c wiki kafka")}`,
+ ].join("\n")),
+ exec: () => console.log([
+ `${pc.bold("csb exec")} — run a command inside the resolved brain's directory`,
+ "",
+ "Usage:",
+ ` ${c("csb exec [--brain <name>] -- <cmd…>")}`,
+ "",
+ `Sets ${c("INDEX_PATH")} to the brain's qmd index and ${c("cwd")} to the brain's root.`,
+ "",
+ "Examples:",
+ ` ${c("csb exec -- pnpm qmd:reindex")}`,
+ ` ${c("csb exec --brain work -- git status")}`,
+ ].join("\n")),
+ use: () => console.log([
+ `${pc.bold("csb use")} — set the default brain`,
+ "",
+ "Usage:",
+ ` ${c("csb use <name>")} ${pc.dim("(aliases: default, switch)")}`,
+ "",
+ "Rewrites the `default = …` line in config.toml. Affects every command that resolves the default brain (path, qmd, exec, global skills).",
+ ].join("\n")),
+ rm: () => console.log([
+ `${pc.bold("csb rm")} — remove one or more brains`,
+ "",
+ "Usage:",
+ ` ${c("csb rm [<name>…] [-y|--yes] [--delete-remote|--keep-remote]")} ${pc.dim("(alias: remove)")}`,
+ "",
+ "Flags:",
+ ` ${c("-y, --yes")} skip the confirmation prompt`,
+ ` ${c("--delete-remote")} also delete GitHub/Cloudflare remotes (no prompt)`,
+ ` ${c("--keep-remote")} keep remotes (no prompt)`,
+ "",
+ `${pc.dim("With -y and no remote flag, remotes are preserved (safe default).")}`,
+ `${pc.dim("Without -y and no remote flag, you'll be prompted per brain.")}`,
+ ].join("\n")),
+ ls: () => console.log([
+ `${pc.bold("csb ls")} — list all brains ${pc.dim("(alias: list)")}`,
+ "",
+ "Prints each registered brain with its path, creation date, and remote.",
+ "The default brain is shown in bold with a `*` marker.",
+ ].join("\n")),
+ doctor: () => console.log([
+ `${pc.bold("csb doctor")} — verify your setup and suggest fixes`,
+ "",
+ "Checks required and optional tools (gh, mise, pnpm, wrangler),",
+ "the central config, each registered brain's path, and its qmd index.",
+ "Prints a `Fix:` hint under each failing check.",
+ ].join("\n")),
+ }
+ const renderer = topics[topic] || topics.top
+ const out = renderer()
+ if (out && typeof out.then === "function") return out
}
// Resolve a brain entry from config. Name defaults to the `default` field.
@@ -454,8 +565,8 @@ async function resolveBrain(name) {
if (!target) {
const available = brains.map(b => b.name).join(", ")
const hint = available
- ? `Pass --brain <name> (available: ${available}), or edit ${CSB_CONFIG} and set \`default = "<name>"\`.`
- : `Run \`claude-second-brain <name>\` to create your first brain.`
+ ? `Quick fix: \`csb use <name>\` (available: ${available}), or pass --brain <name>.`
+ : `Run \`csb <name>\` to create your first brain.`
throw new Error(`No default brain set in config.toml. ${hint}`)
}
const entry = brains.find(b => b.name === target)
@@ -466,17 +577,70 @@ async function resolveBrain(name) {
return entry
}
+// Rewrites config.toml so `name` is the new default. Returns {previous, current}.
+// Strips any existing `active = …` / `default = …` line from the header first.
+async function setDefaultBrain(name) {
+ let content
+ try {
+ content = await readFile(CSB_CONFIG, "utf8")
+ } catch {
+ throw new Error(`No config at ${CSB_CONFIG}. Run \`csb <name>\` to create your first brain.`)
+ }
+ const { defaultBrain, brains, header } = parseConfig(content)
+ if (!brains.find(b => b.name === name)) {
+ const available = brains.map(b => b.name).join(", ") || "(none)"
+ throw new Error(`No brain named "${name}". Available: ${available}.`)
+ }
+ if (defaultBrain === name) {
+ return { previous: name, current: name, changed: false }
+ }
+ const blocks = content.split(/\n(?=\[\[brains\]\])/)
+ let newHeader = (blocks[0] || "")
+ .replace(/^active\s*=\s*"[^"]*"\s*\n?/m, "")
+ .replace(/^default\s*=\s*"[^"]*"\s*\n?/m, "")
+ .replace(/^\s+|\s+$/g, "")
+ newHeader = `default = "${name}"${newHeader ? "\n" + newHeader : ""}`
+ const entries = blocks.slice(1).map(b => b.replace(/^\s+|\s+$/g, ""))
+ const out = [newHeader, ...entries].filter(Boolean).join("\n\n").trimEnd() + "\n"
+ await writeFile(CSB_CONFIG, out, "utf8")
+ return { previous: defaultBrain, current: name, changed: true }
+}
+
+async function cmdUse(args) {
+ const name = args.find(a => !a.startsWith("-"))
+ if (!name) {
+ throw new Error("Usage: csb use <name>")
+ }
+ const { previous, current, changed } = await setDefaultBrain(name)
+ if (!changed) {
+ console.log(`default is already ${pc.cyan(current)}`)
+ return
+ }
+ if (previous) {
+ console.log(`default: ${pc.dim(previous)} → ${pc.cyan(current)}`)
+ } else {
+ console.log(`default set to ${pc.cyan(current)}`)
+ }
+}
+
async function cmdPath(args) {
- // Parse flags: --brain <name>, --root | --qmd | --config (default: --root)
+ // Canonical: csb path [qmd|config|root] [--brain <name>]
+ // Deprecated: csb path --qmd | --config | --root
let name = null
- let mode = "root"
+ let mode = null
+ let sawLegacyFlag = false
for (let i = 0; i < args.length; i++) {
const a = args[i]
if (a === "--brain") { name = args[++i]; continue }
- if (a === "--root") { mode = "root"; continue }
- if (a === "--qmd") { mode = "qmd"; continue }
- if (a === "--config") { mode = "config"; continue }
- throw new Error(`Unknown path arg: ${a}`)
+ if (a === "--root") { mode = "root"; sawLegacyFlag = true; continue }
+ if (a === "--qmd") { mode = "qmd"; sawLegacyFlag = true; continue }
+ if (a === "--config") { mode = "config"; sawLegacyFlag = true; continue }
+ if (a === "root" || a === "qmd" || a === "config") { mode = a; continue }
+ throw new Error(`Unknown path arg: ${a}. Run \`csb help path\` for usage.`)
+ }
+ if (!mode) mode = "root"
+ if (sawLegacyFlag) {
+ process.stderr.write(`${pc.yellow("warning:")} \`--${mode}\` is deprecated — use \`csb path ${mode}\` instead.\n`)
}
if (mode === "config") {
process.stdout.write(CSB_CONFIG + "\n")
@@ -487,8 +651,9 @@ async function cmdPath(args) {
process.stdout.write(out + "\n")
}
-async function cmdQmd(args) {
- // `claude-second-brain qmd [--brain N] [--] <qmd args…>`
+// Parse [--brain <name>] [--] <rest…>. `--` is optional; use it only to pass a
+// literal `--brain` through to the inner command.
+function parseBrainAndRest(args) {
let name = null
const rest = []
for (let i = 0; i < args.length; i++) {
@@ -497,14 +662,132 @@ async function cmdQmd(args) {
if (a === "--") { rest.push(...args.slice(i + 1)); break }
rest.push(a)
}
- const brain = await resolveBrain(name)
- const result = spawnSync("npx", ["-y", "@tobilu/qmd", ...rest], {
+ return { name, rest }
+}
+
+async function runInBrain(brain, cmd) {
+ if (cmd.length === 0) {
+ throw new Error("No command to run. Usage: csb exec [--brain <name>] -- <cmd…>")
+ }
+ const result = spawnSync(cmd[0], cmd.slice(1), {
+ cwd: brain.path,
stdio: "inherit",
env: { ...process.env, INDEX_PATH: brain.qmd_index },
})
process.exit(result.status ?? 1)
}
+async function cmdQmd(args) {
+ const { name, rest } = parseBrainAndRest(args)
+ const brain = await resolveBrain(name)
+ await runInBrain(brain, ["npx", "-y", "@tobilu/qmd", ...rest])
+}
+
+async function cmdExec(args) {
+ const { name, rest } = parseBrainAndRest(args)
+ const brain = await resolveBrain(name)
+ await runInBrain(brain, rest)
+}
+
+async function cmdDoctor() {
+ const toDisplayPath = p => p && p.startsWith(homedir()) ? "~" + p.slice(homedir().length) : p
+ const ok = s => ` ${pc.green("✓")} ${s}`
+ const warn = (s, fix) => ` ${pc.yellow("⚠")} ${s}${fix ? `\n ${pc.dim("Fix:")} ${fix}` : ""}`
+ const fail = (s, fix) => ` ${pc.red("✗")} ${s}${fix ? `\n ${pc.dim("Fix:")} ${fix}` : ""}`
+ const lines = []
+ let failures = 0
+ let warnings = 0
+
+ p.intro(`${pc.bgCyan(pc.black(" csb doctor "))} v${version}`)
+
+ // Tools
+ lines.push(pc.bold("Tools"))
+ lines.push(commandExists("gh")
+ ? ok("gh (GitHub CLI) installed")
+ : (warnings++, warn("gh (GitHub CLI) not installed — required for GitHub remotes", "brew install gh | https://cli.github.com")))
+ if (commandExists("gh")) {
+ const auth = spawnSync("gh", ["auth", "status"], { stdio: "pipe" })
+ lines.push(auth.status === 0
+ ? ok("gh authenticated")
+ : (warnings++, warn("gh is installed but not authenticated", "gh auth login")))
+ }
+ lines.push(commandExists("mise")
+ ? ok("mise installed")
+ : (failures++, fail("mise not installed — required for scaffolded vaults", "npm install -g @jdxcode/mise")))
+ lines.push(commandExists("wrangler") || commandExists("npx")
+ ? ok(commandExists("wrangler") ? "wrangler installed" : "wrangler available via npx (optional — for Cloudflare Artifacts)")
+ : (warnings++, warn("wrangler not installed — required only for Cloudflare Artifacts remotes", "npm install -g wrangler")))
+
+ // Config
+ lines.push("")
+ lines.push(pc.bold("Config"))
+ let parsed = null
+ try {
+ const content = await readFile(CSB_CONFIG, "utf8")
+ parsed = parseConfig(content)
+ lines.push(ok(`config readable at ${pc.dim(toDisplayPath(CSB_CONFIG))}`))
+ } catch {
+ failures++
+ lines.push(fail(`no config at ${toDisplayPath(CSB_CONFIG)}`, "csb <name> # create your first brain"))
+ }
+
+ if (parsed) {
+ if (parsed.brains.length === 0) {
+ warnings++
+ lines.push(warn("no brains registered", "csb <name> # create your first brain"))
+ } else {
+ lines.push(ok(`${parsed.brains.length} brain${parsed.brains.length === 1 ? "" : "s"} registered`))
+ if (parsed.defaultBrain) {
+ const entry = parsed.brains.find(b => b.name === parsed.defaultBrain)
+ if (entry) {
+ lines.push(ok(`default brain: ${pc.cyan(parsed.defaultBrain)}`))
+ } else {
+ failures++
+ lines.push(fail(`default brain "${parsed.defaultBrain}" is not registered`, `csb use <name> # pick one of: ${parsed.brains.map(b => b.name).join(", ")}`))
+ }
+ } else {
+ warnings++
+ lines.push(warn("no default brain set", `csb use <name> # pick one of: ${parsed.brains.map(b => b.name).join(", ")}`))
+ }
+ }
+
+ // Per-brain checks
+ if (parsed.brains.length > 0) {
+ lines.push("")
+ lines.push(pc.bold("Brains"))
+ for (const b of parsed.brains) {
+ lines.push(pc.cyan(b.name))
+ try {
+ await access(b.path)
+ lines.push(ok(`path exists: ${pc.dim(toDisplayPath(b.path))}`))
+ } catch {
+ failures++
+ lines.push(fail(`path missing: ${toDisplayPath(b.path)}`, `csb rm ${b.name} # drop the dead entry, then recreate`))
+ }
+ try {
+ await access(b.qmd_index)
+ lines.push(ok(`qmd index exists: ${pc.dim(toDisplayPath(b.qmd_index))}`))
+ } catch {
+ warnings++
+ lines.push(warn(`qmd index missing: ${toDisplayPath(b.qmd_index)}`, `csb exec --brain ${b.name} -- pnpm qmd:reindex`))
+ }
+ }
+ }
+ }
+
+ p.note(lines.join("\n"), "Checks")
+
+ if (failures > 0) {
+ p.outro(`${pc.red(`${failures} failure${failures === 1 ? "" : "s"}`)}${warnings > 0 ? `, ${pc.yellow(`${warnings} warning${warnings === 1 ? "" : "s"}`)}` : ""}`)
+ process.exit(1)
+ }
+ if (warnings > 0) {
+ p.outro(`${pc.yellow(`${warnings} warning${warnings === 1 ? "" : "s"}`)}`)
+ return
+ }
+ p.outro(pc.green("all checks passed"))
+}
+
async function listBrains() {
const toDisplayPath = p => p && p.startsWith(homedir()) ? "~" + p.slice(homedir().length) : p
let content
@@ -537,7 +820,7 @@ async function listBrains() {
p.outro(defaultBrain ? `default: ${pc.cyan(defaultBrain)}` : "no default brain")
}
-async function removeBrain(names, { yes = false } = {}) {
+async function removeBrain(names, { yes = false, remoteMode = "ask" } = {}) {
p.intro(`${pc.bgCyan(pc.black(" claude-second-brain "))} v${version}`)
let content
@@ -592,14 +875,27 @@ async function removeBrain(names, { yes = false } = {}) {
}
}
- // Ask per-target whether to also delete the remote. Skip in -y mode — remote
- // deletion is destructive beyond the local vault and requires explicit opt-in.
+ // Decide per-target whether to also delete the remote.
+ // remoteMode === "keep" → never delete remotes
+ // remoteMode === "delete" → always delete remotes (no prompt)
+ // remoteMode === "ask" → default: prompt unless -y (then keep)
const remoteDecisions = new Map()
- if (!yes) {
+ const resolvedRemoteMode =
+ remoteMode === "keep" ? "keep"
+ : remoteMode === "delete" ? "delete"
+ : yes ? "keep" : "ask"
+
+ if (resolvedRemoteMode !== "keep") {
for (const target of targets) {
const gh = parseGithubRepo(target.git_remote)
const cf = parseCloudflareArtifact(target.git_remote)
if (!gh && !cf) continue
+ if (resolvedRemoteMode === "delete") {
+ remoteDecisions.set(target.name, gh
+ ? { kind: "github", slug: gh }
+ : { kind: "cloudflare", namespace: cf.namespace, repo: cf.repo })
+ continue
+ }
const label = gh ? `GitHub repo ${pc.cyan(gh)}` : `Cloudflare Artifact ${pc.cyan(`${cf.namespace}/${cf.repo}`)}`
const ok = await p.confirm({
message: `Also delete ${label} for "${target.name}"?`,
@@ -958,13 +1254,34 @@ async function createBrain(initialName) {
p.outro("Happy knowledge building!")
}
+const SUBCOMMANDS = new Set([
+ "help", "--help", "-h",
+ "ls", "list",
+ "rm", "remove",
+ "path",
+ "qmd",
+ "exec",
+ "use", "default", "switch",
+ "doctor",
+])
+
async function main() {
const [, , cmd, ...rest] = process.argv
if (cmd === "help" || cmd === "--help" || cmd === "-h") {
- printHelp()
+ // `csb help <topic>` or `csb help`
+ const topic = rest[0]
+ await printHelp(topic || "top")
return
}
+
+ // Per-subcommand --help / -h — intercept before any prompts run.
+ if (SUBCOMMANDS.has(cmd) && hasHelpFlag(rest)) {
+ const topicMap = { list: "ls", remove: "rm", default: "use", switch: "use" }
+ await printHelp(topicMap[cmd] || cmd)
+ return
+ }
+
if (cmd === "ls" || cmd === "list") {
await listBrains()
return
@@ -972,7 +1289,13 @@ async function main() {
if (cmd === "rm" || cmd === "remove") {
const names = rest.filter(a => !a.startsWith("-"))
const yes = rest.some(a => a === "-y" || a === "--yes")
- await removeBrain(names, { yes })
+ const deleteRemote = rest.some(a => a === "--delete-remote")
+ const keepRemote = rest.some(a => a === "--keep-remote")
+ if (deleteRemote && keepRemote) {
+ throw new Error("Cannot use --delete-remote and --keep-remote together.")
+ }
+ const remoteMode = deleteRemote ? "delete" : keepRemote ? "keep" : "ask"
+ await removeBrain(names, { yes, remoteMode })
return
}
if (cmd === "path") {
@@ -983,6 +1306,18 @@ async function main() {
await cmdQmd(rest)
return
}
+ if (cmd === "exec") {
+ await cmdExec(rest)
+ return
+ }
+ if (cmd === "use" || cmd === "default" || cmd === "switch") {
+ await cmdUse(rest)
+ return
+ }
+ if (cmd === "doctor") {
+ await cmdDoctor()
+ return
+ }
await createBrain(cmd)
}
diff --git a/docs/pages/cli.mdx b/docs/pages/cli.mdx
index cf6e70b..2c546f8 100644
--- a/docs/pages/cli.mdx
+++ b/docs/pages/cli.mdx
@@ -2,27 +2,38 @@
The `claude-second-brain` CLI creates and manages brains registered in `~/.claude-second-brain/config.toml`. Run it via `npx claude-second-brain`, `pnpm dlx claude-second-brain`, or — if installed globally with `npm i -g claude-second-brain` — the shorter `csb` alias.
-All examples below use `claude-second-brain`; substitute `csb` if you've installed it globally.
+All examples below use `csb`; substitute `npx claude-second-brain` if you haven't installed it globally.
## Commands
| Command | Description |
|---|---|
-| `claude-second-brain` | Create a new brain (interactive). |
-| `claude-second-brain <name>` | Create a new brain named `<name>`, skipping the name prompt. |
-| `claude-second-brain ls` | List all registered brains. The default brain is marked with `*`. |
-| `claude-second-brain rm [<name>…]` | Delete one or more brains (directories + `config.toml` entries). Interactive multi-select if no name is given. |
-| `claude-second-brain path [flags]` | Print the path of the default (or named) brain. |
-| `claude-second-brain qmd [flags] -- …` | Run `qmd` against the default (or named) brain. |
-| `claude-second-brain help` | Show usage. |
+| `csb` | Create a new brain (interactive). |
+| `csb <name>` | Create a new brain named `<name>`, skipping the name prompt. |
+| `csb ls` | List all registered brains. The default brain is marked with `*`. |
+| `csb use <name>` | Set the default brain. |
+| `csb rm [<name>…]` | Delete one or more brains. Interactive multi-select if no name is given. |
+| `csb path [qmd\|config\|root]` | Print a path for the default (or named) brain. |
+| `csb qmd [flags] <qmd args…>` | Run `qmd` against the default (or named) brain. |
+| `csb exec [flags] -- <cmd…>` | Run a command inside the default (or named) brain's directory. |
+| `csb doctor` | Verify your setup and suggest fixes. |
+| `csb help [<command>]` | Show usage for a command. |
-`ls` is also available as `list`, and `rm` as `remove`.
+`ls` is also available as `list`; `rm` as `remove`; `use` as `default` or `switch`.
+
+Every subcommand accepts `--help` / `-h` for usage details:
+
+```bash
+csb path --help
+csb rm --help
+csb qmd --help
+```
## Create a brain
```bash
-npx claude-second-brain # interactive — prompts for name + remote
-npx claude-second-brain my-brain # skip the name prompt
+csb # interactive — prompts for name + remote
+csb my-brain # skip the name prompt
```
Creates the brain at `~/.claude-second-brain/<name>/`, runs `mise install`, `pnpm install`, `pnpm qmd:setup`, `git init`, and registers it in `~/.claude-second-brain/config.toml`. The first brain created is set as the default.
@@ -38,65 +49,124 @@ During the interactive flow the CLI asks:
## List brains
```bash
-npx claude-second-brain ls
+csb ls
```
Prints each registered brain with its path, creation date, and git remote. The default brain is shown in bold with a `*` marker.
+## Set the default brain
+
+```bash
+csb use work # switch default to `work`
+csb default work # alias
+csb switch work # alias
+```
+
+Rewrites the `default = "…"` line in `~/.claude-second-brain/config.toml`. Every subsequent command that resolves the default brain — `path`, `qmd`, `exec`, and the global skills (`/brain-ingest`, `/brain-search`, `/brain-refresh`) — uses the new default. Errors if the name isn't registered; run `csb ls` to see the available names.
+
## Remove a brain
```bash
-npx claude-second-brain rm my-brain # single brain, confirmation prompt
-npx claude-second-brain rm a b c # remove multiple by name
-npx claude-second-brain rm my-brain --yes # skip confirmation + remote prompts
-npx claude-second-brain rm # interactive multi-select picker
+csb rm my-brain # single brain, confirmation prompt
+csb rm a b c # remove multiple by name
+csb rm my-brain --yes # skip confirmation (remotes preserved)
+csb rm a b --yes --delete-remote # no prompts; also delete remotes
+csb rm a b --yes --keep-remote # no prompts; keep remotes
+csb rm # interactive multi-select picker
```
Deletes each brain's directory under `~/.claude-second-brain/` and removes its entry from `config.toml`. If you remove the default brain and others remain, the first remaining brain becomes the new default.
**Interactive picker.** When no name is passed, the CLI shows a multi-select list — press **space** to toggle a brain, **a** to toggle all, **enter** to confirm.
-**Remote deletion prompt.** After the bulk confirmation, for each selected brain with a registered `git_remote`, the CLI asks whether to also delete the remote repo:
+**Remote deletion.** For each brain with a registered `git_remote` the CLI can also delete the remote repo:
- **GitHub** — runs `gh repo delete <owner>/<repo> --yes` (requires `gh` CLI with `delete_repo` scope).
- **Cloudflare Artifacts** — calls `DELETE /v1/api/namespaces/<ns>/repos/<repo>` using `CLOUDFLARE_API_TOKEN` or a token fetched from `wrangler auth token`.
+Behavior depends on the flags:
+
+- **No flag + interactive** — prompts per brain.
+- **`--keep-remote`** — never prompts, never deletes remotes.
+- **`--delete-remote`** — never prompts, always deletes remotes.
+- **`-y` / `--yes` with no remote flag** — remotes are preserved (safe default).
+
If a remote deletion fails (missing CLI, revoked token, etc.), the CLI prints the exact manual command and continues — the local directory and config entry are still removed.
Flags:
-- `-y`, `--yes` — skip all confirmation prompts, **including** the remote-deletion prompts. In `-y` mode remotes are left intact; delete them manually if needed.
+- `-y`, `--yes` — skip the bulk confirmation prompt.
+- `--delete-remote` — also delete remotes, no prompting.
+- `--keep-remote` — skip remote deletion, no prompting.
## Print a path
```bash
-npx claude-second-brain path # default brain root
-npx claude-second-brain path --qmd # default brain's qmd index
-npx claude-second-brain path --config # ~/.claude-second-brain/config.toml
-npx claude-second-brain path --brain work --qmd # a specific brain's qmd index
+csb path # default brain root
+csb path qmd # default brain's qmd index
+csb path config # ~/.claude-second-brain/config.toml
+csb path qmd --brain work # a specific brain's qmd index
```
+Positional:
+
+- `root` *(default)* — the brain's directory (e.g. `~/.claude-second-brain/my-brain`).
+- `qmd` — the brain's qmd SQLite index (e.g. `~/.claude-second-brain/my-brain/.qmd/index.sqlite`).
+- `config` — the central config path. Ignores `--brain`.
+
Flags:
-- `--root` *(default)* — the brain's directory (e.g. `~/.claude-second-brain/my-brain`).
-- `--qmd` — the brain's qmd SQLite index (e.g. `~/.claude-second-brain/my-brain/.qmd/index.sqlite`).
-- `--config` — the central config path. Ignores `--brain`.
- `--brain <name>` — target a specific brain instead of the default.
+- `--root` / `--qmd` / `--config` — **deprecated** flag form. Still supported; prints a warning to stderr.
Used by the global skills (`/brain-ingest`, `/brain-search`, `/brain-refresh`) to resolve paths at call time so they work from any working directory.
## Run qmd against a brain
```bash
-npx claude-second-brain qmd -- query -c wiki "distributed systems"
-npx claude-second-brain qmd --brain work -- search -c wiki "kafka"
+csb qmd query -c wiki "distributed systems"
+csb qmd --brain work search -c wiki "kafka"
+csb qmd -- --brain literal-qmd-flag # -- is optional; use to pass literal --brain to qmd
```
-Forwards all arguments after `--` to `npx @tobilu/qmd`, with `INDEX_PATH` set to the resolved brain's qmd index. Flags:
+Forwards all non-`csb` arguments to `npx @tobilu/qmd`, with `INDEX_PATH` set to the resolved brain's qmd index and `cwd` set to the brain's root.
+
+Flags:
- `--brain <name>` — target a specific brain instead of the default.
-- `--` — end of CLI flags; everything after is passed to qmd verbatim.
+- `--` — optional separator; everything after it is passed to qmd verbatim. Use only when you need to pass a literal `--brain` (or other `csb`-reserved flag) through to qmd.
+
+## Run a command inside a brain
+
+```bash
+csb exec -- pnpm qmd:reindex
+csb exec --brain work -- git status
+csb exec -- ls
+```
+
+Runs any command inside the resolved brain's directory with `INDEX_PATH` pre-set. Useful for vault-local scripts that assume you're cd'd into the brain root.
+
+Flags:
+
+- `--brain <name>` — target a specific brain instead of the default.
+- `--` — required separator before the command to run.
+
+## Verify your setup
+
+```bash
+csb doctor
+```
+
+Checks for:
+
+- Installed tools: `gh` (+ auth status), `mise`, `wrangler` (optional).
+- A parseable `~/.claude-second-brain/config.toml`.
+- At least one registered brain.
+- A resolvable default brain.
+- For each brain: the `path` directory exists; the `qmd_index` file exists.
+
+Each failed or warning check prints a `Fix:` hint with the exact command to run. Exits non-zero on failures.
## Exit status
-Every command exits non-zero on failure (invalid brain name, missing config, etc.) and writes the error to stderr.
+Every command exits non-zero on failure (invalid brain name, missing config, failed doctor check, etc.) and writes the error to stderr.
diff --git a/docs/pages/ship-log.mdx b/docs/pages/ship-log.mdx
index 4bd2792..9c373d9 100644
--- a/docs/pages/ship-log.mdx
+++ b/docs/pages/ship-log.mdx
@@ -2,6 +2,19 @@
A running record of every released version of `claude-second-brain` on npm. Newest releases first. For auto-generated notes and tags, see the [GitHub releases](https://github.com/jessepinkman9900/claude-second-brain/releases) page.
+## v1.1.0 — 2026-04-19
+
+CLI UX pass. Every addition is non-breaking — the `--` in `csb qmd -- …` and the `path --qmd` / `--config` / `--root` flag form continue to work, with a stderr deprecation notice on the flag form.
+
+**CLI:**
+- Added `csb use <name>` (aliases `default`, `switch`) to set the default brain without editing `~/.claude-second-brain/config.toml`. Runs the same header-rewrite path as `csb rm`.
+- Added `csb exec [--brain <name>] -- <cmd…>` — runs any command inside the resolved brain's directory with `INDEX_PATH` pre-set. `csb qmd` now delegates to the same helper.
+- Added `csb doctor` — checks for `gh` (+ auth), `mise`, `wrangler`, the central config, each brain's `path` and `qmd_index`, and whether the default brain resolves. Prints a `Fix:` hint under each failed check.
+- `csb path` now accepts positional subcommands: `csb path [qmd|config|root]`. The `--qmd` / `--config` / `--root` flag form still works with a stderr deprecation warning.
+- Every subcommand routes `--help` / `-h` to its own topic help. `csb help <command>` also prints per-command help. Top-level help shows the config path and current default brain.
+- `csb rm` gained `--delete-remote` and `--keep-remote` for scripting. Under `-y` with neither flag, remotes are preserved (safe default).
+- `resolveBrain()` error now points to `csb use <name>` as the fix.
+
## v1.0.0 — 2026-04-19
First major release. Brains now live at `~/.claude-second-brain/<name>/` (not the repo root), and global skills resolve paths at call time via new CLI subcommands instead of baked-in paths. Existing single-brain installs: re-run `npx claude-second-brain <name>` to migrate. Legacy `active = …` in `config.toml` is auto-rewritten to `default = …`.
diff --git a/package.json b/package.json
index bd93c6d..3ec5d18 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "claude-second-brain",
- "version": "1.0.0",
+ "version": "1.1.0",
"description": "The fastest way to start your personal knowledge base powered by Obsidian, Claude Code, qmd, and GitHub.",
"type": "module",
"bin": {
diff --git a/template/README.md b/template/README.md
index b9726c5..6a51f7a 100644
--- a/template/README.md
+++ b/template/README.md
@@ -181,13 +181,20 @@ This wraps `pnpm qmd:reindex` — you can also run that command directly if you'
## Managing brains
-From anywhere:
+From anywhere (`csb` is the short alias — use `npx claude-second-brain` if not installed globally):
```bash
-npx claude-second-brain ls # list all brains
-npx claude-second-brain rm <name> # remove a brain
+csb ls # list all brains (default marked with *)
+csb use <name> # switch the default brain
+csb rm <name> # remove a brain
+csb path qmd # print the default brain's qmd index
+csb qmd query -c wiki "<terms>" # run qmd against the default brain
+csb exec -- pnpm qmd:reindex # run any command inside the default brain
+csb doctor # verify tools, config, and each brain
```
+Run `csb help <command>` (or `csb <command> --help`) for per-command details.
+
---
## License