# itbox-cli

**Repository Path**: jianlidmeng/itbox-cli

## Basic Information

- **Project Name**: itbox-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-29
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @itbox/cli

前端项目模板生成工具，支持Vue、Vue+TypeScript、Nuxt、Nest等多种模板，可从Gitee动态拉取模板分支。

## 功能特性

- ✅ 支持从Gitee仓库动态获取模板分支
- ✅ 支持npm/pnpm包管理器选择
- ✅ 交互式终端操作（方向键切换，空格选择）
- ✅ 配置管理功能（支持设置模板仓库地址）
- ✅ 列出所有可用模板功能
- ✅ ES模块模式开发
- ✅ 支持 `pnpm create itbox` 调用方式

## 安装

### 全局安装

```bash
# 使用 npm
npm install -g @itbox/cli

# 使用 pnpm
pnpm add -g @itbox/cli
```

### 直接使用

```bash
# 使用 npm create
npm create itbox <项目名>

# 使用 pnpm create
pnpm create itbox <项目名>
```

## 使用方法

### 创建项目

```bash
# 使用命令创建项目
itbox create <项目名>

# 示例
itbox create my-vue3-app
```

执行后会进入交互式选择界面：
1. 选择项目模板（从Gitee仓库动态获取的分支）
2. 选择包管理器（npm或pnpm）

### 列出所有可用模板

```bash
itbox list
```

### 配置管理

```bash
# 设置模板仓库地址
itbox config set templateRepo <仓库地址>

# 获取当前模板仓库地址
itbox config get templateRepo

# 删除模板仓库配置
itbox config delete templateRepo

# 查看配置帮助
itbox config help
```

## 命令详解

### `itbox create <projectName>`

创建新的前端项目，从指定Gitee仓库拉取模板。

**参数：**
- `projectName`: 项目名称，将作为新创建的项目目录名

**功能流程：**
1. 检查Git是否安装
2. 获取远程仓库分支列表作为模板选项
3. 交互式选择模板和包管理器
4. 检查包管理器是否安装
5. 使用git clone命令下载模板
6. 安装项目依赖

### `itbox list`

列出所有可用的项目模板（即远程仓库的分支列表）。

**功能流程：**
1. 检查Git是否安装
2. 获取远程仓库分支列表
3. 格式化输出模板列表

### `itbox config`

管理CLI工具的配置项。

**子命令：**
- `set <key> <value>`: 设置配置项
- `get <key>`: 获取配置项值
- `delete <key>`: 删除配置项
- `help`: 显示配置命令帮助

**配置文件位置：**
`~/.fe-cli/config.json`

**可配置项：**
- `templateRepo`: 模板仓库地址（默认：https://gitee.com/jianlidmeng/template.git）

## 实现逻辑

### 技术栈

- **Node.js**: 运行环境
- **Commander.js**: 命令行界面构建
- **Inquirer.js**: 交互式终端实现
- **Git**: 模板下载和分支获取
- **fs-extra**: 文件系统操作
- **ora**: 终端加载动画

### 核心实现

1. **动态模板获取**
   - 使用 `git ls-remote --heads` 命令获取远程仓库分支列表
   - 分支名称作为模板选项供用户选择

2. **模板下载**
   - 使用 `git clone -b <branch> <repo> <projectName>` 命令直接克隆指定分支
   - 替代了传统的 `download-git-repo` 库，解决了Gitee兼容性问题

3. **交互式选择**
   - 使用 Inquirer.js 的 checkbox 类型实现单选限制
   - 通过 validate 函数确保只能选择一个模板和一个包管理器
   - 支持方向键切换、空格选择、回车确认

4. **配置管理**
   - 配置文件存储在用户主目录下的 `.fe-cli/config.json`
   - 实现了完整的配置读写功能
   - 支持多个配置项的管理

5. **模块化设计**
   - 使用 ES 模块模式开发（package.json 中设置 `"type": "module"`）
   - 功能模块化，便于维护和扩展

### 项目结构

```
@itbox/cli/
├── bin/
│   └── index.js          # CLI入口文件
├── package.json          # 项目配置文件
└── README.md             # 项目文档
```

## 注意事项

1. **Git安装**：使用前请确保已安装Git
2. **包管理器**：根据选择的包管理器确保已安装
3. **网络连接**：需要网络连接以获取模板列表和下载模板
4. **仓库权限**：确保Gitee仓库是公开的，或已登录Git账号

## 故障排除

### 1. Git命令失败

**错误信息**：`git clone failed with status 128`

**解决方案**：
- 检查Git是否正确安装：`git --version`
- 检查网络连接是否正常
- 确保Gitee仓库是公开的或已正确配置Git凭证

### 2. 模板列表获取失败

**错误信息**：`403 Forbidden`

**解决方案**：
- 检查Git是否已登录Gitee账号
- 确保仓库具有公开访问权限
- 尝试重新配置模板仓库地址

### 3. 包管理器命令失败

**错误信息**：`Command not found`

**解决方案**：
- 安装选择的包管理器：`npm install -g npm` 或 `npm install -g pnpm`
- 检查包管理器是否在系统PATH中

## License

MIT