Dinox CLI 用户手册

dino 是 Dinox 的命令行工具，用来在本地管理和同步你的 Dinox 数据，包括：笔记、待办、标签、卡片盒、Prompt、知识图谱，以及适合脚本和 AI 助手调用的结构化命令输出。

这份 README 按“先上手、再进阶、最后查表”的顺序重写，尽量做到：

• 先让你快速跑通第一次使用
• 再教你完成最常见的日常操作
• 最后给出完整命令速查，方便回头查阅

如果你只想尽快开始，先看“5 分钟快速上手”。

目录

• 1. 你可以用 Dinox CLI 做什么
• 2. 安装要求与安装方法
• 3. 5 分钟快速上手
• 4. 使用前必须知道的 6 个规则
• 5. 日常操作教程
• 6. 完整命令速查
• 7. AI / 脚本自动化
• 8. 常见问题
• 9. 配置文件、数据库与环境变量
• 10. 如何查看帮助

1. 你可以用 Dinox CLI 做什么

Dinox CLI 适合这几类场景：

1. 在终端里登录 Dinox 账号，并把云端数据同步到本地
2. 快速搜索、查看、创建、更新、删除笔记
3. 从笔记里的任务列表中搜索待办，或追加/创建待办
4. 维护标签、卡片盒、Prompt 等结构化信息
5. 查询笔记之间的链接关系和知识图谱
6. 用 --format json 输出结构化结果，方便脚本和 AI 调用

你可以把它理解为：

• 普通用户：一个更高效的 Dinox 数据管理工具
• 进阶用户：一个可脚本化的本地知识库命令行入口
• AI 用户：一个可通过结构化命令和 schema 稳定调用的本地知识库入口

2. 安装要求与安装方法

2.1 系统要求

安装前请先确认：

• 推荐使用 Node.js 24 LTS；支持 Node.js 22、23、24、25（不支持 Node.js 21 及以下或 26+）
• 已安装 npm
• 你的系统可以正常执行全局 npm 命令

检查方法：

node -v
npm -v

2.2 安装 Dinox CLI

先确认 node -v 是 v22、v23、v24 或 v25，再全局安装。npm 11.16 及以后默认不编译 better-sqlite3 和 sharp，安装命令要放行这两个包：

npm install -g @dinoxx/dinox-cli@latest --allow-scripts=better-sqlite3,sharp

npm -v 低于 11.16 时没有 --allow-scripts，去掉这个参数再装。用 pnpm 10.15 及以后时：

pnpm add -g @dinoxx/dinox-cli@latest --allow-build=better-sqlite3 --allow-build=sharp

安装完成后，验证是否成功：

dino info

看到版本号就表示安装成功。

说明：安装后通常可以使用 dino 或 dinox 两个命令名，本文统一使用 dino。dino 用的是安装时 PATH 里的那个 node。

2.3 macOS 安装 Node.js（如果你还没装）

Homebrew 的 node 公式现在是 Node.js 26，CLI 不能用它。安装 Node.js 24：

brew install node@24
export PATH="$(brew --prefix node@24)/bin:$PATH"
node -v

node -v 应显示 v24。再执行上面的安装命令。

2.4 Windows 安装 Node.js（如果你还没装）

PowerShell 中可使用：

winget install OpenJS.NodeJS.LTS

2.5 更新 CLI

后续如果要更新到最新版本，直接执行：

dino update

它会安装 @latest，所以可以从 1.x 升到 2.x。npm 11.16+ 会自动加上 --allow-scripts=better-sqlite3,sharp，pnpm 10.15+ 会自动加上 --allow-build。旧版 dino update 只在 1.x 里更新，版本停在 1.x 时改用上面的安装命令。

它会自动根据你当前的安装方式选择合适的包管理器执行更新。升级完成后会检查本机已安装的 Agent：有 claude 但没有 ACP 命令时安装 @agentclientprotocol/claude-agent-acp，有 codex 时安装 @agentclientprotocol/codex-acp，有 zcode 时安装 zcode-acp，有 pi 时安装 pi-acp，有 agy 时安装 agy-acp，有 muse 时安装 @bex-co/muse-code-acp。已经装过的适配器会跳过；某个适配器安装失败只给出警告，不影响 CLI 升级本身。

