bod-cli 0.5.9 → 0.7.4

package/.cursor/skills/using-bod-cli/SKILL.md

@@ -134,6 +134,72 @@ bod env set my-api -f .env            # bulk set from .env file
 bod env unset my-api OLD_VAR
 ```
 
+### `bod db get|set|update|push|delete|query <path>`
+Read and write the per-app BodDB. Requires `database: true` in `bodify.yaml`.
+
+**Target resolution** (auto-detected, in order):
+1. **`.bodify/serve.info.json`** — written by `bod serve` on startup (port + admin password).
+2. **`.env` `BODDB_ADMIN_PASSWORD` + `bodify.yaml database.port`** — direct to `http://127.0.0.1:<port>`.
+3. **Bodify agent proxy** — for deployed apps. Auth via `BODIFY_API_KEY`; the agent injects the per-instance admin password when forwarding. `-l/--local` selects the local agent.
+
+**Unknown flags throw** — typos like `--wheree` or `--filtr` exit with an "Unknown argument(s)" error listing the allowed flags. This is deliberate to prevent silent no-ops.
+
+#### Commands
+
+```bash
+# READ — shallow by default (prevents choking on large nodes).
+bod db read /                                   # explore root: [{key, isLeaf, count}, ...]
+bod db read users                               # shallow listing of users/
+bod db read users/123                           # top-level keys of this node
+bod db read users/123 -d                        # deep read (full subtree)
+bod db read users -n 50 --offset 100            # shallow with paging
+bod db read users/123 -d -o snapshot.json       # deep + write to file
+
+# WRITE — full replace (like PUT). Any existing subkeys not in the new value are deleted.
+bod db write users/123 '{"name":"alice"}'       # replace node
+echo '{"name":"alice"}' | bod db write users/123   # via stdin
+bod db write users/123 -f user.json             # via file
+
+# UPDATE — shallow merge (like PATCH). Preserves existing subkeys not in the patch.
+bod db update users/123 '{"age":30}'            # merges into existing node
+
+# PUSH — append to a list-style path, auto-generates key.
+bod db push messages '{"text":"hi"}'            # → messages/<new-id>
+
+# DELETE — requires -y/--confirm to execute.
+bod db delete users/123 -y
+
+# QUERY — shallow by default (returns only _path/_key per match). Pass -d for full docs.
+# Two filter syntaxes (repeatable, can be mixed):
+#   --filter (-f)  shorthand:   field=value  field!=value  field>N  field>=N  field<N  field<=N
+#   --where  (-w)  canonical:   field:op:value  where op ∈ eq|ne|gt|gte|lt|lte|in|contains
+bod db query users --filter "email=alice@x.com"
+bod db query users --filter "age>=18" --filter "status=active" --limit 10
+bod db query users --where age:gte:18 --where status:eq:active --limit 10
+bod db query users --filter "public=true" --order createdAt:desc --limit 20 -d
+```
+
+#### Semantics
+
+| Command | HTTP | Semantics |
+|---|---|---|
+| `get`    | GET `/db/<p>[?shallow=1]` | Shallow = top-level keys + counts. Deep (`-d`) = full subtree. |
+| `set`    | PUT `/db/<p>`             | **Full replace.** Removes keys not in the new value. |
+| `update` | PATCH `/db/<p>`           | **Shallow merge.** Preserves untouched keys. |
+| `push`   | POST `/db/<p>`            | Appends with auto-id (list semantics). Returns `{key}`. |
+| `delete` | DELETE `/db/<p>`          | Recursive delete. Requires `-y`. |
+| `query`  | POST `/query/<p>`         | Filter/order/limit over a collection. Shallow = `[{_path, _key}]`, deep = full docs. |
+
+#### --filter vs --where
+
+`--filter` is the ergonomic shorthand (`field=value`, `field!=value`, `field>=N`, etc.) — matches Firebase/Mongo muscle memory. Use it in most cases.
+
+`--where` is the canonical form when your value contains `=` or spaces, or when you need ops not in the shorthand (`in`, `contains`). Both are repeatable and can be mixed in one invocation.
+
+Value parsing: the CLI tries `JSON.parse(value)` first (so `true`, `42`, `null`, `"quoted"` become the right type), and falls back to a raw string.
+
+**App-side prerequisite for agent-proxy mode:** the app must be deployed with `database: true`. Existing apps deployed before per-instance admin-password persistence must be redeployed once — until then the proxy returns 409 with an actionable error.
+
 ### `bod add <pkg>` / `bod remove <pkg>`
 Registry-aware package management. If Bodify registry is enabled, `bun add` uses it automatically.
 

package/dist/cli.js

@@ -12287,6 +12287,55 @@ var require_public_api = __commonJS((exports) => {
   exports.stringify = stringify;
 });
 
+// node_modules/yaml/dist/index.js
+var require_dist = __commonJS((exports) => {
+  var composer = require_composer();
+  var Document = require_Document();
+  var Schema = require_Schema();
+  var errors3 = require_errors();
+  var Alias = require_Alias();
+  var identity = require_identity();
+  var Pair = require_Pair();
+  var Scalar = require_Scalar();
+  var YAMLMap = require_YAMLMap();
+  var YAMLSeq = require_YAMLSeq();
+  var cst = require_cst();
+  var lexer = require_lexer();
+  var lineCounter = require_line_counter();
+  var parser = require_parser();
+  var publicApi = require_public_api();
+  var visit = require_visit();
+  exports.Composer = composer.Composer;
+  exports.Document = Document.Document;
+  exports.Schema = Schema.Schema;
+  exports.YAMLError = errors3.YAMLError;
+  exports.YAMLParseError = errors3.YAMLParseError;
+  exports.YAMLWarning = errors3.YAMLWarning;
+  exports.Alias = Alias.Alias;
+  exports.isAlias = identity.isAlias;
+  exports.isCollection = identity.isCollection;
+  exports.isDocument = identity.isDocument;
+  exports.isMap = identity.isMap;
+  exports.isNode = identity.isNode;
+  exports.isPair = identity.isPair;
+  exports.isScalar = identity.isScalar;
+  exports.isSeq = identity.isSeq;
+  exports.Pair = Pair.Pair;
+  exports.Scalar = Scalar.Scalar;
+  exports.YAMLMap = YAMLMap.YAMLMap;
+  exports.YAMLSeq = YAMLSeq.YAMLSeq;
+  exports.CST = cst;
+  exports.Lexer = lexer.Lexer;
+  exports.LineCounter = lineCounter.LineCounter;
+  exports.Parser = parser.Parser;
+  exports.parse = publicApi.parse;
+  exports.parseAllDocuments = publicApi.parseAllDocuments;
+  exports.parseDocument = publicApi.parseDocument;
+  exports.stringify = publicApi.stringify;
+  exports.visit = visit.visit;
+  exports.visitAsync = visit.visitAsync;
+});
+
 // src/cli.ts
 init_dist2();
 // node_modules/@inquirer/core/dist/esm/lib/key.js
