命令行与 agent skill

vesper 是一个管理记录的命令行工具。它有两种用法：你自己在终端或脚本里读写记录；或者让 Claude Code 这类编程 agent 通过 skill 调用它，回答关于你手帐的问题。

需要 Node.js 22.12 或更新版本。

安装和登录

npm install -g @pleasure1234/vesper
vesper login

vesper login 会打开浏览器。登录、用 passkey 解锁空间并允许访问，和连接 AI 客户端的流程一样。完成后终端会显示连接到的空间。

登录状态保存在 ~/.config/vesper/auth.json，只有你的用户能读，到期会自动续期。vesper logout 会吊销登录并删除这个文件。Free 套餐下只能读，写入需要 Pro。

查看当前连接的是哪个空间：

vesper whoami

配合 Claude Code 使用

skill 会告诉 agent 什么时候、怎样调用 vesper：先读再写，永远不要索要你的 passkey，删除前先确认。

vesper skill

它会把 skill 复制到 ~/.claude/skills/vesper。用 --dir 可以放到别处，比如某个项目的 .claude/skills 目录，或其他 agent 的 skills 目录。

重启 Claude Code，然后就可以问关于手帐的问题：

• "我十月开会那几天写了什么？"
• "列出我在里斯本拍的照片。"
• "根据这些笔记写今天的记录，标签加 工作。"（Pro）

agent 在你的终端里运行 vesper 命令，用的是你保存的登录状态。如果还没登录，它会请你自己运行 vesper login。

命令

命令	作用
vesper whoami	空间、套餐、角色，以及当前登录能否写入
vesper entries list	按时间倒序列出记录；--tag、--from、--to、--in、--pinned
vesper entries search <关键词>	正文或标签包含关键词的记录，筛选同上
vesper entries get <id>	一条记录的完整 Markdown
vesper entries create <文字>	写一条新记录；--file、--stdin、--tag、--public（Pro）
vesper entries update <id>	修改正文、标签、可见性、置顶、收藏或归档（Pro）
vesper entries delete <id> --yes	永久删除（Pro）
vesper tags list	标签及数量
vesper tags rename <旧> <新>	在所有记录上重命名标签（Pro）
vesper tags remove <标签>	从所有记录上移除标签（Pro）
vesper photos list	照片及所属记录、时间和地点
vesper photos download <id>	保存原图，加 --thumb 保存小图
vesper skill	安装 agent skill

输出是 JSON，可以直接接 jq。列表按页返回并带 next，用 --cursor 传回去取下一页，或加 --all 翻完所有页（最多 --max 条，默认 500）。日期是 UTC 的 YYYY-MM-DD。vesper <命令> --help 会列出全部参数。

vesper entries search 咖啡 --from 2026-10-01 | jq -r '.entries[].excerpt'
vesper entries create --file today.md --tag 日常

脚本和 CI

在脚本或 CI 里，到 设置 → 连接 → 个人 token 创建一个 token，设置为环境变量 VESPER_TOKEN，它会代替保存的登录状态。请把它放在 CI 的密钥管理里，不要写进脚本。

VESPER_TOKEN=vsp_… vesper entries list --from 2026-11-01