CLI 命令参考
约 711 字大约 2 分钟
2026-03-19
ncatbot命令行工具完整 API 参考。基于 Click 构建。
Quick Start
ncatbot --help # 查看所有命令
ncatbot <command> --help # 查看单个命令帮助入口点
# pyproject.toml
[project.scripts]
ncatbot = "ncatbot.cli:main"也可通过模块方式调用:
python -m ncatbot.cli顶层命令
ncatbot [OPTIONS] [COMMAND]| 选项 | 说明 |
|---|---|
--version | 显示版本号 |
--help | 显示帮助信息 |
无子命令时进入交互模式(REPL)。
init
ncatbot init [OPTIONS]初始化项目,创建 config.yaml、plugins/ 目录,以及一个以当前计算机用户名命名的模板插件。
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--dir | str | . | 目标目录 |
交互式提示:
| 提示 | 说明 |
|---|---|
| 请输入机器人 QQ 号 | 写入 bot_uin |
| 请输入管理员 QQ 号 | 写入 root |
若 config.yaml 已存在,提示是否覆盖。
生成的模板插件位于 plugins/{username}/,包含 manifest.toml 和 plugin.py,实现群聊/私聊发送 hello 回复 hi。若模板插件目录已存在则跳过。
run
ncatbot run [OPTIONS]启动 NcatBot(连接 NapCat + 加载插件 + 监听事件)。
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--debug | flag | False | 启用调试模式 |
--no-hot-reload | flag | False | 禁用插件热重载 |
--plugin-dir | str | plugins | 插件目录路径 |
dev
ncatbot dev [OPTIONS]以开发模式启动(debug=True + 热重载)。
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--plugin-dir | str | plugins | 插件目录路径 |
config
ncatbot config COMMAND配置管理命令组。
config show
ncatbot config show以 YAML 格式显示当前全部配置。
config get
ncatbot config get CONFIG_KEY| 参数 | 类型 | 说明 |
|---|---|---|
CONFIG_KEY | str | 配置项路径,支持点分(如 napcat.ws_uri) |
config set
ncatbot config set CONFIG_KEY CONFIG_VALUE| 参数 | 类型 | 说明 |
|---|---|---|
CONFIG_KEY | str | 配置项路径,支持点分 |
CONFIG_VALUE | str | 值(自动类型转换) |
类型转换规则:
| 输入值 | 转换类型 |
|---|---|
true / yes | bool (True) |
false / no | bool (False) |
| 纯数字字符串 | int |
[...] JSON 格式 | list |
| 其它 | str |
config check
ncatbot config check检查配置安全性和必填项,输出问题列表。
plugin
ncatbot plugin COMMAND插件管理命令组。
plugin list
ncatbot plugin list列出已安装插件,显示名称、版本、作者、状态。读取每个插件目录下的 manifest.toml。
plugin create
ncatbot plugin create NAME| 参数 | 类型 | 说明 |
|---|---|---|
NAME | str | 插件名(字母开头,仅字母/数字/下划线) |
在插件目录下生成标准脚手架,包含 __init__.py、manifest.toml、plugin.py、README.md。
plugin info
ncatbot plugin info NAME| 参数 | 类型 | 说明 |
|---|---|---|
NAME | str | 插件名 |
显示插件 manifest.toml 元数据。
plugin enable
ncatbot plugin enable NAME启用插件:从黑名单移除,若白名单存在则加入白名单。
plugin disable
ncatbot plugin disable NAME禁用插件:从白名单移除,加入黑名单。
plugin remove
ncatbot plugin remove NAME| 参数 | 类型 | 说明 |
|---|---|---|
NAME | str | 插件名 |
删除插件目录(含所有文件),并从黑名单/白名单中移除。
版权所有
版权归属:huan-yp