3. 5 分钟快速上手

下面是第一次使用最推荐的顺序。你可以直接照着执行。

第 1 步：登录

在自己的终端运行：

dino auth login

终端会显示二维码。用 Dinox App 打开 设置 → 设备配对 → 扫一扫，扫码确认即可。登录时会完成首次同步，之后的读取命令会自动启动本地 daemon，一般不用再手动执行 dino sync 或 dino auth status。

如果 App 提示二维码无效，先升级 Dinox App。这条命令最长等待 10 分钟。

CI / 自动化

没有人可以扫码时，继续用 token。token 可在 App 的 设置 → 同步设置 → API Token 获取。

read -rs DINOX_TOKEN
printf '%s' "$DINOX_TOKEN" | dino auth login --token-stdin
unset DINOX_TOKEN

说明：

• --token-stdin 接受 token 本体或 Bearer ...
• 也可以只在当前进程注入 DINOX_TOKEN（优先于本地配置，支持 token 本体或 Bearer ...），不写入配置文件

第 2 步：搜索一条笔记试试

dino note search "AI"

第 3 步：新建一条笔记试试

dino note create \
  --title "今天的记录" \
  --content "# 标题\n\n这里是正文" \
  --type note

如果你能顺利完成上面 3 步，说明 CLI 已经可以正常使用。

4. 使用前必须知道的 6 个规则

很多问题都来自对 CLI 约定不熟。先掌握下面 6 条，会少踩很多坑。

规则 1：很多命令默认会优先使用本地数据库

dino sync 会把云端数据同步到本地。后续大多数查询命令会基于本地缓存工作。

如果你希望明确只使用本地缓存、不触发联网/同步，可以加：

--offline

例如：

dino note search "项目复盘" --offline

适用场景：

• 网络不稳定
• 只想查本地缓存
• 你已经先手动执行过 dino sync

规则 2：给脚本或 AI 用时，推荐统一加 --format json

例如：

dino note search "AI" --format json

说明：

• --format json：推荐的结构化输出
• --format yaml：也支持
• --json：历史兼容参数，等价于 --format yaml

规则 3：很多写操作都支持 --dry-run

如果你想先看“将会发生什么”，但暂时不真正写入数据，可以用：

--dry-run

例如：

dino note delete <note-id> --dry-run

这对删除、更新、批量修改尤其有用。

规则 4：很多参数支持直接从文件读取

凡是写成 <string|@file> 或 <string|@file> 的参数，通常都支持 @文件路径 的写法。

例如从文件读取笔记正文：

dino note create --title "读书笔记" --content @./note.md --type note

例如从文件读取待办列表：

dino todo create --tasks @./todo.txt

规则 5：列表参数通常有 3 种写法

像 --tags、--boxes、--tasks、--ids 这类列表参数，通常支持：

1. JSON 数组
2. 逗号分隔
3. 换行分隔

例如这三种都可以：

--tags '["工作","项目A"]'
--tags "工作,项目A"
--tags @./tags.txt

规则 6：标签和卡片盒必须先存在，笔记才能引用它们

例如你先创建笔记时用了一个不存在的标签：

dino note create --title "测试" --content "正文" --tags "工作/项目A"

如果这个标签还不存在，就会报错。正确顺序通常是：

dino tag add "工作/项目A"
dino box add "Inbox"
dino note create --title "测试" --content "正文" --tags "工作/项目A" --boxes "Inbox" --type note

5. 日常操作教程

这一部分按真实使用场景来写。你不需要一开始记住所有命令，先会做日常任务就够了。

5.1 搜索笔记

按关键词搜索

dino note search "AI"

搜索最近 7 天的笔记

dino note search "AI" --days 7

按时间范围搜索

dino note search "AI" --from 2026-03-01 --to 2026-03-31

按标签表达式搜索

dino note search --tags "(work OR life) AND NOT archived"

按卡片盒搜索

