KiVault CLI

KiVault CLI 是 KiVault HTTP API 的命令行客户端，使用 typer 和 httpx 实现。 当前命令以服务端运行中的 OpenAPI 为准；仓库的 .agents/skills/kivault-integration/ 保留开发期 API 契约参考。 CLI 主要面向 /api/v1 Data Plane；item list 使用 /api/v2/items/search， health、whoami 和公开读取仍使用后端定义的对应路径。

运行

开发态直接运行：

uv run python main.py --help
uv run python main.py --version

项目同步或安装后，也可以使用 console script：

kivault --help

为了自动补全，可通过 kivault --install-completion 来拥有自动补全的能力。

配置

CLI 不保存 token，也不提供 login 或 token 管理命令。认证统一通过环境变量传入：

export KIVAULT_SERVER_URL=http://127.0.0.1:8000
export KIVAULT_TOKEN=<你的 KiVault token>

KIVAULT_SERVER_URL 可选，默认值是 http://127.0.0.1:8000。 也可以用全局参数临时覆盖服务地址：

uv run python main.py --server http://127.0.0.1:8000 whoami

whoami 会请求 /api/whoami，并同时输出当前服务地址与 KIVAULT_TOKEN 是否已设置：

uv run python main.py whoami

CLI 不会输出 Token 片段或 S3 预签名 URL。

常用流程

uv run python main.py health
uv run python main.py whoami
uv run python main.py upgrade

uv run python main.py vault create Inbox
uv run python main.py vault list

uv run python main.py item add-text --vault-id <vault-id> --title "Note" --content "hello"
uv run python main.py item add-text --vault-id <vault-id> --title "Note.md" --content-file ./note.md
uv run python main.py item list --vault-id <vault-id>
uv run python main.py item list -q <item-id> --search-field id
uv run python main.py item list -q report --search-field title --search-field object_filename
uv run python main.py item export <item-id> --format markdown

uv run python main.py --json item add-file ./document.pdf --vault-id <vault-id>
uv run python main.py --json item object upload-task <item-id> <task-id>
uv run python main.py item object list <item-id>
uv run python main.py item object download <item-id> <object-id> --output ./document.pdf
uv run python main.py item object update <item-id> <object-id> --metadata '{"reviewed":true}'

uv run python main.py item batch submit ./batch.json
uv run python main.py item batch list

uv run python main.py tag create research
uv run python main.py tag add <tag-id> <item-id>

uv run python main.py skill status
uv run python main.py skill install --target repo

已实现命令

• health
• whoami
• upgrade
• vault list|create|get|update|delete
• item list|create|add-text|add-file|get|update|delete|export|batch-get|publish|discard-draft|version list|get|restore
• item batch submit|list|get|wait|download-source|delete
• item object list|upload|upload-raw|upload-multipart|upload-task|upload-task-wait|get|update|download|delete
• item object upload-session get|resume|parts|cancel|cancel-entry
• object list
• tag list|get-many|create|update|delete|add|remove
• public item|download-object
• skill status|install

版本与升级

查看当前 CLI 版本：

uv run python main.py --version

检查 PyPI 上的最新版本，并按当前安装方式给出升级命令：

uv run python main.py upgrade

upgrade 只检查版本，不会直接安装。输出中的推荐命令会随安装方式变化，例如：

uv tool upgrade kivault-cli
uv pip install --upgrade kivault-cli --python /path/to/python
python -m pip install --upgrade kivault-cli
pipx upgrade kivault-cli

upgrade --yes 为兼容旧参数保留，但不再执行安装；请使用输出中的推荐命令升级。

upgrade 会读取 PyPI：

https://pypi.org/pypi/kivault-cli/json

内置 Agent Skill

CLI wheel 内置了 kivault-cli agent skill。安装后，Codex 或其他兼容 skill 目录约定的 agent 可以通过该 skill 获取当前版本 CLI 的操作说明。

查看 skill 安装状态：

uv run python main.py skill status
uv run python main.py --json skill status

安装到当前仓库：

uv run python main.py skill install --target repo

目标路径为：

./.agents/skills/kivault-cli

