agentic_huge_data_base / wiki
页面 Cognee · 2.2 CLI 接口·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 2.2

2.2 · CLI 接口（CLI Interface）

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节2.2 状态全文译文 模块界面与交互、图谱与关系、安装与启动、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节CLI Interface 上一章2.1 下一章2.3
源码线索
  • cognee/api/v1/ui/__init__.py
  • cognee/api/v1/ui/node_setup.py
  • cognee/api/v1/ui/npm_utils.py
  • cognee/api/v1/ui/ui.py
  • cognee/cli/_cognee.py
  • cognee/cli/api_client.py
  • cognee/cli/api_dispatch.py
  • cognee/cli/commands/add_command.py
  • cognee/cli/commands/cognify_command.py
  • cognee/cli/commands/config_command.py
模块标签
  • 界面与交互
  • 图谱与关系
  • 安装与启动
  • 测试、发布与运维
  • 检索、召回与索引

章节正文

CLI 接口

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/2.2-cli-interface

CLI 接口

相关源文件

本章引用的主要源码文件：

  • cognee/api/v1/ui/__init__.py
  • cognee/api/v1/ui/node_setup.py
  • cognee/api/v1/ui/npm_utils.py
  • cognee/api/v1/ui/ui.py
  • cognee/cli/_cognee.py
  • cognee/cli/api_client.py
  • cognee/cli/api_dispatch.py
  • cognee/cli/commands/add_command.py
  • cognee/cli/commands/cognify_command.py
  • cognee/cli/commands/config_command.py
  • cognee/cli/commands/delete_command.py
  • cognee/cli/commands/search_command.py
  • cognee/cli/minimal_cli.py
  • cognee/cli/reference.py
  • cognee/cli/user_resolution.py
  • cognee/modules/cognify/config.py
  • cognee/modules/data/methods/get_deletion_counts.py
  • cognee/tests/cli_tests/cli_unit_tests/test_api_client.py
  • cognee/tests/cli_tests/cli_unit_tests/test_cli_commands.py
  • cognee/tests/cli_tests/cli_unit_tests/test_cli_edge_cases.py
  • cognee/tests/cli_tests/cli_unit_tests/test_user_resolution.py
  • cognee/tests/integration/retrieval/test_rag_completion_retriever.py
  • cognee/tests/unit/interfaces/graph/get_graph_from_huge_model_test.py
  • cognee/tests/unit/interfaces/graph/get_graph_from_model_circular_test.py

目的与范围

cognee-cli 是一个命令行接口，提供基于终端访问 Cognee 知识引擎的能力。它作为核心 Python API 的封装，允许用户在不编写 Python 代码的情况下执行数据入库（提取）、知识图谱生成（认知化）和多策略检索（加载/搜索）。

该 CLI 面向技术用户，支持大语言模型（LLM）提供商、数据库后端和多代理隔离的高级配置。它可以在两种模式下运行：本地执行模式，直接与数据库交互；委托执行模式，作为运行中 Cognee REST API 服务器的轻量客户端。

来源： cognee/cli/_cognee.py:118-120，cognee/cli/api_client.py:1-11，cognee/cli/config.py:1-5

安装与入口点

CLI 会随 cognee 包自动安装。它注册了两个等效的入口点：cognee 和 cognee-cli。

pip install cognee
# 或者
uv pip install cognee

主入口点是 cognee.cli._cognee 中的 main() 函数，该函数初始化参数解析器并将命令分派到各自的实现类。

来源： cognee/cli/_cognee.py:190-192，cognee/cli/_cognee.py:201-203，cognee/version.py:1-5

命令架构

Cognee 使用可插拔的命令架构，其中每个 CLI 命令都是一个实现 SupportsCliCommand 接口的类。命令在运行时动态发现和注册。

命令发现与注册

_discover_commands() 函数从 cognee.cli.commands 导入命令模块，避免过早初始化整个 Cognee 引擎，从而提高 CLI 响应速度。

命令发现流程

Cognee · 命令发现与注册 · 图 1
Cognee · 命令发现与注册 · 图 1

来源： cognee/cli/_cognee.py:84-114，cognee/cli/_cognee.py:159-170，cognee/cli/api_dispatch.py:31-33

核心命令

add

将原始数据入库到指定的数据集中。它支持文本字符串、本地文件路径、S3 路径和 URL。

  • 实现： cognee/cli/commands/add_command.py 中的 AddCommand 类。
  • 数据流： 参数被解析为列表。该命令调用 cognee.add()，将数据持久化到配置的存储后端，并在关系数据库中注册。
  • 关键参数： data（位置参数，允许多个），--dataset-name（默认值：main_dataset）。

来源： cognee/cli/commands/add_command.py:11-38，cognee/cli/commands/add_command.py:41-51，cognee/tests/cli_tests/cli_unit_tests/test_cli_commands.py:46-55

cognify