dino note search --boxes "Inbox,Project"

只看已收藏或未收藏笔记

dino note search --starred true
dino note search --starred false

分页与字段裁剪

dino note search "AI" --limit 20 --offset 0
dino note search "AI" --fields id,title,summary,created_at

高级 SQL 风格筛选

dino note search --sql 'type = "crawl" AND zettel_boxes IN ("Inbox","Project")'

适合场景：

• 你已经很清楚要筛什么字段
• 希望做更复杂的组合条件查询

提醒：--sql 只支持只读查询条件，不是让你执行任意 SQL。

5.2 查看笔记内容

只看笔记基础信息

dino note get <note-id>

只拿轻量上下文（适合 AI / 脚本）

dino note get <note-id> --format json

note get 在 2.0 中始终是轻量读取；--context-only 仅保留为兼容参数，不会改变输出。

预览正文前几行

dino note preview <note-id>
dino note preview <note-id> --lines 30

查看完整详情

dino note detail <note-id>

批量查看多条笔记详情

dino note detail --ids @./note-ids.txt

5.3 创建笔记

创建最简单的一条笔记

dino note create \
  --title "会议记录" \
  --content "今天讨论了发布计划" \
  --type note

从 Markdown 文件创建

dino note create \
  --title "周报" \
  --content @./weekly.md \
  --type note

同时设置标签和卡片盒

dino note create \
  --title "项目复盘" \
  --content @./review.md \
  --type note \
  --tags "工作/项目A,复盘" \
  --boxes "Project"

注意：

• --title 和 --content 是必填项
• --type 可选值只有 note 和 crawl
• 如果你不写 --type，默认是 crawl
• 如果你想写普通笔记，建议明确加 --type note

创建前先预演

dino note create \
  --title "测试笔记" \
  --content "正文" \
  --type note \
  --dry-run

5.4 整理笔记元数据与正文

note update：显式 ID 的全量替换

dino note update <note-id> --tags "工作,AI" --dry-run
dino note update <note-id> --boxes "Inbox" --starred true --dry-run

note update 面向明确的笔记 ID，--tags 和 --boxes 都是完整替换，不是追加。清空标签或卡片盒时传 []：

dino note update <note-id> --tags '[]'
dino note update <note-id> --boxes '[]'

note tag / note move：显式 ID 的增量整理

dino note tag <note-id> --add "工作,AI" --dry-run
dino note tag --ids @./note-ids.txt --remove "Inbox" --dry-run
dino note move <note-id> --add "Project/Inbox" --dry-run
dino note move --ids @./note-ids.txt --replace "Project" --dry-run

note tag 管标签，note move 管卡片盒归属；它们的 --add / --remove 会保留现有值，--replace 才会覆盖整个列表。note move 不移动文件，也不改正文。

note bulk：按过滤器批量整理

dino note bulk --tags "Inbox" --tag-add "AI" --format json --dry-run
dino note bulk --days 30 --boxes "Work/Inbox" --box-replace "Archive/Review" --expected-count 12 --confirm --format json

note bulk 只接受受控过滤器，不支持 --sql 作为写入目标筛选。真实写入必须先 dry-run，再带 --confirm --expected-count <n>。

note patch：结构化编辑正文

dino note patch <note-id> --append-section "复盘" --content @./section.md --format json --dry-run
dino note content-read <note-id> --format json
dino note patch <note-id> --append-section "复盘" --content @./section.md --read-token @/tmp/dinox-read-token-<random> --format json

note patch 只用于正文结构化编辑。先 dry-run，再在真实写入前执行 content-read 并传回 readToken。默认 content-read 只返回 block 类型、范围、hash 和字符数，不返回 block 文本、预览或 attributes，同时返回 readTokenScope: "structural-metadata"。只有用户授权全文读取时才添加 --include-content；此时返回 readTokenScope: "full-content"。替换媒体、表格、容器、未知节点等受保护 block 时，必须使用已审阅全文后取得的 full-content token，并显式添加 --allow-protected-replace；默认 scope 会被拒绝。

