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