Metadata-Version: 2.4
Name: inkcre-cli
Version: 0.1.0
Summary: An agent-friendly REST interface to InKCre
License-Expression: GPL-3.0-only
Project-URL: Repository, https://github.com/InKCre/core-py
Requires-Python: >=3.12
Requires-Dist: click<9,>=8.1
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: httpx<0.29,>=0.28.1
Requires-Dist: PyJWT<3,>=2.10
Description-Content-Type: text/markdown

# inkcre-cli

InKCre 的独立命令行界面，通过 Core REST API 检索信息、读取 Resolver 内容和管理部署。
它不安装 Core、不访问数据库，也不是执行 Job 的 Peer。

```sh
python -m pip install inkcre-cli
inkcre-cli --help
inkcre-cli connection set personal --input connection.json
inkcre-cli recall 'Agent 工具' --mode lexical --json
inkcre-cli get block:42 relation:8 --json
inkcre-cli resolver invoke block:42 --method get_solved_content
```

connection.json 包含 `base_url` 与 `jwt_secret`。默认连接文件是
`~/.inkcre/cli/connections.json`；可用 `--connections-file` 指定隔离文件。
这里的地址是 Core REST 入口，不是 PostgREST 或 MCP endpoint。
首个连接自动成为默认连接；`connection use personal` 修改默认值，`--connection NAME` 只选择本次接入。

`--help` 离线可用；有结构化输入的命令提供 `--schema`，从当前 Core 发现准确合同。
使用 `--input FILE`、`--input -` 或 `--input-json JSON` 提供输入。
`--json` 输出完整紧凑 JSON；二进制内容保存为文件，不做 Base64 编码。
`--output-dir DIR` 显式保存完整结果，stdout 返回入口文件路径。

## 发现与管理

先发现 exact type、method 或 schema，再提交它所描述的输入。例如：

```sh
inkcre-cli source types --json
inkcre-cli source create --type SOURCE_TYPE --schema
inkcre-cli source create --type SOURCE_TYPE --input source.json
inkcre-cli source collect 42 --input-json '{}'
inkcre-cli job wait 17 --for 10s --json
inkcre-cli job abort 17
inkcre-cli cron create --job-type core.source.collect.v1 --schema
inkcre-cli agent tools --json
inkcre-cli ai models --json
inkcre-cli config schemas --json
```

这里的 ID 仅为示例，应使用实际创建回执或查询返回的 ID。`source collect`、`source backfill` 和
`organization ruminate` 创建 Job，而不是在 CLI 或接入 Core 中同步执行。`job wait --for 10s` 最多观察
十秒，可能返回仍为 pending/running 的记录；停止观察不取消 Job。`job abort` 请求 best-effort 停止，
`abort_requested: true` 不代表执行端已经完成清理。只有后续记录才能说明实际结果。

`connection` 只管理本机连接，`config` 管理远端 deployment config；Agent definition 由 `agent` 管理，
模型目录由 `ai` 发现。Extension 配置和运行目标使用 `extension`，不混入 connection。

## 输出与续读

结果写 stdout，命令错误写 stderr。退出码 0 表示命令成功，1 表示远端/IO/部分结果失败，2 表示本机输入
错误，130 表示观察被中断。读取一个状态为 failed 的 Job 仍是成功读取，脚本应检查 Job 的实际 status。
批量读取与混合 recall 保留各项结果，不因一项失败丢弃其它成功项。

支持分页的目录使用 `--limit`、`--cursor` 和返回的 `next_cursor`；CLI 不自动翻页。
检索仍保留各模式自身的 limit 和结果结构，混合 recall 不融合排名。

人类可读输出过长时显示摘要和完整文件路径；`--json` 不截断、不 pretty-print。
二进制自动保存为文件；显式 `--output-dir DIR` 导出的入口 JSON 使用相对文件引用，整个子目录可以搬移。
这些是同一次 HTTP 响应的本地文件，不是新下载会话，也不会再次调用 Resolver。

开发使用独立 PDM 项目：`pdm install -p cli`、`pdm run -p cli check`、`pdm build -p cli`。
0.0.0 是未发布的开发版本；首次发行由仓库的 Release PR 准备。