token 短期有效（当前为 30 分钟，以 readTokenExpiresAt 为准），绑定生成它时当前账号对应的本地 PowerSync 数据库作用域，不能在切换账号或本地数据库后复用。token 也是单次使用的，任何真实 patch 尝试都会先消费它，失败后重试必须重新执行 content-read。Agent 应把 token 写入唯一、仅 owner 可读写（mode 0600）的临时文件，通过 --read-token @<file> 传入，并在这一次真实 patch 尝试后立即删除；不要把 token 放进命令参数、日志、笔记或可复用文件。

收藏状态

dino note star <note-id>
dino note unstar <note-id>
dino note star --ids @./note-ids.txt

5.5 删除笔记

dino note delete <note-id>

说明：

• 这是软删除，不是物理彻底抹除
• 建议先加 --dry-run 再执行正式删除

dino note delete <note-id> --dry-run

5.6 管理待办任务

Dinox 的待办来自笔记内容中的任务列表。CLI 提供了 4 个最常用动作：搜索、追加、创建、更新状态。

搜索待办

dino todo search
dino todo search "付款"
dino todo search "付款" --status uncompleted
dino todo search --from 2026-03-01 --to 2026-03-07 --limit 100

按标签筛选待办

dino todo search --tags "工作,财务"

创建一条新的待办笔记

dino todo create "补交报销单"

一次创建多条待办

dino todo create --task "补交报销单" --task "整理发票"
dino todo create --tasks '["补交报销单","整理发票"]'
dino todo create --tasks @./todo.txt --title "本周财务待办"

追加待办到现有笔记

dino todo append "补交报销单"
dino todo append --note-id <note-id> --task "补交报销单" --task "整理发票"
dino todo append --note-id <note-id> --tasks @./todo.txt

说明：

• 如果不传 --note-id，CLI 会自动选一条“适合追加任务”的最近笔记
• 如果该笔记末尾已有任务列表，会直接并入；没有则会新建任务列表

更新待办状态

dino todo update <task-id> --status completed
dino todo update <task-id> --note-id <note-id> --status completed
dino todo update <task-id> --status uncompleted

兼容写法也支持：

dino todo update <task-id> --status done
dino todo update <task-id> --status false

但为了可读性，推荐始终使用：

• completed
• uncompleted

对没有持久 task id 的旧笔记，todo search 会返回 legacy-task-* 合成 id。该 id 绑定搜索时的任务位置和内容；如果笔记结构随后变化，更新会安全失败，必须重新搜索，避免把状态写到另一条任务。建议始终把搜索结果中的 note_id 一并传给 --note-id。

5.7 管理标签

查看全部标签

dino tag list

创建标签

dino tag add "工作/项目A"
dino tag add --name "工作/项目A" --emoji "🧠"

说明：

• 支持层级标签，如 工作/项目A
• 已删除但同名的标签，CLI 会尽量做恢复而不是重复新建

查看、调整和合并标签层级

dino tag tree --format json
dino tag stats --format json
dino tag rename "工作/旧项目" "新项目" --format json --dry-run
dino tag move "工作/新项目" --to "归档" --format json --dry-run
dino tag merge "重复标签" "规范标签" --format json --dry-run
dino tag merge "重复标签" "规范标签" --expected-count <affected-count> --confirm --format json

tag merge 会更新笔记引用并软删除来源子树。真实写入必须使用新鲜 dry-run 返回的 data.changes.affected_count，同时提供 --expected-count 和 --confirm。

5.8 管理卡片盒

查看全部卡片盒

dino box list

创建卡片盒

dino box add "Inbox"
dino box add --name "Inbox" --description "用于存放待整理的想法和资料"

说明：

• --description 很值得写
• 这段说明会帮助 AI 和你自己更准确地理解这个卡片盒的用途

查看、调整和合并卡片盒层级

dino box tree --format json
dino box stats --format json
dino box rename "工作/Inbox" "待整理" --format json --dry-run
dino box move "工作/待整理" --to "归档" --format json --dry-run
dino box merge "工作/重复" "工作/规范" --format json --dry-run
dino box merge "工作/重复" "工作/规范" --expected-count <affected-count> --confirm --format json