@@ -18678,6 +18727,9 @@ class BodClient {
   del(path) {
     return this.request("DELETE", path);
   }
+  patch(path, body) {
+    return this.request("PATCH", path, body);
+  }
 }
 
 // src/utils/output.ts
@@ -18755,61 +18807,14 @@ var login_default = defineCommand2({
 });
 
 // src/utils/resolve.ts
+var import_yaml = __toESM(require_dist(), 1);
 import { readFileSync as readFileSync3 } from "fs";
-
-// node_modules/yaml/dist/index.js
-var composer = require_composer();
-var Document = require_Document();
-var Schema = require_Schema();
-var errors3 = require_errors();
-var Alias = require_Alias();
-var identity = require_identity();
-var Pair = require_Pair();
-var Scalar = require_Scalar();
-var YAMLMap = require_YAMLMap();
-var YAMLSeq = require_YAMLSeq();
-var cst = require_cst();
-var lexer = require_lexer();
-var lineCounter = require_line_counter();
-var parser = require_parser();
-var publicApi = require_public_api();
-var visit = require_visit();
-var $Composer = composer.Composer;
-var $Document = Document.Document;
-var $Schema = Schema.Schema;
-var $YAMLError = errors3.YAMLError;
-var $YAMLParseError = errors3.YAMLParseError;
-var $YAMLWarning = errors3.YAMLWarning;
-var $Alias = Alias.Alias;
-var $isAlias = identity.isAlias;
-var $isCollection = identity.isCollection;
-var $isDocument = identity.isDocument;
-var $isMap = identity.isMap;
-var $isNode = identity.isNode;
-var $isPair = identity.isPair;
-var $isScalar = identity.isScalar;
-var $isSeq = identity.isSeq;
-var $Pair = Pair.Pair;
-var $Scalar = Scalar.Scalar;
-var $YAMLMap = YAMLMap.YAMLMap;
-var $YAMLSeq = YAMLSeq.YAMLSeq;
-var $Lexer = lexer.Lexer;
-var $LineCounter = lineCounter.LineCounter;
-var $Parser = parser.Parser;
-var $parse = publicApi.parse;
-var $parseAllDocuments = publicApi.parseAllDocuments;
-var $parseDocument = publicApi.parseDocument;
-var $stringify = publicApi.stringify;
-var $visit = visit.visit;
-var $visitAsync = visit.visitAsync;
-
-// src/utils/resolve.ts
 var _parsedYaml;
 function readYaml() {
   if (_parsedYaml !== undefined)
     return _parsedYaml;
   try {
-    _parsedYaml = $parse(readFileSync3("bodify.yaml", "utf-8"));
+    _parsedYaml = import_yaml.parse(readFileSync3("bodify.yaml", "utf-8"));
   } catch {
     _parsedYaml = null;
   }
@@ -19551,6 +19556,7 @@ console.log(\`Server running on :\${port}\`);
 ];
 
 // src/commands/init/init.ts
+var import_yaml2 = __toESM(require_dist(), 1);
 function detectAppType(dir) {
   if (existsSync3(join3(dir, "api.ts")))
     return "caab";
@@ -19740,7 +19746,7 @@ var init_default = defineCommand2({
       let yamlExisted = false;
       if (existsSync3(yamlPath)) {
         yamlExisted = true;
-        yamlData = $parse(readFileSync4(yamlPath, "utf8")) ?? {};
+        yamlData = import_yaml2.parse(readFileSync4(yamlPath, "utf8")) ?? {};
       }
       let yamlDirty = false;
       if (!yamlData.name) {
@@ -19756,7 +19762,7 @@ var init_default = defineCommand2({
         yamlDirty = true;
       }
       if (yamlDirty) {
-        writeFileSync3(yamlPath, $stringify(yamlData));
+        writeFileSync3(yamlPath, import_yaml2.stringify(yamlData));
         console.log(source_default.green(yamlExisted ? "✓ Updated bodify.yaml" : "✓ Created bodify.yaml"));
       } else {
         console.log(source_default.dim("bodify.yaml already up to date"));
@@ -19781,7 +19787,7 @@ var init_default = defineCommand2({
           changed = true;
         }
         if (changed)
-          writeFileSync3(yamlPath, $stringify(yamlData));
+          writeFileSync3(yamlPath, import_yaml2.stringify(yamlData));
       } catch (e2) {
         console.warn(source_default.yellow(`Warning: Could not register: ${e2.message}`));
       }
@@ -20070,8 +20076,364 @@ var publish_default = defineCommand2({
   }
 });
 
+// src/commands/db.ts
+import { existsSync as existsSync6, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
+import { join as join6 } from "path";
+function readServeInfo() {
+  const path = join6(process.cwd(), ".bodify", "serve.info.json");
+  if (!existsSync6(path))
+    return null;
+  try {
+    const info = JSON.parse(readFileSync6(path, "utf-8"));
+    try {
+      process.kill(info.pid, 0);
+    } catch {
+      return null;
+    }
+    return info;
+  } catch {
+    return null;
+  }
+}
+function readDotEnv(key) {
+  const path = join6(process.cwd(), ".env");
+  if (!existsSync6(path))
+    return null;
+  for (const line of readFileSync6(path, "utf-8").split(`
+`)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+      continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1)
+      continue;
+    if (trimmed.slice(0, eq).trim() !== key)
+      continue;
+    let val = trimmed.slice(eq + 1).trim();
+    if (val.startsWith('"') && val.endsWith('"') || val.startsWith("'") && val.endsWith("'"))
+      val = val.slice(1, -1);
+    return val;
+  }
+  return null;
+}
+function readDbPortFromYaml() {
+  const path = join6(process.cwd(), "bodify.yaml");
+  if (!existsSync6(path))
+    return 4460;
+  try {
+    const { parse: parse2 } = require_dist();
+    const y3 = parse2(readFileSync6(path, "utf-8"));
+    if (typeof y3?.database === "object" && y3.database?.port)
+      return Number(y3.database.port);
+    return 4460;
+  } catch {
+    return 4460;
+  }
+}
+function directTarget(port, token, label) {
+  const base = `http://127.0.0.1:${port}`;
+  return {
+    label: `${label} (${base})`,
+    async request(method, sub, body) {
+      const res = await fetch(`${base}${sub}`, {
+        method,
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        body: body !== undefined ? JSON.stringify(body) : undefined
+      });
+      const text = await res.text();
+      if (!res.ok)
+        throw new Error(`${method} ${sub} → ${res.status}: ${text}`);
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    }
+  };
+}
+async function resolveDbTarget(appArg) {
+  const explicitInstance = !!(process.env._BOD_INSTANCE_OVERRIDE || process.env.BOD_INSTANCE);
+  if (!explicitInstance) {
+    const info = readServeInfo();
+    if (info)
+      return directTarget(info.dbPort, info.dbAdminPassword, "local serve");
+    const envPw = readDotEnv("BODDB_ADMIN_PASSWORD");
+    if (envPw)
+      return directTarget(readDbPortFromYaml(), envPw, "direct via .env");
+  }
+  const { url, apiKey } = getResolvedInstance(loadConfig());
+  const client = new BodClient(url, apiKey);
+  const appId = await resolveAppId(client, resolveAppName(appArg));
+  return {
+    label: `agent ${url} → app ${appId}`,
+    request(method, sub, body) {
+      return client.request(method, `/apps/${appId}${sub}`, body);
+    }
+  };
+}
+async function readBody(positional, file) {
+  let raw;
+  if (positional)
+    raw = positional;
+  else if (file)
+    raw = readFileSync6(file, "utf-8");
+  else if (!process.stdin.isTTY)
+    raw = await new Response(Bun.stdin.stream()).text();
+  if (raw === undefined || raw.trim() === "") {
+    console.error(source_default.red("Body required. Pass JSON as positional arg, --file <path>, or pipe via stdin."));
+    process.exit(1);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e2) {
+    console.error(source_default.red(`Invalid JSON: ${e2.message}`));
+    process.exit(1);
+  }
+}
+function printResult(data, output) {
+  const text = JSON.stringify(data, null, 2);
+  if (output) {
+    writeFileSync4(output, text);
+    console.log(source_default.green(`✓ Wrote ${output}`));
+  } else {
+    console.log(text);
+  }
+}
+function normalizePath(p) {
+  return (p ?? "").replace(/^\/+|\/+$/g, "");
+}
+function strictArgs(known) {
+  const allowed = new Set([...known, "help", "h", "version", "v", "instance", "local", "l"]);
+  const unknown = [];
+  for (const a2 of process.argv.slice(2)) {
+    if (!a2.startsWith("--") && !a2.startsWith("-"))
+      continue;
+    if (a2 === "--" || a2 === "-")
+      continue;
+    const name = a2.replace(/^-+/, "").split("=")[0];
+    if (!name)
+      continue;
+    if (!allowed.has(name))
+      unknown.push(a2);
+  }
+  if (unknown.length) {
+    console.error(source_default.red(`Unknown argument(s): ${unknown.join(", ")}`));
+    console.error(source_default.dim(`Allowed: ${[...allowed].filter((x2) => x2.length > 1).sort().map((x2) => "--" + x2).join(", ")}`));
+    process.exit(1);
+  }
+}
+function parseFilterShorthand(raw) {
+  const ops = [[">=", ">="], ["<=", "<="], ["!=", "!="], ["==", "=="], ["=", "=="], [">", ">"], ["<", "<"]];
+  for (const [token, op] of ops) {
+    const idx = raw.indexOf(token);
+    if (idx <= 0)
+      continue;
+    const field = raw.slice(0, idx);
+    const rawValue = raw.slice(idx + token.length);
+    let value = rawValue;
+    try {
+      value = JSON.parse(rawValue);
+    } catch {}
+    return { field, op, value };
+  }
+  console.error(source_default.red(`Invalid --filter: "${raw}" (expected field=value, field!=value, field>value, etc.)`));
+  process.exit(1);
+}
+var getCmd = defineCommand2({
+  meta: { name: "get", description: "Get value at path. Shallow by default (top-level keys only). Use -d for full deep read. Mirrors BodClient.get()." },
+  args: {
+    path: { type: "positional", description: "DB path (e.g. users/123, or / for root)", required: false },
+    app: { type: "string", alias: "a", description: "App name (defaults to bodify.yaml)" },
+    deep: { type: "boolean", alias: "d", description: "Deep read (full subtree). Warning: large nodes may be huge.", default: false },
+    limit: { type: "string", alias: "n", description: "Shallow only: max keys to return" },
+    offset: { type: "string", description: "Shallow only: skip N keys" },
+    output: { type: "string", alias: "o", description: "Write to file instead of stdout" }
+  },
+  async run({ args }) {
+    strictArgs(["path", "app", "a", "deep", "d", "limit", "n", "offset", "output", "o"]);
+    const target = await resolveDbTarget(args.app);
+    const path = normalizePath(args.path);
+    const qs = [];
+    if (!args.deep) {
+      qs.push("shallow=1");
+      if (args.limit)
+        qs.push(`limit=${encodeURIComponent(args.limit)}`);
+      if (args.offset)
+        qs.push(`offset=${encodeURIComponent(args.offset)}`);
+    }
+    const sub = `/db${path ? "/" + path : "/"}${qs.length ? "?" + qs.join("&") : ""}`;
+    const res = await target.request("GET", sub);
+    printResult(res.data ?? null, args.output);
+    if (res.shallow && !args.output) {
+      console.error(source_default.dim(`(shallow — pass -d for deep read; target: ${target.label})`));
+    }
+  }
+});
+var setCmd2 = defineCommand2({
+  meta: { name: "set", description: "Replace (overwrite) value at path. Any existing subkeys not in the new value are deleted. Use `update` for merge semantics. Mirrors BodClient.set()." },
+  args: {
+    path: { type: "positional", description: "DB path", required: true },
+    value: { type: "positional", description: "JSON value (or use --file / stdin)", required: false },
+    app: { type: "string", alias: "a", description: "App name (defaults to bodify.yaml)" },
+    file: { type: "string", alias: "f", description: "Read JSON from file" }
+  },
+  async run({ args }) {
+    strictArgs(["path", "value", "app", "a", "file", "f"]);
+    const body = await readBody(args.value, args.file);
+    const target = await resolveDbTarget(args.app);
+    await target.request("PUT", `/db/${normalizePath(args.path)}`, body);
+    console.log(source_default.green(`✓ Set ${args.path}`));
+  }
+});
+var updateCmd = defineCommand2({
+  meta: { name: "update", description: "Merge value into path. Preserves keys not present in the new value (shallow merge). Use `set` for full replace. Mirrors BodClient.update()." },
+  args: {
+    path: { type: "positional", description: "DB path", required: true },
+    value: { type: "positional", description: "JSON value (or use --file / stdin)", required: false },
+    app: { type: "string", alias: "a", description: "App name (defaults to bodify.yaml)" },
+    file: { type: "string", alias: "f", description: "Read JSON from file" }
+  },
+  async run({ args }) {
+    strictArgs(["path", "value", "app", "a", "file", "f"]);
+    const body = await readBody(args.value, args.file);
+    const target = await resolveDbTarget(args.app);
+    await target.request("PATCH", `/db/${normalizePath(args.path)}`, body);
+    console.log(source_default.green(`✓ Updated ${args.path}`));
+  }
+});
+var pushCmd = defineCommand2({
+  meta: { name: "push", description: "Append value under path with an auto-generated key (list-style). Returns the new key." },
+  args: {
+    path: { type: "positional", description: "DB path (parent/list)", required: true },
+    value: { type: "positional", description: "JSON value (or use --file / stdin)", required: false },
+    app: { type: "string", alias: "a", description: "App name (defaults to bodify.yaml)" },
+    file: { type: "string", alias: "f", description: "Read JSON from file" }
+  },
+  async run({ args }) {
+    strictArgs(["path", "value", "app", "a", "file", "f"]);
+    const body = await readBody(args.value, args.file);
+    const target = await resolveDbTarget(args.app);
+    const res = await target.request("POST", `/db/${normalizePath(args.path)}`, body);
+    console.log(source_default.green(`✓ Pushed → ${args.path}/${res.key}`));
+  }
+});
+var deleteCmd = defineCommand2({
+  meta: { name: "delete", description: "Delete the node at path and all its descendants. Requires -y/--confirm to avoid accidents." },
+  args: {
+    path: { type: "positional", description: "DB path", required: true },
+    app: { type: "string", alias: "a", description: "App name (defaults to bodify.yaml)" },
+    confirm: { type: "boolean", alias: "y", description: "Confirm destructive delete", default: false }
+  },
+  async run({ args }) {
+    strictArgs(["path", "app", "a", "confirm", "y"]);
+    if (!args.confirm) {
+      console.error(source_default.yellow(`Refusing to delete "${args.path}" without --confirm (-y).`));
+      process.exit(1);
+    }
+    const target = await resolveDbTarget(args.app);
+    await target.request("DELETE", `/db/${normalizePath(args.path)}`);
+    console.log(source_default.green(`✓ Deleted ${args.path}`));
+  }
+});
+function parseFilters(where) {
+  if (!where)
+    return [];
+  const list = Array.isArray(where) ? where : [where];
+  const opMap = { eq: "==", ne: "!=", gt: ">", gte: ">=", lt: "<", lte: "<=", in: "in", contains: "contains" };
+  return list.map((w2) => {
+    const parts = w2.split(":");
+    if (parts.length < 3) {
+      console.error(source_default.red(`Invalid --where: ${w2} (expected field:op:value)`));
+      process.exit(1);
+    }
+    const [field, op, ...rest] = parts;
+    const rawValue = rest.join(":");
+    let value = rawValue;
+    try {
+      value = JSON.parse(rawValue);
+    } catch {}
+    return { field, op: opMap[op] ?? op, value };
+  });
+}
+var queryCmd = defineCommand2({
+  meta: {
+    name: "query",
+    description: "Query a collection with filters. Shallow by default (returns only _path/_key per match). Use -d for full docs."
+  },
+  args: {
+    path: { type: "positional", description: "DB path (collection)", required: true },
+    app: { type: "string", alias: "a", description: "App name (defaults to bodify.yaml)" },
+    filter: {
+      type: "string",
+      alias: "f",
+      description: "Filter shorthand: field=value, field!=value, field>N, field>=N, field<N, field<=N. Repeatable."
+    },
+    where: {
+      type: "string",
+      alias: "w",
+      description: "Canonical filter: field:op:value (op = eq|ne|gt|gte|lt|lte|in|contains). Repeatable. Use when value contains = or spaces."
+    },
+    order: { type: "string", description: "Order: field[:asc|:desc] (default asc)" },
+    limit: { type: "string", alias: "n", description: "Max results" },
+    offset: { type: "string", description: "Skip N results" },
+    deep: { type: "boolean", alias: "d", description: "Return full matched documents. Default: shallow (keys only).", default: false },
+    output: { type: "string", alias: "o", description: "Write to file instead of stdout" }
+  },
+  async run({ args }) {
+    strictArgs(["path", "app", "a", "filter", "f", "where", "w", "order", "limit", "n", "offset", "deep", "d", "output", "o"]);
+    const filters = [];
+    const filterList = args.filter ? Array.isArray(args.filter) ? args.filter : [args.filter] : [];
+    for (const f3 of filterList)
+      filters.push(parseFilterShorthand(f3));
+    filters.push(...parseFilters(args.where));
+    let order;
+    if (args.order) {
+      const [field, dir] = args.order.split(":");
+      order = { field, dir: dir === "desc" ? "desc" : "asc" };
+    }
+    const body = {
+      filters: filters.length ? filters : undefined,
+      order,
+      limit: args.limit ? Number(args.limit) : undefined,
+      offset: args.offset ? Number(args.offset) : undefined
+    };
+    const target = await resolveDbTarget(args.app);
+    const res = await target.request("POST", `/query/${normalizePath(args.path)}`, body);
+    let rows = res.data;
+    if (!args.deep && Array.isArray(rows)) {
+      rows = rows.map((r3) => ({ _path: r3._path, _key: r3._key }));
+    }
+    printResult(rows ?? null, args.output);
+    if (!args.deep && !args.output && Array.isArray(rows)) {
+      console.error(source_default.dim(`(${rows.length} match${rows.length === 1 ? "" : "es"}; shallow — pass -d for full docs)`));
+    }
+  }
+});
+var db_default = defineCommand2({
+  meta: { name: "db", description: "Read/write per-app BodDB (get|set|update|push|delete|query). Names mirror BodClient SDK." },
+  subCommands: {
+    get: getCmd,
+    set: setCmd2,
+    update: updateCmd,
+    push: pushCmd,
+    delete: deleteCmd,
+    query: queryCmd
+  }
+});
+
 // src/cli.ts
-var instanceFlag = process.argv.find((a2) => a2.startsWith("--instance="))?.split("=").slice(1).join("=");
+function parseInstanceFlag() {
+  const argv2 = process.argv;
+  for (let i2 = 0;i2 < argv2.length; i2++) {
+    const a2 = argv2[i2];
+    if (a2.startsWith("--instance="))
+      return a2.slice("--instance=".length);
+    if (a2 === "--instance" && i2 + 1 < argv2.length)
+      return argv2[i2 + 1];
+  }
+  return;
+}
+var instanceFlag = parseInstanceFlag();
 var isLocal = process.argv.includes("--local") || process.argv.includes("-l");
 if (instanceFlag)
   setInstanceOverride(instanceFlag);
@@ -20090,7 +20452,8 @@ var subCommands = {
   open: open_default,
   serve: serve_default,
   ssh: ssh_default,
-  publish: publish_default
+  publish: publish_default,
+  db: db_default
 };
 var main = defineCommand({
   meta: {
@@ -20122,6 +20485,7 @@ var main = defineCommand({
       { value: "logs", name: "logs      \u2014 View app logs" },
       { value: "open", name: "open      \u2014 Open app in browser" },
       { value: "env", name: "env       \u2014 Manage env vars" },
+      { value: "db", name: "db        \u2014 Read/write app database" },
       { value: "serve", name: "serve     \u2014 Run app locally" },
       { value: "ssh", name: "ssh       \u2014 SSH into Bodify server" },
       { value: "init", name: "init      \u2014 Initialize a project" },
@@ -20200,6 +20564,8 @@ async function getInteractiveArgs(command) {
       }
       case "publish":
         return [];
+      case "db":
+        return [];
       default:
         return [];
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bod-cli",
-  "version": "0.5.9",
+  "version": "0.7.4",
   "type": "module",
   "bin": {
     "bod": "./dist/cli.js"

package/src/cli.ts

@@ -15,9 +15,20 @@ import openCmd from './commands/open'
 import serveCmd from './commands/serve'
 import sshCmd from './commands/ssh'
 import publishCmd from './commands/publish'
+import dbCmd from './commands/db'
 
-// Parse --instance / --local / -l early so it's set before citty dispatches subcommands
-const instanceFlag = process.argv.find(a => a.startsWith('--instance='))?.split('=').slice(1).join('=')
+// Parse --instance / --local / -l early so it's set before citty dispatches subcommands.
+// Supports both `--instance=NAME` and `--instance NAME` forms.
+function parseInstanceFlag(): string | undefined {
+  const argv = process.argv
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--instance=')) return a.slice('--instance='.length)
+    if (a === '--instance' && i + 1 < argv.length) return argv[i + 1]
+  }
+  return undefined
+}
+const instanceFlag = parseInstanceFlag()
 const isLocal = process.argv.includes('--local') || process.argv.includes('-l')
 if (instanceFlag) setInstanceOverride(instanceFlag)
 else if (isLocal) setInstanceOverride('local')
@@ -36,6 +47,7 @@ const subCommands = {
   serve: serveCmd,
   ssh: sshCmd,
   publish: publishCmd,
+  db: dbCmd,
 }
 
 const main = defineCommand({
@@ -71,6 +83,7 @@ const main = defineCommand({
       { value: 'logs',     name: 'logs      — View app logs' },
       { value: 'open',     name: 'open      — Open app in browser' },
       { value: 'env',      name: 'env       — Manage env vars' },
+      { value: 'db',       name: 'db        — Read/write app database' },
       { value: 'serve',    name: 'serve     — Run app locally' },
       { value: 'ssh',      name: 'ssh       — SSH into Bodify server' },
       { value: 'init',     name: 'init      — Initialize a project' },
@@ -141,6 +154,7 @@ async function getInteractiveArgs(command: string): Promise<string[] | null> {
         return [pkg]
       }
       case 'publish': return []
+      case 'db': return []
       default: return []
     }
   } catch (e) {

package/src/client.ts

@@ -39,4 +39,5 @@ export class BodClient {
   post<T = unknown>(path: string, body?: unknown) { return this.request<T>('POST', path, body) }
   put<T = unknown>(path: string, body?: unknown) { return this.request<T>('PUT', path, body) }
   del<T = unknown>(path: string) { return this.request<T>('DELETE', path) }
+  patch<T = unknown>(path: string, body?: unknown) { return this.request<T>('PATCH', path, body) }
 }

package/src/commands/db.ts

@@ -0,0 +1,376 @@
+import { defineCommand } from 'citty'
+import chalk from 'chalk'
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { loadConfig, getResolvedInstance } from '../config'
+import { BodClient } from '../client'
+import { resolveAppId, resolveAppName } from '../utils/resolve'
+
+interface DbResponse { ok: boolean; data?: unknown; key?: string; error?: string }
+
+interface ServeInfo { dbPort: number; dbAdminPort: number; dbAdminPassword: string; dbPath: string; pid: number; startedAt: number }
+
+/** Read `.bodify/serve.info.json` if present (created by `bod serve`). */
+function readServeInfo(): ServeInfo | null {
+  const path = join(process.cwd(), '.bodify', 'serve.info.json')
+  if (!existsSync(path)) return null
+  try {
+    const info = JSON.parse(readFileSync(path, 'utf-8')) as ServeInfo
+    // Sanity: is the pid still alive? If not, file is stale.
+    try { process.kill(info.pid, 0) } catch { return null }
+    return info
+  } catch { return null }
+}
+
+/** Parse cwd's .env for a single key. No-op if missing. */
+function readDotEnv(key: string): string | null {
+  const path = join(process.cwd(), '.env')
+  if (!existsSync(path)) return null
+  for (const line of readFileSync(path, 'utf-8').split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eq = trimmed.indexOf('=')
+    if (eq === -1) continue
+    if (trimmed.slice(0, eq).trim() !== key) continue
+    let val = trimmed.slice(eq + 1).trim()
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) val = val.slice(1, -1)
+    return val
+  }
+  return null
+}
+
+/** Read database port from bodify.yaml (`database.port`), else default 4460. */
+function readDbPortFromYaml(): number {
+  const path = join(process.cwd(), 'bodify.yaml')
+  if (!existsSync(path)) return 4460
+  try {
+    const { parse } = require('yaml')
+    const y = parse(readFileSync(path, 'utf-8')) as { database?: boolean | { port?: number } }
+    if (typeof y?.database === 'object' && y.database?.port) return Number(y.database.port)
+    return 4460
+  } catch { return 4460 }
+}
+
+/**
+ * A BodDB target — either via the Bodify agent proxy (deployed apps) or
+ * directly to a locally-running `bod serve` BodDB.
+ */
+interface DbTarget {
+  /** HTTP verb + url path suffix (after the /db or /query base) + optional body → response */
+  request<T = unknown>(method: string, sub: string, body?: unknown): Promise<T>
+  /** Display label for errors/hints */
+  label: string
+}
+
+function directTarget(port: number, token: string, label: string): DbTarget {
+  const base = `http://127.0.0.1:${port}`
+  return {
+    label: `${label} (${base})`,
+    async request<T>(method: string, sub: string, body?: unknown): Promise<T> {
+      const res = await fetch(`${base}${sub}`, {
+        method,
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      })
+      const text = await res.text()
+      if (!res.ok) throw new Error(`${method} ${sub} → ${res.status}: ${text}`)
+      try { return JSON.parse(text) as T } catch { return text as T }
+    },
+  }
+}
+
+/**
+ * Resolve a target for DB commands.
+ *
+ * Precedence:
+ *   1. Explicit `--instance <name>` / `BOD_INSTANCE` → always the Bodify agent
+ *      proxy for that instance. Local shortcuts are skipped so the flag isn't
+ *      silently ignored while `bod serve` runs in the same dir.
+ *   2. Otherwise, prefer direct-to-BodDB if we can discover the port + admin
+ *      password locally (`.bodify/serve.info.json` from `bod serve`, or
+ *      `.env BODDB_ADMIN_PASSWORD` + `bodify.yaml database.port`).
+ *   3. Fall back to the Bodify agent proxy for the default instance.
+ */
+async function resolveDbTarget(appArg: string | undefined): Promise<DbTarget> {
+  const explicitInstance = !!(process.env._BOD_INSTANCE_OVERRIDE || process.env.BOD_INSTANCE)
+
+  if (!explicitInstance) {
+    // 1. Live `bod serve` info file — authoritative (correct port even if scanned).
+    const info = readServeInfo()
+    if (info) return directTarget(info.dbPort, info.dbAdminPassword, 'local serve')
+    // 2. .env BODDB_ADMIN_PASSWORD + bodify.yaml database.port — works without restarting serve.
+    const envPw = readDotEnv('BODDB_ADMIN_PASSWORD')
+    if (envPw) return directTarget(readDbPortFromYaml(), envPw, 'direct via .env')
+  }
+
+  // 3. Bodify agent proxy (deployed apps — or explicitly-requested instance).
+  const { url, apiKey } = getResolvedInstance(loadConfig())
+  const client = new BodClient(url, apiKey)
+  const appId = await resolveAppId(client, resolveAppName(appArg))
+  return {
+    label: `agent ${url} → app ${appId}`,
+    request<T>(method: string, sub: string, body?: unknown): Promise<T> {
+      return client.request<T>(method, `/apps/${appId}${sub}`, body)
+    },
+  }
+}
+
+/** Read body from positional arg, --file, or stdin (in that order). */
+async function readBody(positional: string | undefined, file: string | undefined): Promise<unknown> {
+  let raw: string | undefined
+  if (positional) raw = positional
+  else if (file) raw = readFileSync(file, 'utf-8')
+  else if (!process.stdin.isTTY) raw = await new Response(Bun.stdin.stream()).text()
+  if (raw === undefined || raw.trim() === '') {
+    console.error(chalk.red('Body required. Pass JSON as positional arg, --file <path>, or pipe via stdin.'))
+    process.exit(1)
+  }
+  try { return JSON.parse(raw) }
+  catch (e) {
+    console.error(chalk.red(`Invalid JSON: ${(e as Error).message}`))
+    process.exit(1)
+  }
+}
+
+function printResult(data: unknown, output: string | undefined) {
+  const text = JSON.stringify(data, null, 2)
+  if (output) {
+    writeFileSync(output, text)
+    console.log(chalk.green(`✓ Wrote ${output}`))
+  } else {
+    console.log(text)
+  }
+}
+
+/** Strip leading/trailing slashes; '/' or '' → '' (root). */
+function normalizePath(p: string | undefined): string {
+  return (p ?? '').replace(/^\/+|\/+$/g, '')
+}
+
+/**
+ * Reject any raw argv flag that isn't declared in `known`. citty accepts
+ * unknown flags silently, so this guards against typos (e.g. --wheree).
+ */
+function strictArgs(known: string[]): void {
+  const allowed = new Set([...known, 'help', 'h', 'version', 'v', 'instance', 'local', 'l'])
+  const unknown: string[] = []
+  for (const a of process.argv.slice(2)) {
+    if (!a.startsWith('--') && !a.startsWith('-')) continue
+    if (a === '--' || a === '-') continue
+    const name = a.replace(/^-+/, '').split('=')[0]
+    if (!name) continue
+    if (!allowed.has(name)) unknown.push(a)
+  }
+  if (unknown.length) {
+    console.error(chalk.red(`Unknown argument(s): ${unknown.join(', ')}`))
+    console.error(chalk.dim(`Allowed: ${[...allowed].filter(x => x.length > 1).sort().map(x => '--' + x).join(', ')}`))
+    process.exit(1)
+  }
+}
+
+/**
+ * Parse a single --filter shorthand: `field=value`, `field!=value`, `field>value`,
+ * `field>=value`, `field<value`, `field<=value`. Value is parsed as JSON if possible.
+ * Returns a QueryFilter in the canonical bod-db shape.
+ */
+function parseFilterShorthand(raw: string): { field: string; op: string; value: unknown } {
+  // Order matters: longest ops first so >= beats > etc.
+  const ops: Array<[string, string]> = [['>=', '>='], ['<=', '<='], ['!=', '!='], ['==', '=='], ['=', '=='], ['>', '>'], ['<', '<']]
+  for (const [token, op] of ops) {
+    const idx = raw.indexOf(token)
+    if (idx <= 0) continue
+    const field = raw.slice(0, idx)
+    const rawValue = raw.slice(idx + token.length)
+    let value: unknown = rawValue
+    try { value = JSON.parse(rawValue) } catch { /* keep as string */ }
+    return { field, op, value }
+  }
+  console.error(chalk.red(`Invalid --filter: "${raw}" (expected field=value, field!=value, field>value, etc.)`))
+  process.exit(1)
+}
+
+const getCmd = defineCommand({
+  meta: { name: 'get', description: 'Get value at path. Shallow by default (top-level keys only). Use -d for full deep read. Mirrors BodClient.get().' },
+  args: {
+    path: { type: 'positional', description: 'DB path (e.g. users/123, or / for root)', required: false },
+    app: { type: 'string', alias: 'a', description: 'App name (defaults to bodify.yaml)' },
+    deep: { type: 'boolean', alias: 'd', description: 'Deep read (full subtree). Warning: large nodes may be huge.', default: false },
+    limit: { type: 'string', alias: 'n', description: 'Shallow only: max keys to return' },
+    offset: { type: 'string', description: 'Shallow only: skip N keys' },
+    output: { type: 'string', alias: 'o', description: 'Write to file instead of stdout' },
+  },
+  async run({ args }) {
+    strictArgs(['path', 'app', 'a', 'deep', 'd', 'limit', 'n', 'offset', 'output', 'o'])
+    const target = await resolveDbTarget(args.app)
+    const path = normalizePath(args.path)
+    const qs: string[] = []
+    if (!args.deep) {
+      qs.push('shallow=1')
+      if (args.limit) qs.push(`limit=${encodeURIComponent(args.limit)}`)
+      if (args.offset) qs.push(`offset=${encodeURIComponent(args.offset)}`)
+    }
+    const sub = `/db${path ? '/' + path : '/'}${qs.length ? '?' + qs.join('&') : ''}`
+    const res = await target.request<DbResponse & { shallow?: boolean }>('GET', sub)
+    printResult(res.data ?? null, args.output)
+    if (res.shallow && !args.output) {
+      console.error(chalk.dim(`(shallow — pass -d for deep read; target: ${target.label})`))
+    }
+  },
+})
+
+const setCmd = defineCommand({
+  meta: { name: 'set', description: 'Replace (overwrite) value at path. Any existing subkeys not in the new value are deleted. Use `update` for merge semantics. Mirrors BodClient.set().' },
+  args: {
+    path: { type: 'positional', description: 'DB path', required: true },
+    value: { type: 'positional', description: 'JSON value (or use --file / stdin)', required: false },
+    app: { type: 'string', alias: 'a', description: 'App name (defaults to bodify.yaml)' },
+    file: { type: 'string', alias: 'f', description: 'Read JSON from file' },
+  },
+  async run({ args }) {
+    strictArgs(['path', 'value', 'app', 'a', 'file', 'f'])
+    const body = await readBody(args.value, args.file)
+    const target = await resolveDbTarget(args.app)
+    await target.request('PUT', `/db/${normalizePath(args.path)}`, body)
+    console.log(chalk.green(`✓ Set ${args.path}`))
+  },
+})
+
+const updateCmd = defineCommand({
+  meta: { name: 'update', description: 'Merge value into path. Preserves keys not present in the new value (shallow merge). Use `set` for full replace. Mirrors BodClient.update().' },
+  args: {
+    path: { type: 'positional', description: 'DB path', required: true },
+    value: { type: 'positional', description: 'JSON value (or use --file / stdin)', required: false },
+    app: { type: 'string', alias: 'a', description: 'App name (defaults to bodify.yaml)' },
+    file: { type: 'string', alias: 'f', description: 'Read JSON from file' },
+  },
+  async run({ args }) {
+    strictArgs(['path', 'value', 'app', 'a', 'file', 'f'])
+    const body = await readBody(args.value, args.file)
+    const target = await resolveDbTarget(args.app)
+    await target.request('PATCH', `/db/${normalizePath(args.path)}`, body)
+    console.log(chalk.green(`✓ Updated ${args.path}`))
+  },
+})
+
+const pushCmd = defineCommand({
+  meta: { name: 'push', description: 'Append value under path with an auto-generated key (list-style). Returns the new key.' },
+  args: {
+    path: { type: 'positional', description: 'DB path (parent/list)', required: true },
+    value: { type: 'positional', description: 'JSON value (or use --file / stdin)', required: false },
+    app: { type: 'string', alias: 'a', description: 'App name (defaults to bodify.yaml)' },
+    file: { type: 'string', alias: 'f', description: 'Read JSON from file' },
+  },
+  async run({ args }) {
+    strictArgs(['path', 'value', 'app', 'a', 'file', 'f'])
+    const body = await readBody(args.value, args.file)
+    const target = await resolveDbTarget(args.app)
+    const res = await target.request<DbResponse>('POST', `/db/${normalizePath(args.path)}`, body)
+    console.log(chalk.green(`✓ Pushed → ${args.path}/${res.key}`))
+  },
+})
+
+const deleteCmd = defineCommand({
+  meta: { name: 'delete', description: 'Delete the node at path and all its descendants. Requires -y/--confirm to avoid accidents.' },
+  args: {
+    path: { type: 'positional', description: 'DB path', required: true },
+    app: { type: 'string', alias: 'a', description: 'App name (defaults to bodify.yaml)' },
+    confirm: { type: 'boolean', alias: 'y', description: 'Confirm destructive delete', default: false },
+  },
+  async run({ args }) {
+    strictArgs(['path', 'app', 'a', 'confirm', 'y'])
+    if (!args.confirm) {
+      console.error(chalk.yellow(`Refusing to delete "${args.path}" without --confirm (-y).`))
+      process.exit(1)
+    }
+    const target = await resolveDbTarget(args.app)
+    await target.request('DELETE', `/db/${normalizePath(args.path)}`)
+    console.log(chalk.green(`✓ Deleted ${args.path}`))
+  },
+})
+
+/** Parse --where field:op:value (op = eq|ne|gt|gte|lt|lte|in|contains). Repeatable. */
+function parseFilters(where: string | string[] | undefined): Array<{ field: string; op: string; value: unknown }> {
+  if (!where) return []
+  const list = Array.isArray(where) ? where : [where]
+  const opMap: Record<string, string> = { eq: '==', ne: '!=', gt: '>', gte: '>=', lt: '<', lte: '<=', in: 'in', contains: 'contains' }
+  return list.map(w => {
+    const parts = w.split(':')
+    if (parts.length < 3) {
+      console.error(chalk.red(`Invalid --where: ${w} (expected field:op:value)`))
+      process.exit(1)
+    }
+    const [field, op, ...rest] = parts
+    const rawValue = rest.join(':')
+    let value: unknown = rawValue
+    try { value = JSON.parse(rawValue) } catch { /* keep as string */ }
+    return { field, op: opMap[op] ?? op, value }
+  })
+}
+
+const queryCmd = defineCommand({
+  meta: {
+    name: 'query',
+    description: 'Query a collection with filters. Shallow by default (returns only _path/_key per match). Use -d for full docs.',
+  },
+  args: {
+    path: { type: 'positional', description: 'DB path (collection)', required: true },
+    app: { type: 'string', alias: 'a', description: 'App name (defaults to bodify.yaml)' },
+    filter: {
+      type: 'string',
+      alias: 'f',
+      description: 'Filter shorthand: field=value, field!=value, field>N, field>=N, field<N, field<=N. Repeatable.',
+    },
+    where: {
+      type: 'string',
+      alias: 'w',
+      description: 'Canonical filter: field:op:value (op = eq|ne|gt|gte|lt|lte|in|contains). Repeatable. Use when value contains = or spaces.',
+    },
+    order: { type: 'string', description: 'Order: field[:asc|:desc] (default asc)' },
+    limit: { type: 'string', alias: 'n', description: 'Max results' },
+    offset: { type: 'string', description: 'Skip N results' },
+    deep: { type: 'boolean', alias: 'd', description: 'Return full matched documents. Default: shallow (keys only).', default: false },
+    output: { type: 'string', alias: 'o', description: 'Write to file instead of stdout' },
+  },
+  async run({ args }) {
+    strictArgs(['path', 'app', 'a', 'filter', 'f', 'where', 'w', 'order', 'limit', 'n', 'offset', 'deep', 'd', 'output', 'o'])
+    // Merge --filter (shorthand) and --where (canonical). Both are repeatable.
+    const filters: Array<{ field: string; op: string; value: unknown }> = []
+    const filterList = args.filter ? (Array.isArray(args.filter) ? args.filter : [args.filter]) : []
+    for (const f of filterList) filters.push(parseFilterShorthand(f))
+    filters.push(...parseFilters(args.where as any))
+
+    let order: { field: string; dir?: 'asc' | 'desc' } | undefined
+    if (args.order) {
+      const [field, dir] = args.order.split(':')
+      order = { field, dir: (dir === 'desc' ? 'desc' : 'asc') }
+    }
+    const body = {
+      filters: filters.length ? filters : undefined,
+      order,
+      limit: args.limit ? Number(args.limit) : undefined,
+      offset: args.offset ? Number(args.offset) : undefined,
+    }
+    const target = await resolveDbTarget(args.app)
+    const res = await target.request<DbResponse>('POST', `/query/${normalizePath(args.path)}`, body)
+    let rows = res.data as Array<Record<string, unknown>> | null
+    if (!args.deep && Array.isArray(rows)) {
+      rows = rows.map(r => ({ _path: r._path, _key: r._key }))
+    }
+    printResult(rows ?? null, args.output)
+    if (!args.deep && !args.output && Array.isArray(rows)) {
+      console.error(chalk.dim(`(${rows.length} match${rows.length === 1 ? '' : 'es'}; shallow — pass -d for full docs)`))
+    }
+  },
+})
+
+export default defineCommand({
+  meta: { name: 'db', description: 'Read/write per-app BodDB (get|set|update|push|delete|query). Names mirror BodClient SDK.' },
+  subCommands: {
+    get: getCmd,
+    set: setCmd,
+    update: updateCmd,
+    push: pushCmd,
+    delete: deleteCmd,
+    query: queryCmd,
+  },
+})