核心处理命令，将入库数据转换为结构化的知识图谱。

  • 实现： cognee/cli/commands/cognify_command.py 中的 CognifyCommand 类。
  • 执行逻辑： 它触发一个管线，包括文档分类、片段切分（通过 TextChunker、LangchainChunker 或 CsvChunker）、实体提取和图构建。
  • 关键参数： --datasets，--chunk-size，--chunker（选项：TextChunker、LangchainChunker、CsvChunker），--background（作为后台任务运行）。

来源： cognee/cli/commands/cognify_command.py:12-33，cognee/cli/commands/cognify_command.py:51-55，cognee/cli/commands/cognify_command.py:92-126

检索

使用多种搜索策略从处理后的知识图谱中检索信息。

  • 实现： cognee/cli/commands/search_command.py 中的 SearchCommand 类。
  • 搜索类型：
  • GRAPH_COMPLETION：使用图上下文的自然语言问答。
  • RAG_COMPLETION：基于向量的文档片段检索。
  • CHUNKS：原始文本片段的语义搜索。
  • CODE：专门针对代码结构（函数、类）的搜索。
  • 输出格式： pretty（默认），json，simple。

来源： cognee/cli/commands/search_command.py:13-45，cognee/cli/commands/search_command.py:118-146，cognee/tests/cli_tests/cli_unit_tests/test_cli_commands.py:121-130

delete

从系统中删除数据。它包含一个安全预览功能，在删除前显示要删除的数据集、条目和用户的数量。

  • 实现： cognee/cli/commands/delete_command.py 中的 DeleteCommand 类。
  • 安全逻辑： 调用 get_deletion_counts() 提供摘要 DeletionCountsPreview。除非使用 --force 标志，否则需要确认。
  • 关键参数： --dataset-name，--all，--force。

来源： cognee/cli/commands/delete_command.py:13-32，cognee/modules/data/methods/get_deletion_counts.py:15-18，cognee/modules/data/methods/get_deletion_counts.py:21-52

可视化与 Web 界面

CLI 提供了一个内置标志来启动 Cognee Web 界面，用于图探索。

-ui 标志

运行 cognee -ui 会触发主解析器中的 UiAction。这会启动一个多进程环境，包括 Next.js 前端和 FastAPI 后端。

实现细节：

  • cognee/api/v1/ui/ui.py 中的 start_ui() 管理这些进程的生命周期。
  • 它使用 _is_port_available() 检查端口可用性（UI 默认 3000，API 默认 8000）。
  • 在 Unix 系统上，如果缺少 Node.js/NPM，它会通过 node_setup.py 使用 nvm 自动安装。

UI 启动流程

Cognee · -ui 标志 · 图 2
Cognee · -ui 标志 · 图 2

来源： cognee/cli/_cognee.py:56-80，cognee/api/v1/ui/ui.py:64-75，cognee/api/v1/ui/ui.py:138-183，cognee/api/v1/ui/node_setup.py:141-172

通过 API 远程执行

当提供 --api-url 标志时，CLI 会切换到"轻量客户端"模式。这避免了多个进程同时访问 SQLite 或 LanceDB 等数据库时出现的文件锁定问题。

API 分派器

api_dispatch.py 模块拦截命令并将其转发到 CogneeApiClient。

  • 认证： 支持 X-Api-Key 和 Authorization: Bearer 令牌。
  • 用户隔离： 通过 X-User-Id 请求头转发 --user-id。

来源： cognee/cli/api_dispatch.py:31-33，cognee/cli/api_dispatch.py:36-56，cognee/cli/api_client.py:1-11

全局选项与多租户

CLI 支持多个全局标志，这些标志会修改所有子命令的行为：

标志描述代码引用
--debug通过 debug.enable_debug() 启用调试模式，显示完整堆栈跟踪。cognee/cli/_cognee.py:32-55
--user-id指定用于多代理隔离的 UUID。每个 ID 拥有自己的会话历史。cognee/cli/_cognee.py:141-145
--api-url将 CLI 命令委托给远程 Cognee API 服务器（例如 http://localhost:8000）。cognee/cli/_cognee.py:146-151
用户解析

命令使用 resolve_cli_user() 将提供的 --user-id（或默认值）映射到关系数据库中的 User 实体。这确保了跨 CLI 会话的权限和数据所有权得到维护。

来源： cognee/cli/commands/add_command.py:63-65，cognee/cli/commands/search_command.py:98-100，cognee/cli/user_resolution.py:1-10

数据模型到图的映射

当 cognify 等命令运行时，它们使用 get_graph_from_model 将 Pydantic 模型（DataPoint）转换为图节点和边。

代码仓库实体映射 CodeFile 对象被转换为类型为 "CodeFile" 的 Node，带有指向其他文件的 "depends_on" Edge 对象和指向 CodePart 节点的 "contains" 边。

来源： cognee/tests/unit/interfaces/graph/get_graph_from_huge_model_test.py:15-34，cognee/modules/graph/utils.py:10-11