Kedro 命令行接口（CLI）完全指南：从命令参考到自定义扩展

本篇技术指南系统讲解 Kedro 框架的命令行接口（CLI），涵盖 Shell 自动补全配置、python -m kedro 的模块化调用方式、全局命令与项目命令的完整参数说明，以及如何通过 cli.py 与插件机制自定义项目命令。读完本文，你将能够熟练使用 kedro new、kedro run 等核心命令完成项目创建、管道执行与打包发布，并能依据源码理解 CLI 命令的注册与加载原理。

目录

• Kedro CLI 概览
• 配置 Shell 自动补全（可选）
• 从 Python 模块方式调用 Kedro CLI（可选）
• 全局命令与项目命令
• 全局命令详解
• 项目命令详解
• 自定义或覆盖项目专属命令
• CLI 加载机制源码解读

Kedro CLI 概览

Kedro 的命令行接口让你可以在终端 Shell 中运行 Kedro 命令，例如 macOS 的 Terminal、Windows 的 cmd.exe 或 PowerShell。CLI 的核心用途有两个：创建新的 Kedro 项目与运行项目中的管道。

在终端中执行 kedro 并回车，即可看到可用命令的总览；输入 kedro --help 可查看帮助信息，kedro <command> --help 可查看具体命令的参数说明（帮助选项统一为 -h / --help，参见 kedro/framework/cli/utils.py 中的 CONTEXT_SETTINGS）。

CLI 入口定义在 kedro/framework/cli/cli.py 中，其根命令通过 click.group 注册，并附带版本选项：

# 查看版本号（对应 cli.py 中的 --version/-V 选项）
kedro --version

# 查看 Kedro 概览信息与已安装插件（对应 info 命令）
kedro info

其中 kedro info 会打印 Kedro 的 ASCII 徽标、版本号，以及通过入口点（entry point）发现的所有已安装插件及其版本。

配置 Shell 自动补全（可选）

如果你使用 macOS 或 Linux，可以为 kedro 命令配置 Shell 自动补全。首先确认当前使用的 Shell 类型：

echo $0

根据输出结果选择对应的配置方式。

Bash

将下面这行添加到 ~/.bashrc（或直接在命令行执行）：

eval "$(_KEDRO_COMPLETE=bash_source kedro)"

Z shell（Zsh）

将下面这行添加到 ~/.zshrc：

eval "$(_KEDRO_COMPLETE=zsh_source kedro)"

Fish

将下面这行添加到 ~/.config/fish/completions/foo-bar.fish：

eval (env _KEDRO_COMPLETE=fish_source kedro)

这套机制依赖 Click 的 Shell 补全协议：Kedro 通过 _KEDRO_COMPLETE 环境变量向对应的补全脚本生成器暴露命令结构。重新加载 Shell 配置（如 source ~/.bashrc）后，输入 kedro 再按 Tab 即可看到命令与参数补全建议。

从 Python 模块方式调用 Kedro CLI（可选）

除了 kedro 可执行文件，你还可以将 Kedro CLI 作为 Python 模块调用：

python -m kedro

该方式与直接运行 kedro 等价。其入口定义在 kedro/main.py 中：它调用 kedro.framework.cli.main，并会把 sys.argv[0] 规范化为 python -m kedro，使提示信息中的程序名保持一致。

全局命令与项目命令

Kedro 提供的命令被自动分组为两类，其分组逻辑定义在 kedro/framework/cli/cli.py 的 global_commands 与 project_commands 两个 click.Group 中：

• 全局命令（Global commands）：可以在任意目录运行，不绑定任何特定的 Kedro 项目；
• 项目命令（Project commands）：必须在 Kedro 项目目录内运行，作用于当前项目。

注意：项目相关命令可以在 Kedro 项目内的任意子目录中运行，不要求必须位于项目根目录。

从 cli.py 的 LazyGroup 定义可以看到两组的成员：

命令组	子命令	定义模块
全局命令	new、starter	kedro/framework/cli/starters.py
项目命令	registry、catalog、ipython、run、package、jupyter、pipeline、server	见下方各小节

