kivault-cli 1.4.1

Add your description here

KiVault CLI

KiVault CLI 是 KiVault HTTP API 的命令行客户端，使用 typer 和 httpx 实现。 当前命令以仓库内的 openapi.json 为准。 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

常用流程

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

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 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> # 通常会返回一个 access_url， 不加上 `--json` 可能被截断而看不到该参数。
uv run python main.py --json item object upload-task <item-id> <task-id> # 通常会返回一个 access_url， 不加上 `--json` 可能被截断而看不到该参数。
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 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
• item object list|upload|upload-multipart|upload-task|upload-task-wait|get|download|delete
• tag list|create|update|delete|add|remove
• public item|download-object
• skill status|install

版本与升级

查看当前 CLI 版本：

uv run python main.py --version

检查发布服务上的最新版本：

uv run python main.py upgrade

确认升级时才会安装最新 wheel：

uv run python main.py upgrade --yes

upgrade 会读取：

https://releases.kispace.cc/api/public/latest?app=kivault_cli&tags=default

内置 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

文件上传 API 是异步的：add-file、item object upload 和 item object upload-multipart 会先创建 Object 上传任务。CLI 默认会轮询任务进度直到完成，并输出服务端返回的进度与日志。 如果只想创建任务并稍后查询，可以加 --no-wait，推荐 agent 使用该参数，避免被 bash 执行工具杀掉：

uv run python main.py item object upload <item-id> ./document.pdf --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>

轮询参数：

• --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

后端限制为单个文件 100MB 以内，单次最多 20 个文件。

测试

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