@brainjar/cli 0.4.1 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # brainjar
 
-[![CI](https://github.com/brainjar-sh/brainjar-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/brainjar-sh/brainjar-cli/actions/workflows/ci.yml)
+[![CI](https://github.com/brainjar-sh/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/brainjar-sh/cli/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@brainjar/cli)](https://www.npmjs.com/package/@brainjar/cli)
 [![downloads](https://img.shields.io/npm/dm/@brainjar/cli)](https://www.npmjs.com/package/@brainjar/cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -50,7 +50,8 @@ brainjar pack export|import
 brainjar hooks install|remove|status [--local]
 brainjar shell [--brain <name>] [--soul <name>] [--persona <name>]
 brainjar reset [--backend claude|codex]
-brainjar server start|stop|status|logs|local|remote|upgrade
+brainjar server start|stop|status|logs|local|remote
+brainjar upgrade [--cli-only] [--server-only]
 brainjar migrate [--dry-run] [--skip-backup]
 ```
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@brainjar/cli",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Shape how your AI thinks — composable soul, persona, and rules for AI agents",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/brainjar-sh/brainjar-cli.git"
+    "url": "https://github.com/brainjar-sh/cli.git"
   },
   "homepage": "https://brainjar.sh",
-  "bugs": "https://github.com/brainjar-sh/brainjar-cli/issues",
+  "bugs": "https://github.com/brainjar-sh/cli/issues",
   "keywords": [
     "ai",
     "agent",

package/src/cli.ts

@@ -15,6 +15,8 @@ import { hooks } from './commands/hooks.js'
 import { pack } from './commands/pack.js'
 import { server } from './commands/server.js'
 import { migrate } from './commands/migrate.js'
+import { upgrade } from './commands/upgrade.js'
+import { context } from './commands/context.js'
 
 Cli.create('brainjar', {
   description: 'Shape how your AI thinks — soul, persona, rules',
@@ -35,4 +37,6 @@ Cli.create('brainjar', {
   .command(pack)
   .command(server)
   .command(migrate)
+  .command(upgrade)
+  .command(context)
   .serve()

package/src/client.ts

@@ -1,6 +1,6 @@
 import { Errors } from 'incur'
 import { basename } from 'node:path'
-import { readConfig } from './config.js'
+import { readConfig, activeContext } from './config.js'
 import { getLocalDir } from './paths.js'
 import { access } from 'node:fs/promises'
 import { ensureRunning } from './daemon.js'
@@ -55,11 +55,12 @@ async function detectProject(explicit?: string): Promise<string | null> {
  */
 export async function createClient(options?: ClientOptions): Promise<BrainjarClient> {
   const config = await readConfig()
-  const serverUrl = (options?.serverUrl ?? config.server.url).replace(/\/$/, '')
-  const workspace = options?.workspace ?? config.workspace
+  const ctx = activeContext(config)
+  const serverUrl = (options?.serverUrl ?? ctx.url).replace(/\/$/, '')
+  const workspace = options?.workspace ?? ctx.workspace
   const session = options?.session ?? process.env.BRAINJAR_SESSION ?? null
   const defaultTimeout = options?.timeout ?? 10_000
-  const mode = config.server.mode
+  const mode = ctx.mode
 
   async function request<T>(method: string, path: string, body?: unknown, reqOpts?: RequestOptions): Promise<T> {
     const url = `${serverUrl}${path}`

package/src/commands/context.ts

@@ -0,0 +1,220 @@
+import { Cli, z } from 'incur'
+import { readConfig, writeConfig, activeContext, isLocalContext, contextNameFromUrl, uniqueContextName } from '../config.js'
+import type { RemoteContext } from '../config.js'
+import { healthCheck, ensureRunning } from '../daemon.js'
+import { getApi } from '../client.js'
+import { sync } from '../sync.js'
+import { ErrorCode, createError } from '../errors.js'
+
+const SLUG_RE = /^[a-zA-Z0-9_-]+$/
+
+const listCmd = Cli.create('list', {
+  description: 'List all contexts',
+  async run() {
+    const config = await readConfig()
+    const entries = Object.entries(config.contexts).map(([name, ctx]) => ({
+      name,
+      active: name === config.current_context,
+      mode: ctx.mode,
+      url: ctx.url,
+      workspace: ctx.workspace,
+    }))
+    return { contexts: entries }
+  },
+})
+
+const addCmd = Cli.create('add', {
+  description: 'Add a remote context',
+  args: z.object({
+    name: z.string().describe('Context name'),
+    url: z.string().describe('Server URL'),
+  }),
+  options: z.object({
+    workspace: z.string().default('default').describe('Workspace name'),
+  }),
+  async run(c) {
+    const name = c.args.name
+    const url = c.args.url.replace(/\/$/, '')
+
+    if (!SLUG_RE.test(name)) {
+      throw createError(ErrorCode.VALIDATION_ERROR, {
+        message: `Invalid context name "${name}". Use only letters, numbers, hyphens, and underscores.`,
+      })
+    }
+
+    if (name === 'local') {
+      throw createError(ErrorCode.CONTEXT_PROTECTED, { params: ['local'] })
+    }
+
+    const config = await readConfig()
+
+    if (name in config.contexts) {
+      throw createError(ErrorCode.CONTEXT_EXISTS, { params: [name] })
+    }
+
+    const health = await healthCheck({ url, timeout: 5000 })
+    if (!health.healthy) {
+      throw createError(ErrorCode.SERVER_UNREACHABLE, { params: [url] })
+    }
+
+    config.contexts[name] = {
+      url,
+      mode: 'remote',
+      workspace: c.options.workspace,
+    }
+    await writeConfig(config)
+
+    return { added: name, url, hint: `Switch with \`brainjar context use ${name}\`` }
+  },
+})
+
+const removeCmd = Cli.create('remove', {
+  description: 'Remove a context',
+  args: z.object({
+    name: z.string().describe('Context name'),
+  }),
+  async run(c) {
+    const name = c.args.name
+    const config = await readConfig()
+
+    if (name === 'local') {
+      throw createError(ErrorCode.CONTEXT_PROTECTED, { params: ['local'] })
+    }
+
+    if (!(name in config.contexts)) {
+      throw createError(ErrorCode.CONTEXT_NOT_FOUND, { params: [name] })
+    }
+
+    if (name === config.current_context) {
+      throw createError(ErrorCode.CONTEXT_ACTIVE, { params: [name] })
+    }
+
+    delete config.contexts[name]
+    await writeConfig(config)
+
+    return { removed: name }
+  },
+})
+
+const useCmd = Cli.create('use', {
+  description: 'Switch active context',
+  args: z.object({
+    name: z.string().describe('Context name'),
+  }),
+  async run(c) {
+    const name = c.args.name
+    const config = await readConfig()
+
+    if (!(name in config.contexts)) {
+      throw createError(ErrorCode.CONTEXT_NOT_FOUND, { params: [name] })
+    }
+
+    config.current_context = name
+    await writeConfig(config)
+
+    const ctx = activeContext(config)
+
+    // If switching to local, ensure running
+    if (isLocalContext(ctx)) {
+      await ensureRunning()
+    }
+
+    // Sync if server is reachable
+    const health = await healthCheck({ url: ctx.url, timeout: 3000 })
+    if (health.healthy) {
+      const api = await getApi()
+
+      // Ensure workspace exists
+      try {
+        await api.post('/api/v1/workspaces', { name: ctx.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
+      } catch (e: any) {
+        if (e.code !== 'CONFLICT') throw e
+      }
+
+      await sync({ api })
+    }
+
+    return { active: name, mode: ctx.mode, url: ctx.url, workspace: ctx.workspace }
+  },
+})
+
+const showCmd = Cli.create('show', {
+  description: 'Show context details',
+  args: z.object({
+    name: z.string().optional().describe('Context name (defaults to active)'),
+  }),
+  async run(c) {
+    const config = await readConfig()
+    const name = c.args.name ?? config.current_context
+
+    if (!(name in config.contexts)) {
+      throw createError(ErrorCode.CONTEXT_NOT_FOUND, { params: [name] })
+    }
+
+    const ctx = config.contexts[name]
+    return {
+      name,
+      active: name === config.current_context,
+      ...ctx,
+    }
+  },
+})
+
+const renameCmd = Cli.create('rename', {
+  description: 'Rename a context',
+  args: z.object({
+    old: z.string().describe('Current name'),
+    new: z.string().describe('New name'),
+  }),
+  async run(c) {
+    const oldName = c.args.old
+    const newName = c.args.new
+
+    if (oldName === 'local') {
+      throw createError(ErrorCode.CONTEXT_PROTECTED, { params: ['local'] })
+    }
+
+    if (newName === 'local') {
+      throw createError(ErrorCode.CONTEXT_PROTECTED, {
+        message: 'Cannot rename to "local" — that name is reserved.',
+      })
+    }
+
+    if (!SLUG_RE.test(newName)) {
+      throw createError(ErrorCode.VALIDATION_ERROR, {
+        message: `Invalid context name "${newName}". Use only letters, numbers, hyphens, and underscores.`,
+      })
+    }
+
+    const config = await readConfig()
+
+    if (!(oldName in config.contexts)) {
+      throw createError(ErrorCode.CONTEXT_NOT_FOUND, { params: [oldName] })
+    }
+
+    if (newName in config.contexts) {
+      throw createError(ErrorCode.CONTEXT_EXISTS, { params: [newName] })
+    }
+
+    config.contexts[newName] = config.contexts[oldName]
+    delete config.contexts[oldName]
+
+    if (config.current_context === oldName) {
+      config.current_context = newName
+    }
+
+    await writeConfig(config)
+
+    return { renamed: { from: oldName, to: newName } }
+  },
+})
+
+export const context = Cli.create('context', {
+  description: 'Manage server contexts — named server profiles',
+})
+  .command(listCmd)
+  .command(addCmd)
+  .command(removeCmd)
+  .command(useCmd)
+  .command(showCmd)
+  .command(renameCmd)

package/src/commands/init.ts

@@ -5,7 +5,7 @@ import { buildSeedBundle } from '../seeds.js'
 import { putState } from '../state.js'
 import { sync } from '../sync.js'
 import { getApi } from '../client.js'
-import { readConfig, writeConfig, type Config } from '../config.js'
+import { readConfig, writeConfig, activeContext, isLocalContext, type Config } from '../config.js'
 import { ensureBinary, upgradeServer } from '../daemon.js'
 import type { ApiImportResult } from '../api-types.js'
 
@@ -32,14 +32,18 @@ export const init = Cli.create('init', {
 
     if (!configExists) {
       const config: Config = {
-        server: {
-          url: 'http://localhost:7742',
-          mode: 'local',
-          bin: `${brainjarDir}/bin/brainjar-server`,
-          pid_file: `${brainjarDir}/server.pid`,
-          log_file: `${brainjarDir}/server.log`,
+        version: 2,
+        current_context: 'local',
+        contexts: {
+          local: {
+            url: 'http://localhost:7742',
+            mode: 'local',
+            bin: `${brainjarDir}/bin/brainjar-server`,
+            pid_file: `${brainjarDir}/server.pid`,
+            log_file: `${brainjarDir}/server.log`,
+            workspace: 'default',
+          },
         },
-        workspace: 'default',
         backend: c.options.backend as Backend,
       }
       await writeConfig(config)
@@ -48,9 +52,10 @@ export const init = Cli.create('init', {
     // 3. Ensure server binary exists and is up to date
     await ensureBinary()
     const config = await readConfig()
-    if (config.server.mode === 'local') {
+    const ctx = activeContext(config)
+    if (isLocalContext(ctx)) {
       // Only upgrade if server isn't already running (can't overwrite a running binary)
-      const health = await (await import('../daemon.js')).healthCheck({ timeout: 1000, url: config.server.url })
+      const health = await (await import('../daemon.js')).healthCheck({ timeout: 1000, url: ctx.url })
       if (!health.healthy) {
         await upgradeServer()
       }
@@ -61,7 +66,7 @@ export const init = Cli.create('init', {
 
     // 5. Ensure workspace exists (ignore conflict if already created)
     try {
-      await api.post('/api/v1/workspaces', { name: config.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
+      await api.post('/api/v1/workspaces', { name: ctx.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
     } catch (e: any) {
       if (e.code !== 'CONFLICT') throw e
     }

package/src/commands/server.ts

@@ -7,19 +7,19 @@ import {
   status as daemonStatus,
   ensureRunning,
   readLogFile,
-  upgradeServer,
 } from '../daemon.js'
-import { readConfig, writeConfig } from '../config.js'
+import { readConfig, writeConfig, activeContext, localContext, contextNameFromUrl, uniqueContextName } from '../config.js'
 import { getApi } from '../client.js'
 import { sync } from '../sync.js'
 
 const { IncurError } = Errors
 import { ErrorCode, createError } from '../errors.js'
 
-function assertLocalMode(config: { server: { mode: string } }, action: string) {
-  if (config.server.mode === 'remote') {
+function assertLocalContext(config: { current_context: string; contexts: Record<string, { mode: string }> }, action: string) {
+  const ctx = config.contexts[config.current_context]
+  if (ctx.mode === 'remote') {
     throw createError(ErrorCode.INVALID_MODE, {
-      message: `Server is in remote mode. Cannot ${action}.`,
+      message: `Active context is remote. Cannot ${action}.`,
     })
   }
 }
@@ -35,6 +35,7 @@ const statusCmd = Cli.create('status', {
       healthy: s.healthy,
       running: s.running,
       pid: s.pid,
+      serverVersion: health.serverVersion ?? null,
       latencyMs: health.latencyMs ?? null,
     }
   },
@@ -44,12 +45,13 @@ const startCmd = Cli.create('start', {
   description: 'Start the local server daemon',
   async run() {
     const config = await readConfig()
-    assertLocalMode(config, 'start')
+    assertLocalContext(config, 'start')
+    const ctx = activeContext(config)
 
     const health = await healthCheck({ timeout: 2000 })
     if (health.healthy) {
       const s = await daemonStatus()
-      return { already_running: true, pid: s.pid, url: config.server.url }
+      return { already_running: true, pid: s.pid, url: ctx.url }
     }
 
     const { pid } = await start()
@@ -58,7 +60,7 @@ const startCmd = Cli.create('start', {
     while (Date.now() < deadline) {
       await new Promise(r => setTimeout(r, 200))
       const check = await healthCheck({ timeout: 2000 })
-      if (check.healthy) return { started: true, pid, url: config.server.url }
+      if (check.healthy) return { started: true, pid, url: ctx.url }
     }
 
     throw createError(ErrorCode.SERVER_START_FAILED, {
@@ -71,7 +73,7 @@ const stopCmd = Cli.create('stop', {
   description: 'Stop the local server daemon',
   async run() {
     const config = await readConfig()
-    assertLocalMode(config, 'stop')
+    assertLocalContext(config, 'stop')
 
     const result = await stop()
     if (!result.stopped) {
@@ -89,9 +91,10 @@ const logsCmd = Cli.create('logs', {
   }),
   async run(c) {
     const config = await readConfig()
+    const local = localContext(config)
 
     if (c.options.follow) {
-      const child = spawn('tail', ['-f', '-n', String(c.options.lines), config.server.log_file], {
+      const child = spawn('tail', ['-f', '-n', String(c.options.lines), local.log_file], {
         stdio: 'inherit',
       })
       await new Promise<void>((resolve) => {
@@ -106,32 +109,31 @@ const logsCmd = Cli.create('logs', {
 })
 
 const localCmd = Cli.create('local', {
-  description: 'Switch to managed local server',
+  description: 'Switch to local server (use `brainjar context use local` instead)',
   async run() {
     const config = await readConfig()
-    config.server.url = 'http://localhost:7742'
-    config.server.mode = 'local'
+    config.current_context = 'local'
     await writeConfig(config)
 
     await ensureRunning()
 
     const api = await getApi()
+    const ctx = activeContext(config)
 
-    // Ensure workspace exists (ignore conflict if already created)
     try {
-      await api.post('/api/v1/workspaces', { name: config.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
+      await api.post('/api/v1/workspaces', { name: ctx.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
     } catch (e: any) {
       if (e.code !== 'CONFLICT') throw e
     }
 
     await sync({ api })
 
-    return { mode: 'local', url: config.server.url }
+    return { mode: 'local', url: ctx.url }
   },
 })
 
 const remoteCmd = Cli.create('remote', {
-  description: 'Switch to a remote server',
+  description: 'Switch to a remote server (use `brainjar context add` instead)',
   args: z.object({
     url: z.string().describe('Remote server URL'),
   }),
@@ -144,15 +146,26 @@ const remoteCmd = Cli.create('remote', {
     }
 
     const config = await readConfig()
-    config.server.url = url
-    config.server.mode = 'remote'
+
+    // Find existing context with this URL, or create one
+    let ctxName = Object.entries(config.contexts).find(([, ctx]) => ctx.url === url)?.[0]
+    if (!ctxName) {
+      ctxName = uniqueContextName(contextNameFromUrl(url), config.contexts)
+      config.contexts[ctxName] = {
+        url,
+        mode: 'remote',
+        workspace: 'default',
+      }
+    }
+
+    config.current_context = ctxName
     await writeConfig(config)
 
     const api = await getApi()
+    const ctx = activeContext(config)
 
-    // Ensure workspace exists (ignore conflict if already created)
     try {
-      await api.post('/api/v1/workspaces', { name: config.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
+      await api.post('/api/v1/workspaces', { name: ctx.workspace }, { headers: { 'X-Brainjar-Workspace': '' } })
     } catch (e: any) {
       if (e.code !== 'CONFLICT') throw e
     }
@@ -163,43 +176,6 @@ const remoteCmd = Cli.create('remote', {
   },
 })
 
-const upgradeCmd = Cli.create('upgrade', {
-  description: 'Upgrade the server binary to the latest version',
-  async run() {
-    const config = await readConfig()
-    assertLocalMode(config, 'upgrade')
-
-    // Stop server if running before replacing binary
-    const s = await daemonStatus()
-    const wasRunning = s.running
-
-    if (wasRunning) {
-      await stop()
-    }
-
-    const result = await upgradeServer()
-
-    if (result.alreadyLatest) {
-      if (wasRunning) await start()
-      return { upgraded: false, version: result.version, message: 'Already on latest version' }
-    }
-
-    // Restart if it was running
-    if (wasRunning) {
-      const { pid } = await start()
-      const deadline = Date.now() + 10_000
-      while (Date.now() < deadline) {
-        await new Promise(r => setTimeout(r, 200))
-        const check = await healthCheck({ timeout: 2000 })
-        if (check.healthy) return { upgraded: true, version: result.version, pid, restarted: true }
-      }
-      return { upgraded: true, version: result.version, restarted: false, warning: 'Server upgraded but failed health check after restart' }
-    }
-
-    return { upgraded: true, version: result.version }
-  },
-})
-
 export const server = Cli.create('server', {
   description: 'Manage the brainjar server',
 })
@@ -209,4 +185,3 @@ export const server = Cli.create('server', {
   .command(logsCmd)
   .command(localCmd)
   .command(remoteCmd)
-  .command(upgradeCmd)

package/src/commands/upgrade.ts

@@ -0,0 +1,35 @@
+import { Cli, z } from 'incur'
+import { upgradeCli, upgradeServerBinary } from '../upgrade.js'
+import type { UpgradeResult } from '../upgrade.js'
+import { ErrorCode, createError } from '../errors.js'
+
+export const upgrade = Cli.create('upgrade', {
+  description: 'Upgrade brainjar CLI and server to latest versions',
+  options: z.object({
+    'cli-only': z.boolean().default(false).describe('Only upgrade the CLI'),
+    'server-only': z.boolean().default(false).describe('Only upgrade the server'),
+  }),
+  async run(c) {
+    const cliOnly = c.options['cli-only']
+    const serverOnly = c.options['server-only']
+
+    if (cliOnly && serverOnly) {
+      throw createError(ErrorCode.MUTUALLY_EXCLUSIVE, {
+        message: '--cli-only and --server-only are mutually exclusive.',
+      })
+    }
+
+    const result: UpgradeResult = {}
+
+    if (!serverOnly) {
+      result.cli = await upgradeCli()
+    }
+
+    // Server upgrade always targets the local binary, regardless of active context
+    if (!cliOnly) {
+      result.server = await upgradeServerBinary()
+    }
+
+    return result
+  },
+})

package/src/config.ts

@@ -4,31 +4,67 @@ import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 import { getBrainjarDir, paths } from './paths.js'
 import type { Backend } from './paths.js'
 
-export interface ServerConfig {
+// ─── Context types ──────────────────────────────────────────────────────────
+
+export interface LocalContext {
   url: string
-  mode: 'local' | 'remote'
+  mode: 'local'
   bin: string
   pid_file: string
   log_file: string
+  workspace: string
 }
 
-export interface Config {
-  server: ServerConfig
+export interface RemoteContext {
+  url: string
+  mode: 'remote'
   workspace: string
+}
+
+export type ServerContext = LocalContext | RemoteContext
+
+export function isLocalContext(ctx: ServerContext): ctx is LocalContext {
+  return ctx.mode === 'local'
+}
+
+// ─── Config types ───────────────────────────────────────────────────────────
+
+export interface Config {
+  version: 2
+  current_context: string
+  contexts: Record<string, ServerContext>
   backend: Backend
 }
 
-function defaults(): Config {
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Get the active context from config. */
+export function activeContext(config: Config): ServerContext {
+  return config.contexts[config.current_context]
+}
+
+/** Get the local context from config. Always present. */
+export function localContext(config: Config): LocalContext {
+  return config.contexts.local as LocalContext
+}
+
+function defaultLocalContext(): LocalContext {
   const dir = getBrainjarDir()
   return {
-    server: {
-      url: 'http://localhost:7742',
-      mode: 'local',
-      bin: `${dir}/bin/brainjar-server`,
-      pid_file: `${dir}/server.pid`,
-      log_file: `${dir}/server.log`,
-    },
+    url: 'http://localhost:7742',
+    mode: 'local',
+    bin: `${dir}/bin/brainjar-server`,
+    pid_file: `${dir}/server.pid`,
+    log_file: `${dir}/server.log`,
     workspace: 'default',
+  }
+}
+
+function defaults(): Config {
+  return {
+    version: 2,
+    current_context: 'local',
+    contexts: { local: defaultLocalContext() },
     backend: 'claude',
   }
 }
@@ -41,15 +77,80 @@ function isValidBackend(v: unknown): v is Backend {
   return v === 'claude' || v === 'codex'
 }
 
+/** Derive a context name from a URL hostname. */
+export function contextNameFromUrl(url: string): string {
+  try {
+    const hostname = new URL(url).hostname
+    return hostname.replace(/\./g, '-')
+  } catch {
+    return 'remote'
+  }
+}
+
+/** Find a unique context name, appending -2, -3, etc. if needed. */
+export function uniqueContextName(base: string, existing: Record<string, unknown>): string {
+  if (!(base in existing)) return base
+  let i = 2
+  while (`${base}-${i}` in existing) i++
+  return `${base}-${i}`
+}
+
+// ─── Migration: v1 → v2 ────────────────────────────────────────────────────
+
+interface V1Config {
+  server: {
+    url: string
+    mode: 'local' | 'remote'
+    bin: string
+    pid_file: string
+    log_file: string
+  }
+  workspace: string
+  backend: Backend
+}
+
+function migrateV1(v1: V1Config): Config {
+  const dir = getBrainjarDir()
+  const localCtx: LocalContext = {
+    url: 'http://localhost:7742',
+    mode: 'local',
+    bin: v1.server.bin || `${dir}/bin/brainjar-server`,
+    pid_file: v1.server.pid_file || `${dir}/server.pid`,
+    log_file: v1.server.log_file || `${dir}/server.log`,
+    workspace: v1.workspace || 'default',
+  }
+
+  const config: Config = {
+    version: 2,
+    current_context: 'local',
+    contexts: { local: localCtx },
+    backend: v1.backend || 'claude',
+  }
+
+  if (v1.server.mode === 'remote') {
+    const name = contextNameFromUrl(v1.server.url)
+    const uniqueName = uniqueContextName(name, config.contexts)
+    config.contexts[uniqueName] = {
+      url: v1.server.url,
+      mode: 'remote',
+      workspace: v1.workspace || 'default',
+    }
+    config.current_context = uniqueName
+  }
+
+  return config
+}
+
+// ─── Read / Write ───────────────────────────────────────────────────────────
+
 /**
  * Read config from ~/.brainjar/config.yaml.
  * Returns defaults if file doesn't exist.
+ * Migrates v1 configs to v2 on read.
  * Applies env var overrides on top.
- * Throws if file exists but is corrupt YAML.
  */
 export async function readConfig(): Promise<Config> {
-  const def = defaults()
-  let config = { ...def, server: { ...def.server } }
+  let config: Config
 
   try {
     const raw = await readFile(paths.config, 'utf-8')
@@ -63,32 +164,107 @@ export async function readConfig(): Promise<Config> {
     if (parsed && typeof parsed === 'object') {
       const p = parsed as Record<string, unknown>
 
-      if (typeof p.workspace === 'string') config.workspace = p.workspace
-      if (isValidBackend(p.backend)) config.backend = p.backend
-
-      if (p.server && typeof p.server === 'object') {
-        const s = p.server as Record<string, unknown>
-        if (typeof s.url === 'string') config.server.url = s.url
-        if (isValidMode(s.mode)) config.server.mode = s.mode
-        if (typeof s.bin === 'string') config.server.bin = s.bin
-        if (typeof s.pid_file === 'string') config.server.pid_file = s.pid_file
-        if (typeof s.log_file === 'string') config.server.log_file = s.log_file
+      if (p.version === 2) {
+        // v2 config
+        config = parseV2(p)
+      } else {
+        // v1 config (no version field)
+        config = parseV1(p)
       }
+    } else {
+      config = defaults()
     }
   } catch (e) {
-    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return applyEnvOverrides(config)
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return applyEnvOverrides(defaults())
     throw e
   }
 
   return applyEnvOverrides(config)
 }
 
+function parseV2(p: Record<string, unknown>): Config {
+  const def = defaults()
+  const defLocal = localContext(def)
+  const config: Config = {
+    version: 2,
+    current_context: typeof p.current_context === 'string' ? p.current_context : 'local',
+    contexts: {},
+    backend: isValidBackend(p.backend) ? p.backend : def.backend,
+  }
+
+  if (p.contexts && typeof p.contexts === 'object') {
+    for (const [name, raw] of Object.entries(p.contexts as Record<string, unknown>)) {
+      if (!raw || typeof raw !== 'object') continue
+      const ctx = raw as Record<string, unknown>
+      if (ctx.mode === 'local') {
+        config.contexts[name] = {
+          url: typeof ctx.url === 'string' ? ctx.url : 'http://localhost:7742',
+          mode: 'local',
+          bin: typeof ctx.bin === 'string' ? ctx.bin : defLocal.bin,
+          pid_file: typeof ctx.pid_file === 'string' ? ctx.pid_file : defLocal.pid_file,
+          log_file: typeof ctx.log_file === 'string' ? ctx.log_file : defLocal.log_file,
+          workspace: typeof ctx.workspace === 'string' ? ctx.workspace : 'default',
+        }
+      } else {
+        config.contexts[name] = {
+          url: typeof ctx.url === 'string' ? ctx.url : '',
+          mode: 'remote',
+          workspace: typeof ctx.workspace === 'string' ? ctx.workspace : 'default',
+        }
+      }
+    }
+  }
+
+  // Ensure local context always exists
+  if (!config.contexts.local) {
+    config.contexts.local = defaultLocalContext()
+  }
+
+  // Ensure current_context points to an existing context
+  if (!(config.current_context in config.contexts)) {
+    config.current_context = 'local'
+  }
+
+  return config
+}
+
+function parseV1(p: Record<string, unknown>): Config {
+  const dir = getBrainjarDir()
+  const v1: V1Config = {
+    server: {
+      url: 'http://localhost:7742',
+      mode: 'local',
+      bin: `${dir}/bin/brainjar-server`,
+      pid_file: `${dir}/server.pid`,
+      log_file: `${dir}/server.log`,
+    },
+    workspace: 'default',
+    backend: 'claude',
+  }
+
+  if (typeof p.workspace === 'string') v1.workspace = p.workspace
+  if (isValidBackend(p.backend)) v1.backend = p.backend
+
+  if (p.server && typeof p.server === 'object') {
+    const s = p.server as Record<string, unknown>
+    if (typeof s.url === 'string') v1.server.url = s.url
+    if (isValidMode(s.mode)) v1.server.mode = s.mode
+    if (typeof s.bin === 'string') v1.server.bin = s.bin
+    if (typeof s.pid_file === 'string') v1.server.pid_file = s.pid_file
+    if (typeof s.log_file === 'string') v1.server.log_file = s.log_file
+  }
+
+  return migrateV1(v1)
+}
+
 function applyEnvOverrides(config: Config): Config {
+  const ctx = activeContext(config)
+
   const url = process.env.BRAINJAR_SERVER_URL
-  if (typeof url === 'string' && url) config.server.url = url
+  if (typeof url === 'string' && url) ctx.url = url
 
   const workspace = process.env.BRAINJAR_WORKSPACE
-  if (typeof workspace === 'string' && workspace) config.workspace = workspace
+  if (typeof workspace === 'string' && workspace) ctx.workspace = workspace
 
   const backend = process.env.BRAINJAR_BACKEND
   if (isValidBackend(backend)) config.backend = backend
@@ -98,21 +274,36 @@ function applyEnvOverrides(config: Config): Config {
 
 /**
  * Write config to ~/.brainjar/config.yaml.
- * Atomic write (tmp + rename).
+ * Always writes v2 format. Atomic write (tmp + rename).
  */
 export async function writeConfig(config: Config): Promise<void> {
-  const doc = {
-    server: {
-      url: config.server.url,
-      mode: config.server.mode,
-      bin: config.server.bin,
-      pid_file: config.server.pid_file,
-      log_file: config.server.log_file,
-    },
-    workspace: config.workspace,
+  const doc: Record<string, unknown> = {
+    version: 2,
+    current_context: config.current_context,
+    contexts: {} as Record<string, unknown>,
     backend: config.backend,
   }
 
+  const contexts = doc.contexts as Record<string, unknown>
+  for (const [name, ctx] of Object.entries(config.contexts)) {
+    if (isLocalContext(ctx)) {
+      contexts[name] = {
+        url: ctx.url,
+        mode: ctx.mode,
+        bin: ctx.bin,
+        pid_file: ctx.pid_file,
+        log_file: ctx.log_file,
+        workspace: ctx.workspace,
+      }
+    } else {
+      contexts[name] = {
+        url: ctx.url,
+        mode: ctx.mode,
+        workspace: ctx.workspace,
+      }
+    }
+  }
+
   await mkdir(dirname(paths.config), { recursive: true })
   const tmp = `${paths.config}.tmp`
   await writeFile(tmp, stringifyYaml(doc))

package/src/daemon.ts

@@ -4,17 +4,39 @@ import { readFile, writeFile, rm, access, open, chmod, mkdir } from 'node:fs/pro
 import { dirname, join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { Errors } from 'incur'
-import { readConfig } from './config.js'
+import { readConfig, activeContext, localContext } from './config.js'
 import { ErrorCode, createError } from './errors.js'
 
 export const DIST_BASE = 'https://get.brainjar.sh/brainjar-server'
 
+/**
+ * Compare two semver strings. Returns -1, 0, or 1.
+ * Strips leading 'v' prefix. Only compares major.minor.patch.
+ */
+export function compareSemver(a: string, b: string): number {
+  const parse = (v: string) => v.replace(/^v/, '').split('.').map(Number)
+  const pa = parse(a)
+  const pb = parse(b)
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0)
+    if (diff !== 0) return diff > 0 ? 1 : -1
+  }
+  return 0
+}
+
 const { IncurError } = Errors
 
+/**
+ * Minimum server version this CLI is compatible with.
+ * Bump when the CLI depends on server features/API changes.
+ */
+export const MIN_SERVER_VERSION = '0.2.1'
+
 export interface HealthStatus {
   healthy: boolean
   url: string
   latencyMs?: number
+  serverVersion?: string
   error?: string
 }
 
@@ -26,13 +48,27 @@ export interface DaemonStatus {
   healthy: boolean
 }
 
+/**
+ * Assert the server version is compatible with this CLI.
+ * No-op if the server doesn't report a version (old servers).
+ */
+function assertCompatible(serverVersion: string | undefined): void {
+  if (!serverVersion) return
+  if (compareSemver(serverVersion, MIN_SERVER_VERSION) < 0) {
+    throw createError(ErrorCode.SERVER_INCOMPATIBLE, {
+      message: `Server ${serverVersion} is incompatible with this CLI (requires >= ${MIN_SERVER_VERSION}).`,
+    })
+  }
+}
+
 /**
  * Check if the server is healthy.
  * Returns health status without throwing.
  */
 export async function healthCheck(options?: { timeout?: number; url?: string }): Promise<HealthStatus> {
   const config = await readConfig()
-  const url = options?.url ?? config.server.url
+  const ctx = activeContext(config)
+  const url = options?.url ?? ctx.url
   const timeout = options?.timeout ?? 2000
   const start = Date.now()
 
@@ -44,9 +80,9 @@ export async function healthCheck(options?: { timeout?: number; url?: string }):
 
     if (response.status === 200) {
       try {
-        const body = await response.json() as { status?: string }
+        const body = await response.json() as { status?: string; version?: string }
         if (body.status === 'ok') {
-          return { healthy: true, url, latencyMs }
+          return { healthy: true, url, latencyMs, serverVersion: body.version }
         }
       } catch {}
       return { healthy: true, url, latencyMs }
@@ -200,7 +236,8 @@ export async function downloadAndVerify(binPath: string, versionBase: string): P
  */
 export async function ensureBinary(): Promise<void> {
   const config = await readConfig()
-  const binPath = config.server.bin
+  const local = localContext(config)
+  const binPath = local.bin
 
   try {
     await access(binPath)
@@ -221,7 +258,8 @@ export async function ensureBinary(): Promise<void> {
 export async function upgradeServer(): Promise<{ version: string; alreadyLatest: boolean }> {
   const { getInstalledServerVersion, setInstalledServerVersion } = await import('./version-check.js')
   const config = await readConfig()
-  const binPath = config.server.bin
+  const local = localContext(config)
+  const binPath = local.bin
 
   const version = await fetchLatestVersion()
   const installed = await getInstalledServerVersion()
@@ -242,7 +280,8 @@ export async function upgradeServer(): Promise<{ version: string; alreadyLatest:
  */
 export async function start(): Promise<{ pid: number }> {
   const config = await readConfig()
-  const { bin, pid_file, log_file, url } = config.server
+  const local = localContext(config)
+  const { bin, pid_file, log_file, url } = local
 
   try {
     await access(bin)
@@ -290,7 +329,7 @@ export async function start(): Promise<{ pid: number }> {
  */
 export async function stop(): Promise<{ stopped: boolean }> {
   const config = await readConfig()
-  const { pid_file } = config.server
+  const { pid_file } = localContext(config)
 
   const pid = await readPid(pid_file)
   if (pid === null) return { stopped: false }
@@ -324,15 +363,16 @@ export async function stop(): Promise<{ stopped: boolean }> {
  */
 export async function status(): Promise<DaemonStatus> {
   const config = await readConfig()
-  const { mode, url, pid_file } = config.server
+  const ctx = activeContext(config)
+  const local = localContext(config)
 
-  const pid = await readPid(pid_file)
+  const pid = await readPid(local.pid_file)
   const running = pid !== null && isAlive(pid)
-  const health = await healthCheck({ timeout: 2000, url })
+  const health = await healthCheck({ timeout: 2000, url: ctx.url })
 
   return {
-    mode,
-    url,
+    mode: ctx.mode,
+    url: ctx.url,
     running,
     pid: running ? pid : null,
     healthy: health.healthy,
@@ -346,7 +386,7 @@ export async function readLogFile(options?: { lines?: number }): Promise<string>
   const config = await readConfig()
   const lines = options?.lines ?? 50
   try {
-    const content = await readFile(config.server.log_file, 'utf-8')
+    const content = await readFile(localContext(config).log_file, 'utf-8')
     const allLines = content.trimEnd().split('\n')
     return allLines.slice(-lines).join('\n')
   } catch (e) {
@@ -363,21 +403,25 @@ export async function readLogFile(options?: { lines?: number }): Promise<string>
  */
 export async function ensureRunning(): Promise<void> {
   const config = await readConfig()
-  const { mode, url } = config.server
+  const ctx = activeContext(config)
+  const local = localContext(config)
 
   // Check health first — fast path
-  const health = await healthCheck({ timeout: 2000, url })
-  if (health.healthy) return
+  const health = await healthCheck({ timeout: 2000, url: ctx.url })
+  if (health.healthy) {
+    assertCompatible(health.serverVersion)
+    return
+  }
 
-  if (mode === 'remote') {
+  if (ctx.mode === 'remote') {
     throw createError(ErrorCode.SERVER_UNREACHABLE, {
-      params: [url],
-      hint: `Check the URL or run 'brainjar server remote <url>'.`,
+      params: [ctx.url],
+      hint: `Check the URL or run 'brainjar context add <name> <url>'.`,
     })
   }
 
   // Local mode: auto-start
-  await cleanStalePid(config.server.pid_file)
+  await cleanStalePid(local.pid_file)
 
   try {
     await start()
@@ -385,7 +429,7 @@ export async function ensureRunning(): Promise<void> {
     if (e instanceof IncurError) throw e
     throw createError(ErrorCode.SERVER_START_FAILED, {
       message: 'Failed to start brainjar server.',
-      hint: `Check ${config.server.log_file}`,
+      hint: `Check ${local.log_file}`,
     })
   }
 
@@ -393,12 +437,15 @@ export async function ensureRunning(): Promise<void> {
   const deadline = Date.now() + 10_000
   while (Date.now() < deadline) {
     await new Promise(r => setTimeout(r, 200))
-    const check = await healthCheck({ timeout: 2000, url })
-    if (check.healthy) return
+    const check = await healthCheck({ timeout: 2000, url: ctx.url })
+    if (check.healthy) {
+      assertCompatible(check.serverVersion)
+      return
+    }
   }
 
   throw createError(ErrorCode.SERVER_START_FAILED, {
     message: 'Server started but failed health check after 10s.',
-    hint: `Check ${config.server.log_file}`,
+    hint: `Check ${local.log_file}`,
   })
 }

package/src/errors.ts

@@ -53,12 +53,19 @@ export const ErrorCode = {
   SERVER_UNREACHABLE: 'SERVER_UNREACHABLE',
   BINARY_NOT_FOUND: 'BINARY_NOT_FOUND',
   SERVER_START_FAILED: 'SERVER_START_FAILED',
+  SERVER_INCOMPATIBLE: 'SERVER_INCOMPATIBLE',
 
   // Validation
   MUTUALLY_EXCLUSIVE: 'MUTUALLY_EXCLUSIVE',
   MISSING_ARG: 'MISSING_ARG',
   NO_OVERRIDES: 'NO_OVERRIDES',
 
+  // Contexts
+  CONTEXT_NOT_FOUND: 'CONTEXT_NOT_FOUND',
+  CONTEXT_PROTECTED: 'CONTEXT_PROTECTED',
+  CONTEXT_EXISTS: 'CONTEXT_EXISTS',
+  CONTEXT_ACTIVE: 'CONTEXT_ACTIVE',
+
   // Other
   INVALID_MODE: 'INVALID_MODE',
   SHELL_ERROR: 'SHELL_ERROR',
@@ -99,6 +106,12 @@ export const Messages: Partial<Record<ErrorCode, string | ((...args: string[]) =
   PACK_NOT_DIR: (path: string) => `Pack path "${path}" is a file, not a directory. Packs are directories.`,
   PACK_NOT_FOUND: (path: string) => `Pack path "${path}" does not exist.`,
 
+  // Contexts
+  CONTEXT_NOT_FOUND: (name: string) => `Context "${name}" not found.`,
+  CONTEXT_EXISTS: (name: string) => `Context "${name}" already exists.`,
+  CONTEXT_PROTECTED: (name: string) => `Context "${name}" is protected and cannot be removed or renamed.`,
+  CONTEXT_ACTIVE: (name: string) => `Context "${name}" is the active context. Switch first.`,
+
   // Infra
   SERVER_UNREACHABLE: (url: string) => `Cannot reach server at ${url}`,
 }
@@ -132,10 +145,17 @@ export const Hints: Partial<Record<ErrorCode, string | ((...args: string[]) => s
   PACK_DIR_EXISTS: 'Remove the directory first, or use --out to write elsewhere.',
   PACK_NO_MANIFEST: 'A valid pack needs a pack.yaml at its root.',
 
+  // Contexts
+  CONTEXT_NOT_FOUND: 'List available contexts: `brainjar context list`',
+  CONTEXT_EXISTS: 'Pick a different name.',
+  CONTEXT_PROTECTED: 'The local context is always present and cannot be modified.',
+  CONTEXT_ACTIVE: 'Switch to a different context first: `brainjar context use <name>`',
+
   // Infra
   BINARY_NOT_FOUND: 'Install the server: `brainjar init`',
   SERVER_UNREACHABLE: 'Start the server: `brainjar server start`, or set a remote: `brainjar server remote <url>`',
   SERVER_START_FAILED: 'Check server logs: `brainjar server logs`',
+  SERVER_INCOMPATIBLE: 'Run `brainjar upgrade` to update both CLI and server.',
   SERVER_UNAVAILABLE: 'Server is starting up. Retry in a moment, or check: `brainjar server status`',
   UNAUTHORIZED: 'Verify server config: `brainjar server status`',
   SERVER_ERROR: 'Check server logs: `brainjar server logs`',

package/src/upgrade.ts

@@ -0,0 +1,121 @@
+import { execFile } from 'node:child_process'
+import {
+  healthCheck,
+  start,
+  stop,
+  status as daemonStatus,
+  upgradeServer,
+} from './daemon.js'
+import { checkForUpdates } from './version-check.js'
+import { ErrorCode, createError } from './errors.js'
+import pkg from '../package.json'
+
+export interface ComponentResult {
+  upgraded: boolean
+  from: string
+  to: string
+  message?: string
+}
+
+export interface ServerResult extends ComponentResult {
+  restarted?: boolean
+}
+
+export interface UpgradeResult {
+  cli?: ComponentResult
+  server?: ServerResult
+}
+
+/**
+ * Detect which package manager installed brainjar.
+ * Checks the runtime binary path first, then falls back to npm.
+ */
+export function detectPackageManager(): 'bun' | 'npm' {
+  const argv0 = process.argv[0] ?? ''
+  if (argv0.includes('bun')) return 'bun'
+  return 'npm'
+}
+
+/** Shell out to a package manager and capture stdout/stderr. */
+function exec(cmd: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: 120_000 }, (error, stdout, stderr) => {
+      if (error) reject(Object.assign(error, { stderr }))
+      else resolve({ stdout, stderr })
+    })
+  })
+}
+
+/**
+ * Upgrade the CLI npm package to latest.
+ */
+export async function upgradeCli(): Promise<ComponentResult> {
+  const currentVersion = pkg.version
+
+  // Check if already on latest
+  const updates = await checkForUpdates(currentVersion)
+  if (!updates?.cli) {
+    return { upgraded: false, from: currentVersion, to: currentVersion, message: 'Already on latest version' }
+  }
+
+  const latestVersion = updates.cli.latest
+  const pm = detectPackageManager()
+
+  try {
+    if (pm === 'bun') {
+      await exec('bun', ['install', '-g', `@brainjar/cli@${latestVersion}`])
+    } else {
+      await exec('npm', ['install', '-g', `@brainjar/cli@${latestVersion}`])
+    }
+  } catch (e: any) {
+    const stderr = e.stderr ?? e.message ?? ''
+    const isPermission = stderr.includes('EACCES') || stderr.includes('permission')
+    throw createError(ErrorCode.SHELL_ERROR, {
+      message: `Failed to upgrade CLI via ${pm}: ${stderr.trim()}`,
+      hint: isPermission
+        ? `Try running with sudo, or fix npm permissions: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally`
+        : 'Check your network connection and try again.',
+    })
+  }
+
+  return { upgraded: true, from: currentVersion, to: latestVersion }
+}
+
+/**
+ * Upgrade the server binary. Handles stop/restart lifecycle.
+ */
+export async function upgradeServerBinary(): Promise<ServerResult> {
+  const { getInstalledServerVersion } = await import('./version-check.js')
+  const installedVersion = (await getInstalledServerVersion()) ?? 'unknown'
+
+  // Stop server if running before replacing binary
+  const s = await daemonStatus()
+  const wasRunning = s.running
+
+  if (wasRunning) {
+    await stop()
+  }
+
+  const result = await upgradeServer()
+
+  if (result.alreadyLatest) {
+    if (wasRunning) await start()
+    return { upgraded: false, from: installedVersion, to: result.version, message: 'Already on latest version' }
+  }
+
+  // Restart if it was running
+  if (wasRunning) {
+    await start()
+    const deadline = Date.now() + 10_000
+    while (Date.now() < deadline) {
+      await new Promise(r => setTimeout(r, 200))
+      const check = await healthCheck({ timeout: 2000 })
+      if (check.healthy) {
+        return { upgraded: true, from: installedVersion, to: result.version, restarted: true }
+      }
+    }
+    return { upgraded: true, from: installedVersion, to: result.version, restarted: false, message: 'Upgraded but failed health check after restart' }
+  }
+
+  return { upgraded: true, from: installedVersion, to: result.version }
+}

package/src/version-check.ts

@@ -126,11 +126,11 @@ export async function renderUpdateBanner(currentCliVersion: string): Promise<str
   const lines: string[] = []
 
   if (updates.cli) {
-    lines.push(`  ⬆ brainjar ${updates.cli.latest} available (current: ${updates.cli.current}) — npm update -g @brainjar/cli`)
+    lines.push(`  ⬆ brainjar ${updates.cli.latest} available (current: ${updates.cli.current}) — brainjar upgrade`)
   }
 
   if (updates.server) {
-    lines.push(`  ⬆ server ${updates.server.latest} available (current: ${updates.server.current}) — brainjar server upgrade`)
+    lines.push(`  ⬆ server ${updates.server.latest} available (current: ${updates.server.current}) — brainjar upgrade`)
   }
 
   return lines.length > 0 ? lines.join('\n') : undefined