kivault-cli 1.4.1__tar.gz

kivault_cli-1.4.1/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# env
+.env
+
+# Virtual environments
+.venv

kivault_cli-1.4.1/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: kivault-cli
+Version: 1.4.1
+Summary: Add your description here
+Requires-Python: >=3.13
+Requires-Dist: agent-skill-dist>=0.1.1
+Requires-Dist: httpx[socks]>=0.28.1
+Requires-Dist: typer>=0.24.2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.20.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.15.12; extra == 'dev'
+Requires-Dist: ty>=0.0.32; extra == 'dev'
+Requires-Dist: uv>=0.11.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# KiVault CLI
+
+KiVault CLI 是 KiVault HTTP API 的命令行客户端，使用 `typer` 和 `httpx` 实现。
+当前命令以仓库内的 `openapi.json` 为准。
+CLI 主要面向 `/api/v1` Data Plane；`item list` 使用 `/api/v2/items/search`，
+`health`、`whoami` 和公开读取仍使用后端定义的对应路径。
+
+## 运行
+
+开发态直接运行：
+
+```bash
+uv run python main.py --help
+uv run python main.py --version
+```
+
+项目同步或安装后，也可以使用 console script：
+
+```bash
+kivault --help
+```
+
+为了自动补全，可通过 `kivault --install-completion` 来拥有自动补全的能力。
+
+## 配置
+
+CLI 不保存 token，也不提供 `login` 或 `token` 管理命令。认证统一通过环境变量传入：
+
+```bash
+export KIVAULT_SERVER_URL=http://127.0.0.1:8000
+export KIVAULT_TOKEN=<你的 KiVault token>
+```
+
+`KIVAULT_SERVER_URL` 可选，默认值是 `http://127.0.0.1:8000`。
+也可以用全局参数临时覆盖服务地址：
+
+```bash
+uv run python main.py --server http://127.0.0.1:8000 whoami
+```
+
+`whoami` 会请求 `/api/whoami`，并同时输出当前服务地址与 `KIVAULT_TOKEN` 是否已设置：
+
+```bash
+uv run python main.py whoami
+```
+
+## 常用流程
+
+```bash
+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 版本：
+
+```bash
+uv run python main.py --version
+```
+
+检查发布服务上的最新版本：
+
+```bash
+uv run python main.py upgrade
+```
+
+确认升级时才会安装最新 wheel：
+
+```bash
+uv run python main.py upgrade --yes
+```
+
+`upgrade` 会读取：
+
+```text
+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 安装状态：
+
+```bash
+uv run python main.py skill status
+uv run python main.py --json skill status
+```
+
+安装到当前仓库：
+
+```bash
+uv run python main.py skill install --target repo
+```
+
+目标路径为：
+
+```text
+./.agents/skills/kivault-cli
+```
+
+安装到用户全局 Codex skills 目录：
+
+```bash
+uv run python main.py skill install --target global
+```
+
+目标路径为：
+
+```text
+${CODEX_HOME:-~/.codex}/skills/kivault-cli
+```
+
+如果目标已存在，默认拒绝覆盖；确认覆盖时加 `--yes`：
+
+```bash
+uv run python main.py skill install --target repo --yes
+```
+
+也可以指定自定义 skills 根目录：
+
+```bash
+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` 查看参数说明和使用示例：
+
+```bash
+uv run python main.py item create --help
+uv run python main.py item object upload --help
+```
+
+默认帮助输出启用 Rich 表格样式。Agent、脚本或日志采集场景如果更适合纯文本输出，可以在启动 CLI 时设置：
+
+```bash
+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、图片、压缩包或其他二进制文件，请使用：
+
+```bash
+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 执行工具杀掉：
+
+```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` 都可以一次传入多个文件路径，
+并创建同一个异步上传任务：
+
+```bash
+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 个文件。
+
+## 测试
+
+```bash
+.venv/bin/python -m pytest . -q
+```

kivault_cli-1.4.1/README.md

@@ -0,0 +1,223 @@
+# KiVault CLI
+
+KiVault CLI 是 KiVault HTTP API 的命令行客户端，使用 `typer` 和 `httpx` 实现。
+当前命令以仓库内的 `openapi.json` 为准。
+CLI 主要面向 `/api/v1` Data Plane；`item list` 使用 `/api/v2/items/search`，
+`health`、`whoami` 和公开读取仍使用后端定义的对应路径。
+
+## 运行
+
+开发态直接运行：
+
+```bash
+uv run python main.py --help
+uv run python main.py --version
+```
+
+项目同步或安装后，也可以使用 console script：
+
+```bash
+kivault --help
+```
+
+为了自动补全，可通过 `kivault --install-completion` 来拥有自动补全的能力。
+
+## 配置
+
+CLI 不保存 token，也不提供 `login` 或 `token` 管理命令。认证统一通过环境变量传入：
+
+```bash
+export KIVAULT_SERVER_URL=http://127.0.0.1:8000
+export KIVAULT_TOKEN=<你的 KiVault token>
+```
+
+`KIVAULT_SERVER_URL` 可选，默认值是 `http://127.0.0.1:8000`。
+也可以用全局参数临时覆盖服务地址：
+
+```bash
+uv run python main.py --server http://127.0.0.1:8000 whoami
+```
+
+`whoami` 会请求 `/api/whoami`，并同时输出当前服务地址与 `KIVAULT_TOKEN` 是否已设置：
+
+```bash
+uv run python main.py whoami
+```
+
+## 常用流程
+
+```bash
+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 版本：
+
+```bash
+uv run python main.py --version
+```
+
+检查发布服务上的最新版本：
+
+```bash
+uv run python main.py upgrade
+```
+
+确认升级时才会安装最新 wheel：
+
+```bash
+uv run python main.py upgrade --yes
+```
+
+`upgrade` 会读取：
+
+```text
+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 安装状态：
+
+```bash
+uv run python main.py skill status
+uv run python main.py --json skill status
+```
+
+安装到当前仓库：
+
+```bash
+uv run python main.py skill install --target repo
+```
+
+目标路径为：
+
+```text
+./.agents/skills/kivault-cli
+```
+
+安装到用户全局 Codex skills 目录：
+
+```bash
+uv run python main.py skill install --target global
+```
+
+目标路径为：
+
+```text
+${CODEX_HOME:-~/.codex}/skills/kivault-cli
+```
+
+如果目标已存在，默认拒绝覆盖；确认覆盖时加 `--yes`：
+
+```bash
+uv run python main.py skill install --target repo --yes
+```
+
+也可以指定自定义 skills 根目录：
+
+```bash
+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` 查看参数说明和使用示例：
+
+```bash
+uv run python main.py item create --help
+uv run python main.py item object upload --help
+```
+
+默认帮助输出启用 Rich 表格样式。Agent、脚本或日志采集场景如果更适合纯文本输出，可以在启动 CLI 时设置：
+
+```bash
+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、图片、压缩包或其他二进制文件，请使用：
+
+```bash
+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 执行工具杀掉：
+
+```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` 都可以一次传入多个文件路径，
+并创建同一个异步上传任务：
+
+```bash
+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 个文件。
+
+## 测试
+
+```bash
+.venv/bin/python -m pytest . -q
+```

kivault_cli-1.4.1/kivault_cli/__init__.py

@@ -0,0 +1 @@
+"""KiVault CLI package."""