box merge 会更新笔记归属并软删除来源子树，同样要求新鲜 dry-run、--expected-count 和 --confirm。

5.9 管理 Prompt

查看全部 Prompt

dino prompt list

新建 Prompt

dino prompt add --name "周报助手" --prompt "请基于本周笔记输出一份简洁周报"
dino prompt add --name "周报助手" --prompt @./weekly-prompt.txt

5.10 查看版本与配置

查看版本信息

dino info

查看全部可读配置

dino config get

查看单个配置项

dino config get sync.timeoutMs

设置同步超时

dino config set sync.timeoutMs 20000

目前最常用、也是正式开放可写的配置项就是：

• sync.timeoutMs

6. 完整命令速查

这一节适合“我已经知道要做什么，只想确认命令怎么写”。

6.1 全局参数

这些参数可以放在很多命令前后使用：

示例：

dino --format json note search "AI"
dino note search "AI" --offline --format json

6.2 auth：登录与状态

dino auth login
read -rs DINOX_TOKEN
printf '%s' "$DINOX_TOKEN" | dino auth login --token-stdin
unset DINOX_TOKEN
dino auth status
dino auth logout
dino auth logout --clear-local-db

用途说明：

• login：不带 token 时在终端显示二维码，用 Dinox App「设置 → 设备配对 → 扫一扫」确认登录；也可以保存 token 并验证连接
• 登录会完成首次同步。CI / 自动化没有扫码条件时，用 --token-stdin 或 DINOX_TOKEN
• status：查看登录状态、本地库位置、同步状态
• logout：退出登录
• logout --clear-local-db：退出并删除本地 SQLite 缓存
• logout 会优先清除配置中保存的凭据；若 daemon 停止、身份解析、数据库 owner lease 获取或释放、缓存删除失败，错误详情会返回 persistedCredentialsCleared、cleanupPhase 和缓存路径。CLI 会尝试释放全部已取得的 lease；即使某个 release 失败，也不会跳过后续 release 或覆盖更早的主错误。此时凭据已清，但不能认为本地清理已安全完成。
• 当前 shell 中的 DINOX_TOKEN 不受 logout 影响；结果中的 environmentTokenActive: true 表示该环境仍可认证。

6.3 sync：手动同步

dino sync
dino sync --sync-timeout 20000

用途说明：

• 主动执行一次连接与同步
• 首次使用、网络恢复后、或想刷新本地缓存时最常用
• --sync-timeout 是包含 checkpoint、下载、本地索引和前台运行时准备在内的总预算；AI/CI 外层命令超时应至少比它多几秒
• 上传仍在进行不会阻塞下载新鲜度。判断成功应看 stale、downloadIdle 和 gate，不能只看兼容字段 idle
• 结构化成功结果会在数据库关闭、owner lease 释放和 daemon 恢复完成后输出

6.4 note：笔记管理

搜索与查看

dino note search [query]
dino note get <id>
dino note get <id> --context-only
dino note preview <id> --lines 30
dino note detail <id>
dino note detail --ids @./ids.txt

创建与修改

dino note create --title "标题" --content @./note.md --type note
dino note update <id> --tags "工作,AI"
dino note update <id> --boxes "Inbox"
dino note update <id> --starred true
dino note star <id>
dino note unstar <id>
dino note delete <id>

重点参数：

• note search
  • --tags <expr>：标签表达式
  • --from <date> / --to <date> / --days <n>：时间过滤
  • --starred <true|false>：按收藏状态过滤
  • --boxes <list>：按卡片盒过滤
  • --sql <expr>：高级筛选
  • --limit <n> / --offset <n>：分页
  • --fields <list>：裁剪输出字段
  • --include-deleted：包含软删除笔记
• note create
  • --title：必填
  • --content：必填，可用 @文件
  • --type <note|crawl>：默认 crawl
  • --tags / --boxes
  • --dry-run
• note update
  • [id] 或 --ids
  • --tags / --boxes / --starred
  • --dry-run

6.5 todo：待办管理