安装到用户全局 Codex skills 目录：

uv run python main.py skill install --target global

目标路径为：

${CODEX_HOME:-~/.codex}/skills/kivault-cli

如果目标已存在，默认拒绝覆盖；确认覆盖时加 --yes：

uv run python main.py skill install --target repo --yes

也可以指定自定义 skills 根目录：

uv run python main.py skill install --output .agents/skills --yes

内置 skill 通过 agent-skill-dist 分发，随 KiVault CLI wheel 一起发布，因此 CLI 升级后可以重新运行 skill install --yes 同步 agent 使用的 skill。

参数提示与内容输入

每个命令都可以通过 --help 查看参数说明和使用示例：

uv run python main.py item create --help
uv run python main.py item object upload --help

默认帮助输出启用 Rich 表格样式。Agent、脚本或日志采集场景如果更适合纯文本输出，可以在启动 CLI 时设置：

KIVAULT_PLAIN_HELP=1 uv run python main.py item create --help

--content 与 --content-file 都写入 Item 的 content_text：

• --content "hello" 直接使用命令行中的文本。
• --content-file ./note.md 读取本地 UTF-8 文本文件内容后写入；它不是上传附件。

如果要上传 PDF、图片、压缩包或其他二进制文件，请使用：

uv run python main.py item add-file ./document.pdf --vault-id <vault-id>
uv run python main.py item object upload <item-id> ./document.pdf

上传前 CLI 会查询服务端能力：单文件 legacy 使用 raw-body 流式上传，多文件 legacy 使用 Base64 异步批次；s3_direct 模式在命令内完成直传，且不会输出预签名 URL。item add-file 总是先创建草稿，上传成功后才发布为 active。

图片和视频会在任何 API 请求之前自动读取尺寸，并为每个 Object 写入 width、height、aspect_ratio。item add-file --metadata 仍表示 Item metadata；附件覆盖值使用 --object-metadata：

uv run python main.py item add-file ./image.png --vault-id <vault-id> \
  --object-metadata '{"source":"scanner"}'

legacy 模式下可用 --no-wait 创建任务；此时 add-file 的 Item 保持草稿，任务成功后必须显式发布：

uv run python main.py item add-file ./document.pdf --vault-id <vault-id> --no-wait
uv run python main.py item object upload-task <item-id> <task-id>
uv run python main.py item object upload-task-wait <item-id> <task-id>
uv run python main.py item publish <item-id>

轮询参数：

• --poll-interval <seconds> 调整轮询间隔，默认 1.0 秒。
• --timeout <seconds> 调整等待超时，默认 600 秒；0 表示不超时。

当 --content-file 指向的文件不能作为正常 UTF-8 文本读取，CLI 会直接拒绝并提示改用文件上传命令。

上传多个 Object

item object upload 和 item object upload-multipart 都可以一次传入多个文件路径；实际批次和大小上限由服务端能力响应决定：

uv run python main.py item object upload <item-id> ./a.pdf ./b.md ./c.png
uv run python main.py item object upload-multipart <item-id> ./a.pdf ./b.md

上传大小与批次限制由服务端能力声明并最终校验；CLI 不再假设固定的 100MB 或 20 文件限制。

S3 直传失败时 CLI 会保留并报告 session ID。使用原始完整路径列表和原顺序恢复，CLI 会校验文件并复用已上传分片：

uv run python main.py item object upload-session get <item-id> <session-id>
uv run python main.py item object upload-session resume <item-id> <session-id> ./a.bin ./b.bin
uv run python main.py item object upload-session cancel <item-id> <session-id> --yes

Item 原子批量任务

批量任务 JSON 使用 UUID batch_id 作为幂等键，支持 create、update、delete、restore，并在服务端事务中整体成功或回滚：

uv run python main.py item batch submit ./batch.json
uv run python main.py item batch submit ./batch.json --no-wait
uv run python main.py item batch wait <task-id>
uv run python main.py item batch download-source <task-id> --output ./source.json

update、delete、restore 操作应使用 Item 返回的 current_version_number 作为 expected_version_number。

测试

.venv/bin/python -m pytest . -q