kivault-cli 1.4.2

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

检查 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

文件上传 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