dino todo search [query]
dino todo append [task]
dino todo create [task]
dino todo update <task-id> --status completed

重点参数：

• todo search
  • --status <all|completed|uncompleted>
  • --tags <list>
  • --from <date> / --to <date> / --days <n>
  • --limit <n>
  • --scan-limit <n>
  • --include-deleted
• todo append
  • [task] / --task / --tasks
  • --note-id <id>
  • --dry-run
• todo create
  • [task] / --task / --tasks
  • --title <string>
  • --dry-run
• todo update
  • --status <status> 必填
  • --note-id <id>：用搜索结果中的笔记 id 精确限定目标
  • --dry-run

6.6 tag：标签管理

dino tag list
dino tag add "工作/项目A"
dino tag add --name "工作/项目A" --emoji "🧠"

6.7 box：卡片盒管理

dino box list
dino box add "Inbox"
dino box add --name "Inbox" --description "用于存放待整理资料"

重点参数：

• --description <string>：用途说明
• --color <string>：颜色
• --dry-run

6.8 prompt：Prompt 管理

dino prompt list
dino prompt add --name "周报助手" --prompt "请基于本周笔记输出简洁周报"

6.9 config：CLI 配置

dino config get
dino config get sync.timeoutMs
dino config set sync.timeoutMs 20000

6.10 graph：知识图谱查询

dino graph backlinks <note-id>
dino graph outlinks <note-id>
dino graph related <note-id> --depth 2
dino graph stats

说明：

• 这些命令用于查看笔记之间的链接关系
• 在线模式下，CLI 会自动确保 daemon 可用，并通过 daemon-owned DB runtime 执行
• 如果你只想用本地缓存而不启动 daemon，可加 --offline
• 如果 daemon 不可用，默认在线模式会返回带 suggested_action 的结构化错误；不会静默回退到另一个进程打开本地 DB

例如：

dino graph related <note-id> --depth 2 --offline --format json

6.11 meta：查看元数据

dino meta stats
dino meta schema

用途说明：

• meta stats：看 notes / tags / boxes 等统计信息
• meta schema：看 Dinox 结构化数据 schema，适合 AI / 自动化接入

6.12 storage：自定义存储配置与上传

dino storage list
dino storage test
dino storage test --storage-id <id>
dino storage upload ./report.pdf
dino storage upload ./photo.jpg --category images
dino storage upload ./report.pdf --key imports/report.pdf --overwrite
dino storage stats

重点说明：

• 这是给 Dinox 的自定义存储配置用的，不是一个“任意云盘命令”
• storage list 会列出当前可用的自定义存储，并标出活动配置
• storage test 会测试目标存储是否可写
• storage upload 会上传本地文件，并写入资源记录
• 如果不是上传到当前活动存储，可用 --storage-id <id> 指定目标
• --category 支持：images、audios、files、videos
• 如果你想自己指定对象 key，可用 --key <string>；key 和存储路径前缀不能包含纯 . 或 .. 路径段，否则标准 URL 客户端会把路径归一化到错误对象
• 显式 --key 默认拒绝覆盖已有主对象或图片缩略图；只有在确认替换这些精确 key 后才使用 --overwrite
• 使用 --overwrite 时，一旦远端对象写入成功，后续缩略图或资源 metadata 记录失败不会自动删除已经写入的远端对象。不要把命令失败理解为远端已回滚；请检查结构化错误详情中的 remoteObjectChanged、affectedKeys 和主对象 storageKey，再核查或重试相关 key
• --dry-run 非常适合在正式上传前确认目标位置

6.13 schema：查看命令 schema

dino schema
dino schema note.search
dino schema todo.update --format json

适合场景：

• 你不确定某个命令的参数怎么写
• 你要让 AI / 脚本可靠调用 CLI
• 你想快速查看命令风险级别、输出结构、示例

6.14 daemon：管理后台进程

dino daemon start
dino daemon status
dino daemon restart
dino daemon stop

调试时可以前台运行：

dino daemon start --no-detach

daemon 是公开 CLI 模块，也可以通过 schema 查询：

dino schema daemon.start --format json