这些子命令采用懒加载（lazy loading）机制（见 utils.py 中的 LazyGroup）：只有在实际执行某个子命令时，对应的模块才会被导入，从而加快 kedro --help 的响应速度。

如果在非项目目录中执行项目命令（如 kedro run），CLI 会给出明确提示：Kedro 正在当前工作目录中查找 pyproject.toml 文件——这正是判断一个目录是否为 Kedro 项目的标志（见 cli.py）。

全局命令详解

kedro new：创建新项目

kedro new 用于创建一个新的 Kedro 项目，底层通过 cookiecutter 渲染项目模板（项目模板位于 kedro/templates/project，提示定义见其 prompts.yml）。其完整参数如下：

参数	简写	说明
--config	-c	非交互模式，使用 YAML 配置文件提供项目信息；必须包含模板 prompts.yml 要求的键，默认为 project_name、repo_name、python_package
--starter	-s	指定 starter 模板：可以是本地目录路径、远程 VCS 仓库 URL，或 kedro starter list 中列出的别名
--checkout	—	在 starter 仓库中检出指定的 tag、分支或提交；仅在使用 --starter、--tools=pyspark 或 --example=yes 时生效
--directory	—	starter 仓库内部存放模板的目录（须与 --starter 一起使用）
--name	-n	新 Kedro 项目的名称
--tools	-t	选择要包含的工具，见下方工具列表
--example	-e	y/n，是否包含示例管道
--telemetry	-tc	yes/no，是否允许 Kedro 收集使用统计
--verbose	-v	查看详细日志与错误堆栈

--tools 支持以下 6 种工具（由 starters.py 中的 TOOLS_ARG_HELP 定义）：

1. Linting：基于 Ruff 的基础代码检查配置
2. Testing：基于 pytest 的基础测试配置
3. Custom Logging：更丰富的日志选项
4. Documentation：基于 Sphinx 的基础文档配置
5. Data Structure：提供数据存储的目录结构
6. PySpark：配置 PySpark 工作环境

工具名支持短名（lint,test,log,docs,data,pyspark）、all 与 none，可组合使用：

# 选择全部工具
kedro new --tools=all

# 选择部分工具（任意子集）
kedro new --tools=lint,test,log,docs,data,pyspark

# 不选择任何工具
kedro new --tools=none

--tools 的选择映射关系定义在 starters.py 的 TOOLS_SHORTNAME_TO_NUMBER 与 NUMBER_TO_TOOLS_NAME 中。Kedro Viz 无需选择，它始终被自动包含在项目中。交互式创建时可使用范围语法（如 1-3），源码中的 _parse_tools_input 负责解析。

常用组合示例：

# 全参数非交互式创建：指定名称、工具与示例管道
kedro new --name=my-new-project --tools=lint,test,log,docs,data --example=yes

创建过程中，CLI 还会校验项目 Python 包名：如果包名与 Python 关键字或标准库模块冲突（如 json、email），会直接报错终止（见 starters.py 的 _validate_package_name_is_importable），避免生成后无法导入的问题。

kedro starter：管理项目模板

kedro starter list 列出所有可用的官方 starter 别名。当前仓库中注册的官方 starter 定义在 starters.py：

• astro-airflow-iris：Astro + Airflow + Iris 示例
• spaceflights-pandas：pandas 版 Spaceflights 示例
• spaceflights-pyspark：PySpark 版 Spaceflights 示例
• databricks-iris：Databricks + Iris 示例
• support-agent-langgraph：LangGraph 支持 Agent 示例

# 列出所有官方 starter
kedro starter list

使用 starter 创建项目：

# 使用空间飞行（pandas）starter 创建项目
kedro new --starter=spaceflights-pandas

插件也可以通过 kedro.starters 入口点注册自定义 starter（KedroStarterSpec 结构，见 starters.py）。

项目命令详解

kedro run：运行管道

