CLI-Anything ChromaDB CLI 实战基于 ChromaDB v2 REST API 的向量子集、文档与语义检索命令行工具【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-AnythingCLI-Anything 为 ChromaDB 向量数据库提供了一个名为cli-anything-chromadb的命令行 harnessREADME。它完全通过 ChromaDB 的 HTTP API v2 与服务器交互默认目标为http://localhost:8000覆盖服务器健康检查、集合collection管理、文档document增删查计以及语义检索四大命令组并提供交互式 REPL 与--json机器可读输出。读完本文你将掌握该 CLI 的完整命令参数、默认值与配置项并理解其底层 URL 构造、REPL 分发机制与错误处理策略便于将其接入脚本、CI 或 AI Agent 工作流。一、定位与运行前提从 SKILL.md 的描述看该工具被定位为“面向 AI agent 与自动化脚本的无状态statelessChromaDB 命令行接口”其核心特征是不依赖 ChromaDB Python SDK仅使用requests直连 v2 REST API见 chromadb_backend.py因此对服务器所在语言/进程无要求默认目标服务器http://localhost:8000租户default_tenant数据库default_databaseREADME Configuration 一节与 backend 源码 一致双交互模式不带子命令直接运行进入交互式 REPL带子命令则执行单条命令后退出。运行前提Python 3.10setup.py 中python_requires3.10以及一台可达的 ChromaDB 服务器。二、安装与可执行入口按 README 安装cd agent-harness pip install -e .该命令实际安装的是 setup.py 定义的cli-anything-chromadb包版本 1.0.0其关键元数据如下入口点console_scriptscli-anything-chromadb→cli_anything.chromadb.chromadb_cli:mainsetup.py#L35-L38运行依赖click8.0.0、prompt-toolkit3.0.0、requests2.28.0setup.py#L24-L28即 REPL 样式与补全能力来自 prompt_toolkitHTTP 通信来自 requests包数据随包分发skills/*.md即上面提到的 Agent 技能说明文件。除pip install外仓库还提供模块方式运行python -m cli_anything.chromadbmain.py 直接转调main()适合未安装入口脚本的临时调试场景。三、全局选项--json、--host 与环境变量所有子命令共享两个全局选项定义在根 Click group 上chromadb_cli.py#L17-L31选项默认值作用--json关闭所有命令输出改为 JSON缩进 2 空格--hosthttp://localhost:8000ChromaDB 服务器地址两点源码层面的补充选项必须放在子命令之前。--json/--host挂在根 group 上因此正确写法是cli-anything-chromadb --json collection list这与 README “Add--jsonbefore any subcommand” 的说明一致。支持环境变量覆盖。main()以cli(auto_envvar_prefixCHROMADB_CLI)启动chromadb_cli.py#L105-L107Click 会自动读取CHROMADB_CLI_*环境变量作为选项的默认值来源例如CHROMADB_CLI_HOST这在无终端交互的 Agent/脚本环境中尤其方便无需每次在命令行拼接--host。--host的值最终传给ChromaDBBackend(base_urlhost)chromadb_cli.py#L27backend 构造时会对 URL 做rstrip(/)去除尾斜杠chromadb_backend.py#L18单测 test_core.py 专门验证了这一行为因此--host http://other:8000/与不带斜杠的写法等效。四、命令全集参考README 给出的命令总览如下hub_knowledge为示例集合名# Server cli-anything-chromadb server heartbeat cli-anything-chromadb server version # Collections cli-anything-chromadb collection list cli-anything-chromadb collection info hub_knowledge cli-anything-chromadb collection create --name test_collection cli-anything-chromadb collection delete --name test_collection # Documents cli-anything-chromadb document count --collection hub_knowledge cli-anything-chromadb document get --collection hub_knowledge --limit 5 cli-anything-chromadb document add --collection hub_knowledge --id doc1 --document Hello world cli-anything-chromadb document delete --collection hub_knowledge --id doc1 # Semantic search cli-anything-chromadb query search --collection hub_knowledge --text how does the pipeline work --n-results 3下面逐组展开并结合core/目录下的实现补充每个参数的取值约束与默认值。4.1 server健康检查与版本实现在 core/server.pyserver heartbeatGET/api/v2/heartbeat。成功时打印服务器存活信息及nanosecond_heartbeat时间戳失败时服务器不可达等输出Server unreachable: ...并以退出码 1 结束server.py#L16-L35。--json模式下错误也输出为{error: ...}便于程序判断。server versionGET/api/v2/version输出服务器版本字符串--json模式下包装为{version: ...}。这两个命令是脚本接入时的典型前置检查。4.2 collection集合管理实现在 core/collections.py子命令参数说明list无以表格列出 Name / ID / Metadata空库时提示 No collections found.create--name必填--metadata可选JSON 字符串创建集合并返回服务器分配的id--metadata会经json.loads解析后随请求体下发collections.py#L47-L69delete--name必填按名称删除集合成功输出{status: deleted, name: ...}JSON 模式info name位置参数显示集合的 ID、Name、Metadata注意此处名称是位置参数而非--name选项一个实用细节ChromaDB 的文档级 API 使用集合IDUUID而用户习惯用名称操作。document与query命令内部都会先调用_resolve_collection_id()把名称解析成 IDdocuments.py#L9-L12、query.py#L9-L12使用者无需手动查 ID。4.3 document文档增删查计实现在 core/documents.py。该组所有命令都要求--collection指定集合名称子命令参数说明add--id必填可重复--document必填可重复--metadata可选可重复的 JSON 字符串批量写入。--id与--document通过多次出现实现批量例如--id a --document text A --id b --document text B每个--metadata值会被独立json.loads解析为一份 metadatadocuments.py#L22-L53get--id可重复可选--limit可选int--offset可选int按 ID 精确取回或分页浏览--limit/--offset透传给后端get请求体适合大集合翻页documents.py#L56-L98。表格输出中文档正文超过 80 字符会截断加...delete--id必填可重复按 ID 批量删除count无返回集合中文档总数JSON 模式输出{collection: ..., count: ...}README 示例覆盖了单文档写入与删除的最短路径结合上表可知批量操作与分页浏览是该组的完整能力边界。4.4 query语义检索实现在 core/query.pycli-anything-chromadb query search --collection hub_knowledge \ --text how does the pipeline work --n-results 3--text必填查询文本会以query_texts[text]形式下发单查询语义query.py#L32-L38--n-results默认5query.py#L25控制返回的最近邻条数输出人类模式逐条展示排名、文档 ID、distance距离值、metadata 与正文预览超过 120 字符截断JSON 模式直接透传服务器返回的ids/documents/distances/metadatas完整结构方便下游程序做距离阈值过滤。--json用法示例来自 READMEcli-anything-chromadb --json collection list cli-anything-chromadb --json query search --collection hub_knowledge --text pipeline --n-results 3五、底层实现ChromaDBBackend 与 v2 REST API 映射chromadb_backend.py 是唯一的网络层ChromaDBBackend用requests.Session统一带Content-Type: application/json头封装全部调用。所有集合级操作共享一个 URL 前缀chromadb_backend.py#L24-L26{base_url}/api/v2/tenants/{tenant}/databases/{database}默认即http://localhost:8000/api/v2/tenants/default_tenant/databases/default_database。各方法到 HTTP 端点的映射如下方法HTTP 调用说明heartbeat()GET{base_url}/api/v2/heartbeat服务器级端点不走租户前缀version()GET{base_url}/api/v2/version同上list_collections()GET{prefix}/collections—create_collection(name, metadata)POST{prefix}/collectionsmetadata 可选get_collection(name)GET{prefix}/collections/{name}名称 → 集合对象含 iddelete_collection(name)DELETE{prefix}/collections/{name}—add_documents(...)POST{prefix}/collections/{cid}/add请求体含ids、documents可选metadatas、embeddingsget_documents(...)POST{prefix}/collections/{cid}/get请求体按需含ids、limit、offsetdelete_documents(...)POST{prefix}/collections/{cid}/delete请求体{ids: [...]}count_documents(...)POST{prefix}/collections/{cid}/count—query(...)POST{prefix}/collections/{cid}/query请求体{query_texts: [...], n_results: N}两点值得注意构造签名允许传入自定义tenant/databasechromadb_backend.py#L15-L20单测 test_core.py#L45-L48 也验证了自定义租户/数据库的 URL 拼装但从 CLI 层面看--host只暴露了服务器地址租户与数据库在命令行上固定为默认值——若你的 ChromaDB 实例使用了非默认租户从源码结构看需要扩展 CLI 参数或改用环境变量/直接调用 backend。每个方法都会raise_for_status()任何 HTTP 错误都会以异常形式抛到命令层统一处理见下节。六、REPL 模式交互、分发与历史记录直接运行cli-anything-chromadb不带子命令时cli根 group 检测到ctx.invoked_subcommand is None转入_run_repl()chromadb_cli.py#L59-L102。其机制值得展开统一皮肤 ReplSkinREPL 外观品牌横幅、彩色提示符、表格、状态色由 utils/repl_skin.py 的ReplSkin(chromadb, version1.0.0)提供这是 CLI-Anything 所有 harness 共用的终端界面层。横幅会展示当前 harness 的 skill 安装方式与全局 SKILL.md 路径方便 AI agent 发现技能说明repl_skin.py#L218-L243。输入经 shlex 拆分后回投 Click每一行输入先shlex.split解析chromadb_cli.py#L87-L95再以standalone_modeFalse调用cli.main()。这意味着REPL 里能输入的就是命令行上能输入的子命令如document add --collection x --id 1 --document hi两者共用同一套参数解析与执行路径不存在行为分叉。命令帮助表REPL 内输入help/h/?展示内置命令清单chromadb_cli.py#L42-L56quit/exit/q退出。历史与补全ReplSkin.create_prompt_session()创建 prompt_toolkit 会话启用FileHistory与AutoSuggestFromHistoryrepl_skin.py#L486-L508历史文件默认落在~/.cli-anything-chromadb/historyrepl_skin.py#L159-L165。若 prompt_toolkit 不可用则自动退化为内置input()因此 REPL 在最小依赖环境下也能使用。REPL 错误隔离Click 的SystemExit在 REPL 循环中被吞掉chromadb_cli.py#L96-L102单条命令失败不会中断会话而是通过skin.error(...)打印后继续等待输入。七、JSON 输出与错误处理约定对脚本与 Agent 来说可预测的输出契约比功能本身更关键。所有命令遵循同一套双模式约定以 collections.py 与 query.py 的实现为准成功 --jsonjson.dumps(result, indent2)输出服务器原始响应heartbeat、collection 信息、查询结果等成功 人类模式由 ReplSkin 渲染为表格 / 状态行 / 成功提示如✓ Collection x created失败 --json输出{error: 异常信息}失败 人类模式输出✗ 错误到 stderr并以SystemExit(1)使进程退出码为 1server.py#L30-L35。这套“退出码 统一 JSON 错误形状”的组合使set -e脚本、CI 任务和 LLM 工具调用都能可靠地判断成败并解析失败原因。八、配置小结与适用边界汇总 README Configuration 一节并对照源码可用配置项如下配置项默认值覆盖方式服务器地址http://localhost:8000--host http://other:8000需置于子命令前或CHROMADB_CLI_HOST环境变量JSON 输出关--json置于子命令前或CHROMADB_CLI_JSON环境变量租户default_tenant仅 backend 构造参数CLI 未暴露数据库default_database同上适用边界基于当前仓库实现版本 1.0.0需要一台独立运行的 ChromaDB 服务器HTTP v2 API非嵌入式本地模式CLI 目前不暴露 embedding 相关参数add_documents虽在 backend 层接受embeddings参数chromadb_backend.py#L76-L79但document add命令未提供对应选项向量由服务器端 embedding 函数生成租户/数据库固定为默认值多租户场景需直接实例化ChromaDBBackend或扩展 CLIquery search为单查询文本内部固定query_texts[text]多查询批量场景不在当前命令面内。九、验证依据测试与配套文件tests/test_core.py全量 mock HTTP验证 URL 构造默认/自定义 base_url、尾斜杠去除、租户前缀拼接、session 头、heartbeat/version 的端点地址与返回解析等可在无 ChromaDB 环境时直接运行tests/test_full_e2e.py 与 tests/TEST.md端到端验证与测试说明skills/SKILL.md随包分发的 Agent 技能说明含命令速查表REPL 横幅也会指引 agent 读取该文件CHROMADB.md该 harness 在 agent-harness 层的设计文档。总体而言cli-anything-chromadb是一个薄而完整的 v2 API 命令行映射Click 负责参数解析与命令树ChromaDBBackend负责 REST 封装ReplSkin负责人机/机机双输出。理解了“名称→ID 解析、统一错误契约、REPL 复用 Click 分发”这三条主线就能把它稳妥地纳入自己的向量库运维与 Agent 工具链。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考