daemon 通过用户数据目录下的私有 Unix domain socket 通信，Windows 使用命名管道；--port 仅保留给旧脚本作为兼容字段，不再作为监听地址。

需要在当前进程打开 PowerSync SQLite 的命令（例如写命令、sync、在线 auth status、--offline 或 --require-sync 读取）会先取得跨进程生命周期锁。如果同一用户数据库正由健康 daemon 持有，CLI 会暂时停止该实例；只有在命令结束、数据库关闭且 owner lease 成功释放后，才会按原端口恢复它。使用其他用户数据库的 daemon 不会被停止；如果关闭或释放失败，CLI 会保留 daemon 为停止状态并在 stderr 报告警告，避免两个运行时同时持有同一 SQLite 数据库。

6.15 gateway：把本机 Agent 挂成远程设备

在 Dinox App 中为每个 Agent 选择工作目录；会话始终保留开始时的目录，开启新话题也不改变。App 可以浏览该会话在这台电脑上的目录。

dino gateway detect
dino gateway detect --add
dino gateway add Hermes --command hermes --arg acp
dino gateway list
dino gateway status
dino gateway reload
dino gateway remove Hermes

detect 会在 PATH 上查找 ACP agent，并用真实握手确认能否启动。覆盖范围与 Paseo 的 ACP catalog 对齐，另外包含 Pi（pi-acp）、Antigravity（agy-acp）、Muse Code（muse-code-acp）和 OMP（omp acp）。只认本机已经装好的命令，不会为了探测去 npx -y 下载。每个 agent 一握手完就打印，不用等最慢的那个。某个启动方式一直不应答时，不再换参数重试。--add 把已确认的 agent 写入当前账号的 gateway 配置，并由 daemon 托管。gateway list 只显示环境变量名，不显示值。dino gateway mcp 由这些 agent 拉起，对外提供笔记、待办、标签、卡片盒等读写工具，以及把本机文件放进回复的 send_file。账号、同步、守护进程和 gateway 自身的命令不在这套工具里。

6.16 info：查看版本与技能仓库地址

dino info

6.17 update：升级 CLI

dino update

升级 CLI 之后，会为本机已有、但还没有 ACP 命令的 Agent 安装适配器（Claude Code、Codex、ZCode）。--format json 的 acpAdapters 返回每一项的 installed 或 failed。

7. AI / 脚本自动化

如果你希望让 AI 助手或脚本可靠调用 Dinox 数据，推荐直接使用 CLI 命令的结构化输出。

7.1 使用 JSON 输出

dino note search "dinox" --limit 5 --format json
dino note detail <id> --format json
dino todo search --status uncompleted --format json

--format json 会返回稳定的结构化 envelope，适合被脚本、自动化任务和 AI Agent 解析。

2.0 对几个读命令统一了 freshness envelope，升级脚本时需要迁移：

• dino note get 只返回轻量 data.note，不再默认暴露正文。
• dino note detail 始终返回 data.stale、data.count 和 data.notes，即使只查询一条笔记。
• dino prompt list 从 data.prompts 读取，dino box list 从 data.boxes 读取；两者同时返回 data.stale 和 data.count。
• 所有 structured dry-run 都会返回 data.stale 和 data.sync.gate，用于判断预览是否建立在新鲜数据上。

Agent 调用在线命令时，只要 schema 提供 --sync-timeout，建议传入有界预算（例如 20000），并把宿主工具超时设为高 5–10 秒。宿主先超时但没有收到 structured envelope 时，结果是未知，不要直接重试写入；先检查新鲜度或写入后置条件。

7.2 先读取命令 schema

不确定某个命令支持哪些参数、输出哪些字段时，先读取 schema：

dino schema
dino schema note.search --format json
dino schema todo.update --format json

schema 包含命令路径、风险级别、参数、选项、输出字段和示例。写操作建议先使用 --dry-run 确认结果。

8. 常见问题

Q1：安装或升级后出现 allowScripts / Ignored build scripts，或者一用就报 better-sqlite3