kedro run 是 Kedro 最核心的命令，定义于 kedro/framework/cli/project.py。它会创建一个 KedroSession 并调用 session.run() 执行管道。完整参数如下：

参数	简写	说明
--from-inputs	—	一组数据集名称，作为管道的起始点
--to-outputs	—	一组数据集名称，作为管道的终点
--from-nodes	—	一组节点名称，作为管道的起始点
--to-nodes	—	一组节点名称，作为管道的终点
--nodes	-n	只运行指定名称的节点
--runner	-r	指定 runner：SequentialRunner、ParallelRunner、ThreadRunner，默认 SequentialRunner
--async	—	以线程方式异步加载/保存节点输入输出；已被弃用，建议改用 --runner-params=is_async=True
--runner-params	—	传给 runner 的额外关键字参数，逗号分隔、等号赋值，如 max_workers=4,is_async=True
--env	-e	Kedro 配置环境名，默认 local
--tags	-t	只使用带有指定 tag 的节点构造管道；可多次指定，取并集
--load-versions	-lv	指定加载特定数据集版本（时间戳），格式 dataset:YYYY-MM-DDThh.mm.ss.sssZ
--pipeline	-p	要运行的已注册管道名称（已被弃用，建议改用 --pipelines）；未指定时运行 __default__
--pipelines	—	逗号分隔的多个已注册管道名称，如 data_engineering,feature_engineering；未指定时运行 __default__
--namespaces	-ns	只运行指定名称的命名空间节点
--config	-c	从 YAML 配置文件加载 run 参数；命令行参数优先于配置文件
--conf-source	—	项目配置存储目录的路径
--params	—	传递给上下文初始化器的额外参数，逗号分隔、等号或冒号赋值，如 param1=value1,param2=value2；用点号表示嵌套字典，如 param_group.param1:value1
--only-missing-outputs	—	只运行输出缺失的节点；节点全部输出已持久化时跳过执行

常用示例：

# 在默认环境（local）运行默认管道
kedro run

# 指定环境运行
kedro run --env=dev

# 只运行打了特定 tag 的节点（可叠加多个 tag）
kedro run --tags=tag1 --tags=tag2

# 使用并行 runner，并传入 max_workers 参数
kedro run --runner=ParallelRunner --runner-params=max_workers=4

# 只运行指定命名空间下的节点
kedro run --namespaces=data_science

# 从配置文件读取 run 参数（命令行参数优先）
kedro run --config=run_config.yml

# 只运行输出缺失的节点
kedro run --only-missing-outputs

从源码看，run 的执行链路为：load_obj 按名称加载 runner 类 → _resolve_runner_kwargs 合并 --async 与 --runner-params（见 project.py）→ settings.SESSION_CLASS.create() 创建会话 → session.run() 传入所有过滤条件。--pipeline 与 --pipelines 不能同时使用，源码会抛出 KedroCliError；而 --params 与 --runner-params 均由 _split_params 解析为字典，它底层使用 OmegaConf 的 from_dotlist 支持点号嵌套键（见 utils.py）。

kedro ipython：进入交互式环境

kedro ipython 打开一个预加载了项目变量的 IPython 会话（见 project.py）。会话中会自动提供以下变量：

• catalog：包含所有已定义数据集的目录实例（context.catalog 的快捷方式）
• context：Kedro 项目上下文，提供对 Kedro 库组件的访问
• pipelines：管道注册表中定义的管道
• session：编排管道运行的 Kedro 会话

kedro ipython

若修改了 catalog.yml 等配置，可使用 %reload_kedro line magic 重新加载这些变量，该 magic 也会在变量未定义时显示错误信息。--env 选项会设置 KEDRO_ENV 环境变量。

kedro jupyter：Jupyter 集成

kedro jupyter 提供三个子命令（见 kedro/framework/cli/jupyter.py），都会为项目创建一个名为 kedro_<package_name> 的专用 IPython 内核：

# 初始化项目的 Jupyter 内核
kedro jupyter setup

# 打开 Jupyter Notebook（预加载项目变量）
kedro jupyter notebook

