---
name: "ulthon-admin-menu-cli"
description: "解释并指导后台菜单（system_menu）与 admin:menu:* 命令的使用方式。需要导出菜单、通过命令行创建/更新/删除菜单、或排查菜单字段映射（pid/href/auth_node）时调用。"
---

# 菜单管理（admin:menu:* CLI）

## 何时调用

- 需要导出当前系统菜单数据，用于备份/迁移/对比。
- 需要在不进入后台页面的情况下，通过命令行创建/更新/删除菜单。
- 需要排查菜单字段映射：`pid`/`href`/`auth_node` 与命令参数 `parent-id`/`path`/`node` 的对应关系。
- 需要脚本化输出（JSON）对接自动化运维/测试（仅导出命令支持）。

## 命令清单

### 1) 导出菜单

```bash
php think admin:menu:export
```

常用参数：
- `--format=json`：JSON 输出（含 count/exported_at）
- `--output=<文件路径>`：把导出的菜单数组写入文件（JSON）

示例：

```bash
php think admin:menu:export --format=json
php think admin:menu:export --output=runtime/agent/menu_export.json
php think admin:menu:export --output=runtime/agent/menu_export.json --format=json
```

### 2) 创建菜单（会写入数据库）

```bash
php think admin:menu:create --title="测试菜单" --path="demo.index/index" --icon="fa fa-list" --parent-id=0 --sort=100
```

### 3) 更新菜单（会写入数据库）

```bash
php think admin:menu:update --id=123 --title="新标题" --path="demo.index/index" --icon="fa fa-list" --parent-id=0 --sort=100
```

说明：
- `--id` 必填；其余参数不传则不更新该字段。
- `--path` 更新的是数据库字段 `href`。
- `--parent-id` 更新的是数据库字段 `pid`。

### 4) 删除菜单（会写入数据库，软删除）

```bash
php think admin:menu:delete --id=123
```

说明：
- 若存在子菜单会拒绝删除（需先删除子菜单）。

## 字段映射速查

- `--parent-id` → `system_menu.pid`
- `--path` → `system_menu.href`
- `--node` → `system_menu.auth_node`

## 典型工作流

### 工作流 A：备份菜单到文件

```bash
php think admin:menu:export --output=runtime/agent/menu_export.json
```

### 工作流 B：创建 → 更新 → 删除（用于验证命令链路）

```bash
php think admin:menu:create --title="CLI测试菜单" --path="test.cli/index" --parent-id=0
php think admin:menu:update --id=<上一步返回的id> --title="CLI测试菜单_改"
php think admin:menu:delete --id=<上一步返回的id>
```

## 注意事项

- `create/update/delete` 会实际修改数据库，建议在测试环境或确认无风险后执行。
- 导出默认过滤 `delete_time=0`（只导出未删除菜单）。