原因：本地数据库依赖 better-sqlite3，图片处理依赖 sharp。npm 11.16+ 和 pnpm 10.15+ 默认不运行这两个包的安装脚本，本机程序就没有装上。Node.js 26 也不在支持范围内，Homebrew 的 brew install node 现在装的就是 26。

解决：换成 Node.js 24，再重新安装。

node -v
npm install -g @dinoxx/dinox-cli@latest --allow-scripts=better-sqlite3,sharp
dino info

node -v 必须是 v22 到 v25。黄字警告本身不是升级失败；版本号没有变成最新版时，用上面这条命令，不要继续用旧的 dino update。

Q2：报错 Missing resolved userId for the current authorization

原因：你还没有完成登录，或当前 DINOX_TOKEN 环境变量覆盖了本地 token，CLI 需要先在线解析这个 token 对应的用户身份。

解决：在自己的终端运行 dino auth login，用 Dinox App 扫码。CI 或已有 token 时：

read -rs DINOX_TOKEN
printf '%s' "$DINOX_TOKEN" | dino auth login --token-stdin
unset DINOX_TOKEN

如果你使用环境变量登录，确认 DINOX_TOKEN 已设置后直接运行一次在线命令：

dino auth status --format json
dino sync

Q3：创建笔记时报 Unknown tags 或 Unknown zettel box names

原因：你引用了不存在的标签或卡片盒。

解决：先创建，再重试。

dino tag add "你的标签"
dino box add "你的卡片盒"

Q4：我已经同步过了，能不能完全离线查询？

可以。很多读命令都支持：

--offline

例如：

dino note search "日报" --offline
dino graph stats --offline --format json

前提是：你之前至少成功同步过一次，本地缓存里已经有数据。

Q5：note update 为什么不是“追加标签”？

因为它的设计就是“全量替换”。

例如：

dino note update <note-id> --tags "工作,AI"

执行后，目标笔记的标签会被替换成这两个，而不是在原来基础上追加。

追加标签请使用：

dino note tag <note-id> --add "工作,AI"

Q6：todo append 不传 --note-id 时会发生什么？

CLI 会自动选一条最近的、适合追加任务的笔记作为目标。

如果你不希望它自动选，最稳妥的做法是显式传：

dino todo append --note-id <note-id> --task "补交报销单"

Q7：Windows 下 @file 参数解析不稳定怎么办？

在 PowerShell 中，建议把 @文件路径 放进引号里。

例如：

dino note create --title "测试" --content "@.\note.md" --type note

Q8：怎么知道某个命令到底支持哪些参数？

最直接的方法：

dino <命令> --help

如果你想看更结构化的 schema：

dino schema
dino schema note.search
dino schema todo.update --format json

9. 配置文件、数据库与环境变量

9.1 默认文件位置

macOS

• 配置文件：~/Library/Application Support/dinox/config.json
• 本地数据库：~/Library/Application Support/dinox/dinox-cli.sqlite

Windows

• 配置文件：%APPDATA%\dinox\config.json
• 本地数据库：%LOCALAPPDATA%\dinox\dinox-cli.sqlite

Linux

• 配置文件：~/.config/dinox/config.json
• 本地数据库：~/.local/share/dinox/dinox-cli.sqlite

9.2 常用环境变量

9.3 macOS / Linux 与 Windows 的多行命令差异

macOS / Linux（bash / zsh）

用反斜杠 \ 续行：

dino note create \
  --title "标题" \
  --content "正文" \
  --type note

Windows PowerShell

用反引号 ` 续行：

dino note create `
  --title "标题" `
  --content "正文" `
  --type note

10. 如何查看帮助

任何时候都可以直接看 CLI 帮助：

dino --help
dino help note

更常见的写法是：

dino note --help
dino note create --help
dino todo --help
dino storage upload --help

如果你是脚本作者或 AI Agent 开发者，强烈建议搭配这两个命令一起使用：

dino schema
dino schema <path> --format json

如果你是第一次用，建议按下面顺序熟悉：

1. dino auth login
2. dino note search
3. dino note create
4. dino todo search
5. dino tag add / dino box add
6. dino schema

这样会最快建立完整使用感。