Metadata-Version: 2.4
Name: kivault-cli
Version: 1.4.2
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: packaging>=24
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 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
```

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

```bash
uv run python main.py upgrade
```

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

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

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

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