# 打开 Jupyter Lab（预加载项目变量）
kedro jupyter lab

内核创建逻辑位于 _create_kernel：它安装用户级内核规格并修改 kernel.json，使内核启动时加载 kedro.ipython 扩展（见 jupyter.py）。

kedro package：打包项目

kedro package 将 Kedro 项目打包为 Python wheel，并导出配置文件（见 project.py）：

• 构建 .whl 文件并保存到 dist/ 目录；
• 将项目配置（排除所有 local/*.yml 文件）打包为独立的 conf-<package_name>.tar.gz 归档，便于部署或共享。

kedro package

两个产物都会出现在 dist/ 文件夹中（旧式项目布局除外）。打包配置时使用 tar --exclude=local/*.yml，确保本地敏感配置不被包含。

kedro pipeline：管理模块化管道

kedro pipeline 提供创建与删除模块化管道的命令（见 kedro/framework/cli/pipeline.py）：

# 创建名为 <name> 的模块化管道
kedro pipeline create <name>

# 不创建管道配置文件
kedro pipeline create <name> --skip-config

# 使用自定义 cookiecutter 模板创建管道
kedro pipeline create <name> --template=/path/to/template

# 指定配置环境（默认 base）
kedro pipeline create <name> --env=base

# 删除管道（-y 表示非交互式确认）
kedro pipeline delete <name> -y

创建命令会生成管道源码（src/<package>/pipelines/<name>/）、测试（tests/pipelines/<name>/）与配置（conf/<env>/parameters_<name>.yml、conf/<env>/catalog_<name>.yml）。模板查找优先级为：命令行 --template > 项目内 templates/pipeline/ > 全局默认模板（kedro/templates/pipeline）。管道名称需符合 Python 包命名规范（见 _assert_pkg_name_ok）。

kedro catalog：检查数据目录

kedro catalog 提供三个数据目录诊断命令（见 kedro/framework/cli/catalog.py）：

# 描述指定管道中使用的数据集，按类型分组（datasets/factories/defaults）
kedro catalog describe-datasets --pipeline=<pipeline_name>

# 列出数据目录中全部数据集工厂模式，按匹配优先级排序
kedro catalog list-patterns

# 解析工厂模式与管道数据集的匹配结果
kedro catalog resolve-patterns --pipeline=<pipeline_name>

describe-datasets 的输出将数据集分为三类：显式定义在 catalog 中的 datasets、由工厂模式解析出的 factories、以及未匹配任何模式的 defaults。结果以 YAML 形式输出。

kedro registry：查看已注册管道

kedro registry 用于查看 pipeline_registry.py 中注册的管道（见 kedro/framework/cli/registry.py）：

# 列出 pipeline_registry.py 中定义的所有管道
kedro registry list

# 描述指定管道的节点，默认描述 __default__ 管道
kedro registry describe <pipeline_name>

kedro registry describe data_engineering

describe 会输出管道中每个节点的名称与对应函数名。

kedro server：以 HTTP 服务方式运行

kedro server start 以 HTTP 服务方式启动 Kedro，允许外部系统通过 HTTP 端点编程式地触发管道执行（见 kedro/framework/cli/server.py）：

# 默认 host 与端口启动
kedro server start

# 指定 host 与端口
kedro server start --host 0.0.0.0 --port 8080

# 开发模式：代码变更后自动重启（勿用于生产环境）
kedro server start --reload

其参数包括：--host/-H（默认值见 kedro/server/utils.py 的 DEFAULT_HOST）、--port/-p（默认 DEFAULT_HTTP_PORT）、--reload、--env/-e（服务会话的 Kedro 配置环境）、--conf-source。服务暴露两个端点：GET /health（健康检查）与 POST /run（执行管道）。运行需要 fastapi、pydantic、uvicorn，缺失时会提示通过 uv pip install 'kedro[server]' 安装。

自定义或覆盖项目专属命令

Kedro CLI 允许将一组命令与依赖关联到某个目标，然后在项目目录内执行。项目支持的命令由框架侧定义，若想自定义 Kedro 命令，有两种方式：

1. 在项目的 Python 包中创建 cli.py 文件；
2. 通过插件框架向其中注入命令。

cli.py 文件模板如下（来自原文档，与当前仓库源码 project.py 的 run 定义对应）：

"""Command line tools for manipulating a Kedro project.
Intended to be invoked via `kedro`."""
from typing import Any

import click
from kedro.framework.cli.project import (
    ASYNC_ARG_HELP,
    CONFIG_FILE_HELP,
    CONF_SOURCE_HELP,
    FROM_INPUTS_HELP,
    FROM_NODES_HELP,
    LOAD_VERSION_HELP,
    NAMESPACES_ARG_HELP,
    NODE_ARG_HELP,
    ONLY_MISSING_OUTPUTS_HELP,
    PARAMS_ARG_HELP,
    PIPELINE_ARG_HELP,
    RUNNER_ARG_HELP,
    RUNNER_PARAMS_HELP,
    TAG_ARG_HELP,
    TO_NODES_HELP,
    TO_OUTPUTS_HELP,
    _resolve_runner_kwargs,
)
from kedro.framework.cli.utils import (
    CONTEXT_SETTINGS,
    _config_file_callback,
    _split_params,
    _split_load_versions,
    env_option,
    split_string,
    split_node_names,
    validate_conf_source,
)
from kedro.framework.session import KedroSession
from kedro.utils import load_obj


@click.group(context_settings=CONTEXT_SETTINGS, name=__file__)
def cli():
    """Command line tools for manipulating a Kedro project."""
@cli.command()

@click.option(
    "--from-inputs",
    type=str,
    default="",
    help=FROM_INPUTS_HELP,
    callback=split_string,
)
@click.option(
    "--to-outputs",
    type=str,
    default="",
    help=TO_OUTPUTS_HELP,
    callback=split_string,
)
@click.option(
    "--from-nodes",
    type=str,
    default="",
    help=FROM_NODES_HELP,
    callback=split_node_names,
)
@click.option(
    "--to-nodes", type=str, default="", help=TO_NODES_HELP, callback=split_node_names
)
@click.option(
    "--nodes",
    "-n",
    "node_names",
    type=str,
    default="",
    help=NODE_ARG_HELP,
    callback=split_node_names,
)
@click.option("--runner", "-r", type=str, default=None, help=RUNNER_ARG_HELP)
@click.option("--async", "is_async", is_flag=True, help=ASYNC_ARG_HELP)
@click.option(
    "--runner-params",
    type=click.UNPROCESSED,
    default="",
    help=RUNNER_PARAMS_HELP,
    callback=_split_params,
)
@env_option
@click.option(
    "--tags",
    "-t",
    type=str,
    default="",
    help=TAG_ARG_HELP,
    callback=split_string,
)
@click.option(
    "--load-versions",
    "-lv",
    type=str,
    default="",
    help=LOAD_VERSION_HELP,
    callback=_split_load_versions,
)
@click.option("--pipeline", "-p", type=str, default=None, help=PIPELINE_ARG_HELP)
@click.option(
    "--namespaces",
    "-ns",
    type=str,
    default="",
    help=NAMESPACES_ARG_HELP,
    callback=split_node_names,
)
@click.option(
    "--config",
    "-c",
    type=click.Path(exists=True, dir_okay=False, resolve_path=True),
    help=CONFIG_FILE_HELP,
    callback=_config_file_callback,
)
@click.option(
    "--conf-source",
    callback=validate_conf_source,
    help=CONF_SOURCE_HELP,
)
@click.option(
    "--params",
    type=click.UNPROCESSED,
    default="",
    help=PARAMS_ARG_HELP,
    callback=_split_params,
)
@click.option(
    "--only-missing-outputs",
    is_flag=True,
    help=ONLY_MISSING_OUTPUTS_HELP,
)
def run(
    tags: str,
    env: str,
    runner: str,
    is_async: bool,
    runner_params: dict[str, Any],
    node_names: str,
    to_nodes: str,
    from_nodes: str,
    from_inputs: str,
    to_outputs: str,
    load_versions: dict[str, str] | None,
    pipeline: str,
    config: str,
    conf_source: str,
    params: dict[str, Any],
    namespaces: str,
    only_missing_outputs: bool,
) -> dict[str, Any]:
    """Run the pipeline."""

    runner_obj = load_obj(runner or "SequentialRunner", "kedro.runner")
    runner_kwargs = _resolve_runner_kwargs(is_async, runner_params)
    tuple_tags = tuple(tags)
    tuple_node_names = tuple(node_names)

    with KedroSession.create(
        env=env, conf_source=conf_source, runtime_params=params
    ) as session:
        return session.run(
            tags=tuple_tags,
            runner=runner_obj(**runner_kwargs),
            node_names=tuple_node_names,
            from_nodes=from_nodes,
            to_nodes=to_nodes,
            from_inputs=from_inputs,
            to_outputs=to_outputs,
            load_versions=load_versions,
            pipeline_name=pipeline,
            namespaces=namespaces,
            only_missing_outputs=only_missing_outputs,
        )

把上述 cli.py 放入项目的 src/<python_package>/ 目录后，其中的 cli 组就会被合并进 kedro 命令树。需要注意：如果 cli.py 存在但其中没有名为 cli 的变量，CLI 会抛出 KedroCliError（见 cli.py）。

CLI 加载机制源码解读

理解 Kedro CLI 的加载机制，有助于正确设计自定义命令与插件。核心逻辑集中在 kedro/framework/cli/cli.py 的 KedroCLI 类中：

1. 项目检测：KedroCLI.__init__ 调用 is_kedro_project / find_kedro_project 检查当前目录是否为 Kedro 项目（依据 pyproject.toml），若是则通过 bootstrap_project 加载项目元数据。
2. 命令集合：KedroCLI 继承自自定义的 CommandCollection（见 utils.py），由"全局命令"与"项目专属命令"两部分组成。
3. 加载顺序与覆盖优先级：从 project_groups 属性的源码（cli.py）可以确认，命令合并顺序为：

内置命令 < 插件命令 < 项目自定义 cli.py

即后加载者覆盖先加载者：插件可以覆盖内置命令，项目自己的 cli.py 又可以覆盖插件命令。全局命令则按 内置命令 < 插件全局命令 的顺序合并（见 global_groups）。 4. 入口点（Entry Point）机制：插件通过 utils.py 中 ENTRY_POINT_GROUPS 定义的组注册命令——kedro.global_commands（全局命令）、kedro.project_commands（项目命令）、kedro.init（初始化钩子）、kedro.hooks（钩子）等，由 load_entry_points 加载。 5. 生命周期钩子：main() 方法会在命令执行前后触发 before_command_run 与 after_command_run CLI 钩子，方便插件做统一的横切处理。 6. 错误提示：当在非项目目录中尝试执行项目命令时，CommandCollection 会基于 resolve_command 捕获 No such command 异常并给出"Kedro project not found in this directory"的提示与查找 pyproject.toml 的建议（cli.py）；此外还会利用 _suggest_cli_command（基于 difflib 的近似匹配）对拼写错误的命令给出 "Did you mean" 建议。

总结

Kedro CLI 以"全局命令 + 项目命令"的双层结构覆盖了数据科学工作流的完整生命周期：kedro new 创建项目、kedro pipeline create 搭建模块化管道、kedro run 执行管道、kedro package 打包发布，配套的 catalog、registry、jupyter、ipython 与 server 命令则服务于数据目录诊断、管道检视、交互开发与 HTTP 化部署。而基于入口点与 cli.py 的扩展机制，让内置命令、插件命令与项目自定义命令形成了清晰的覆盖优先级，你可以在 docs/extend/plugins.md 中进一步了解插件开发细节。如需在终端中查看每个命令的最新帮助，直接运行 kedro <command> --help 即可。