Fastest way to scaffold your LLM powered personal knowledge base - Obsidian, Claude Code, qmd, Github
JavaScript aiampclaude-codecodexcursorgithubknowledge-baseknowledge-graphknowledge-managementllmobsidianobsidian-vaultqmdsecond-brain
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.mdindex 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 updiff --git a/.github/workflows/pack-test.yml b/.github/workflows/pack-test.ymlindex 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 ]; thenecho ""echo "One or more checks failed."diff --git a/README.md b/README.mdindex d678f15..348e147 100644--- a/README.md+++ b/README.md@@ -245,16 +245,22 @@ All brains live under `~/.claude-second-brain/`. A central `config.toml` tracksRun `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 skillsdiff --git a/bin/create.js b/bin/create.jsindex 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 | --rootlet name = null- let mode = "root"+ let mode = null+ let sawLegacyFlag = falsefor (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 = nullconst 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) : plet 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.argvif (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.mdxindex 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.mdxindex 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-19First 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.jsonindex 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.mdindex 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