CLI 参考

md-db-engine --help 列出稳定命令；--json 适合脚本和 Agent，失败时返回结构化错误对象和非零退出码。

连接方式

场景	参数
Server 没有运行，当前进程临时拥有 Writer	`--database <runtime-path>`
Server 正在运行	`--endpoint <url> --credentials <credential>`

同一 Runtime Database 不能同时由 Server 和 Embedded CLI 打开。看到 WRITER_LOCKED 时，不要删除 Lock；改用 Server endpoint，或者正常停止原 Writer Host。

常用命令

md-db-engine serve <database> [--open]
md-db-engine init scan <vault> [--output <external-directory>]
md-db-engine init preview <vault> --config <file> [--plan <external-file>]
md-db-engine init apply <vault> --plan <file> --database <path> --yes
md-db-engine workspace export|status|update --database <path> --workspace <path>
md-db-engine merge plan|apply --database <path> --workspace <path>
md-db-engine query --database <path> --collection <name> [--where <json>]
md-db-engine check --database <path>
md-db-engine backup --database <path>
md-db-engine restore --database <path> --snapshot <id> --target <new-path> --yes
md-db-engine upgrade --database <path> --yes
md-db-engine index rebuild --database <path> --yes
md-db-engine user create|disable|list|rotate

Workspace、Merge、Query、Backup 和用户管理可以把 Embedded 参数替换为 Remote 参数。init scan|preview|apply 操作本地知识库与新 Runtime 路径，因此迁移期间使用本地路径。

Query 示例

md-db-engine query \
  --endpoint http://127.0.0.1:3000 \
  --credentials 'owner:replace-with-your-secret' \
  --collection documents \
  --where '{"field":"status","operator":"eq","value":"published"}' \
  --limit 20 \
  --json

确认参数

init apply、merge apply、restore、upgrade、index rebuild 和危险 Credential 操作需要 --yes。自动化应该先读取 Preview 或 Plan，再明确传入确认参数；不能通过模拟终端输入绕过审阅。

错误处理

常见错误包括 WRITER_LOCKED、PLAN_STALE、MERGE_CONFLICT、WORKSPACE_BASE_INVALID、AUTHENTICATION_FAILED 和 DATABASE_CORRUPTED。修复建议位于 JSON 的 suggestion 字段。PLAN_STALE 表示 Plan 生成后 Runtime 或 Workspace 已经变化，应该重新生成 Plan。