cli.md

CLI命令说明

magic-dash命令是项目脚手架的主要入口，用于查看内置模板、创建模板项目和确认当前安装版本。

安装与更新

pip install magic-dash -U

全局命令

查看版本

magic-dash --version

查看帮助

magic-dash --help

查看子命令帮助：

magic-dash list --help
magic-dash create --help

magic-dash list

列出当前可直接创建的全部内置模板：

magic-dash list

当前顶层模板为：

模板	说明
magic-dash	适用于多页面、持续扩展的应用模板
magic-dash-pro	适用于多页面、持续扩展的管理型应用模板，支持复杂用户与部门关系、用户登录、管理和鉴权能力
simple-tool	单页面工具应用模板

magic-dash-pro-fastapi是magic-dash-pro的内部FastAPI后端变体，不会出现在顶层模板列表中，也不能通过--name magic-dash-pro-fastapi直接创建。

magic-dash create

创建指定模板项目：

magic-dash create [OPTIONS]

可用选项：

选项	简写	默认值	说明
--name	-n	无	Dash应用项目模板名称；可选simple-tool、magic-dash、magic-dash-pro
--path	-p	"."	项目生成目标父目录
--backend	-b	交互选择	后端类型；可选flask、fastapi

长参数和简写参数完全等价，例如--name可写作-n，--path可写作-p，--backend可写作-b。

交互式创建

不传入--name时，命令会进入模板选择菜单：

magic-dash create

选择模板后，命令会继续提示选择后端类型并输入项目名称。如果目标父目录下已存在同名文件夹，会要求重新输入项目名称，避免覆盖已有项目。

指定模板创建

magic-dash create --name simple-tool
magic-dash create --name magic-dash
magic-dash create --name magic-dash-pro

指定生成父目录和后端类型：

magic-dash create --name simple-tool --backend flask --path ./workspace
magic-dash create --name magic-dash --backend fastapi --path ./workspace
magic-dash create --name magic-dash-pro --backend fastapi --path ./workspace

也可以使用简写参数：

magic-dash create -n simple-tool -b flask -p ./workspace
magic-dash create -n magic-dash -b fastapi -p ./workspace
magic-dash create -n magic-dash-pro -b fastapi -p ./workspace

如果项目名称为demo-app，最终生成路径为：

./workspace/demo-app

后端选择

创建simple-tool、magic-dash或magic-dash-pro时，命令会提示选择后端类型：

选项	说明
Flask	默认后端
FastAPI	可选后端

示例：

magic-dash create --name simple-tool --backend fastapi
magic-dash create --name magic-dash --backend fastapi
magic-dash create --name magic-dash-pro --backend fastapi

等价的简写形式：

magic-dash create -n simple-tool -b fastapi
magic-dash create -n magic-dash -b fastapi
magic-dash create -n magic-dash-pro -b fastapi

simple-tool和magic-dash选择FastAPI后端时，会在复制原始模板后轻量改写生成结果：requirements.txt会切换到dash[fastapi]并补充fastapi、uvicorn依赖，dash.Dash()实例会添加backend="fastapi"。magic-dash中的浏览器版本检查也会从Flask before_request改写为FastAPI middleware。

magic-dash-pro选择FastAPI后端时，仍使用内部维护的magic-dash-pro-fastapi模板变体，以适配登录、鉴权和权限管理等复杂差异。

生成后的启动提示

项目生成成功后，命令会提示进入目录、安装依赖并启动应用：

cd 项目名称
pip install -r requirements.txt
python app.py

如果创建的是magic-dash-pro，还需要先初始化数据库和默认管理员账号：

python -m magic_init
python app.py

默认管理员账号：

用户名：admin
初始密码：admin123

错误处理

模板名称不存在

magic-dash create --name unknown-template

命令会报错，并列出可用模板名称。

直接创建FastAPI内部变体

magic-dash create --name magic-dash-pro-fastapi

该命令无效。请使用magic-dash create --name magic-dash-pro --backend fastapi，或使用magic-dash create --name magic-dash-pro后在后端类型菜单中选择FastAPI。

项目文件夹已存在

如果目标父目录下已经存在同名文件夹，命令不会覆盖旧目录，而是提示重新输入项目名称。

取消交互

在模板选择或后端选择过程中取消操作，命令会停止生成，不写入项目文件。