> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bizyair.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 命令行工具

> 用于管理 BizyAir 上模型文件的命令行工具

## 简介

BizyAir CLI 是用于管理 BizyAir 上模型文件的命令行工具。它提供了 **交互式界面(TUI)** 和 **命令行(CLI)** 两种使用模式,让您可以轻松上传和管理 BizyAir 模型。

| 模式      | 适用场景           |
| ------- | -------------- |
| TUI 交互式 | 新手或不熟悉命令行参数的用户 |
| CLI 命令行 | 脚本化、CI/CD、批量操作 |

***

## 发布版本

所有发布版本请 [点击这里查看](https://github.com/siliconflow/bizyair-cli/releases)。

***

## 安装

### 下载

BizyAir CLI 支持 Linux、macOS 和 Windows 平台。所有平台的二进制文件都可以从以下位置下载:

1. [bizyair.ai 个人中心 -> 发布模型界面](https://bizyair.ai/publish/model)
2. [GitHub Release 页面](https://github.com/siliconflow/bizyair-cli/releases)

### Linux 安装

**下载**

```bash theme={null}
# 设置版本号(请替换为最新版本)
VERSION=0.2.8

# 下载 Linux amd64 版本
wget https://github.com/siliconflow/bizyair-cli/releases/download/v${VERSION}/bizyair-v${VERSION}-linux-amd64.tar.gz

# 或下载 Linux arm64 版本
# wget https://github.com/siliconflow/bizyair-cli/releases/download/v${VERSION}/bizyair-v${VERSION}-linux-arm64.tar.gz
```

**解压并安装**

```bash theme={null}
# 解压文件
tar -xzvf bizyair-v${VERSION}-linux-amd64.tar.gz

# 安装到系统路径
sudo install bizyair /usr/local/bin/bizyair

# 或者安装到用户目录(无需 sudo)
# mkdir -p ~/.local/bin
# install bizyair ~/.local/bin/bizyair
# 确保 ~/.local/bin 在您的 PATH 中
```

**验证安装**

```bash theme={null}
bizyair --version
```

### macOS 安装

**下载**

```bash theme={null}
# 设置版本号(请替换为最新版本)
VERSION=0.2.8

# 下载 macOS arm64 版本(Apple Silicon,如 M1/M2/M3)
curl -LO https://github.com/siliconflow/bizyair-cli/releases/download/v${VERSION}/bizyair-v${VERSION}-macos-arm64.tar.gz

# 或下载 macOS amd64 版本(Intel 芯片)
# curl -LO https://github.com/siliconflow/bizyair-cli/releases/download/v${VERSION}/bizyair-v${VERSION}-macos-amd64.tar.gz
```

**解压并安装**

```bash theme={null}
# 解压文件
tar -xzvf bizyair-v${VERSION}-macos-arm64.tar.gz

# 添加执行权限
chmod +x bizyair

# 安装到系统路径
sudo install bizyair /usr/local/bin/bizyair

# 或者安装到用户目录(无需 sudo)
# mkdir -p ~/.local/bin
# install bizyair ~/.local/bin/bizyair
# 确保 ~/.local/bin 在您的 PATH 中
```

**macOS 安全提示处理**

首次运行时,macOS 可能会提示安全警告。

```bash theme={null}
# 移除隔离属性
sudo xattr -d com.apple.quarantine /usr/local/bin/bizyair
```

或者在系统设置中允许运行:

* 打开 **系统设置** → **隐私与安全性**
* 找到被阻止的 `bizyair` 并点击 **仍要打开**

**验证安装**

```bash theme={null}
bizyair --version
```

### Windows 安装

* 从 [Release 页面](https://github.com/siliconflow/bizyair-cli/releases) 下载最新版本
* 下载 `bizyair-v{VERSION}-windows-amd64.zip` 文件

**解压文件**

* 右键点击下载的 `.zip` 文件
* 选择 **解压全部** 或使用解压工具(如 7-Zip)
* 将 `bizyair.exe` 解压到您选择的目录(例如 `C:\Program Files\BizyAir\`)

**添加到系统 PATH(推荐)**

* 右键点击 **此电脑** → **属性** → **高级系统设置**
* 点击 **环境变量**
* 在 **系统变量** 中找到 `Path`,点击 **编辑**
* 点击 **新建**,添加 `bizyair.exe` 所在的目录路径
* 点击 **确定** 保存

**验证安装**(打开 **命令提示符** 或 **PowerShell**)

```powershell theme={null}
bizyair --version
```

> 💡 如果没有添加到 PATH,可以使用完整路径运行: `C:\Program Files\BizyAir\bizyair.exe --version`

***

## 从源码构建

BizyAir CLI 当前使用 Go v1.22.x 或更高版本。要从源码构建,您需要:

* 克隆仓库
* 构建并运行可执行文件

```bash theme={null}
make build && ./execs/bizyair
```

**不同平台的构建命令:**

| 平台            | 命令                       |
| ------------- | ------------------------ |
| Windows       | `make build_windows`     |
| macOS         | `make build_mac`         |
| Linux (amd64) | `make build_linux`       |
| Linux (arm64) | `make build_linux_arm64` |

***

## 升级到最新版本

BizyAir CLI 支持一键升级到最新版本:

```bash theme={null}
# 检查更新
bizyair upgrade --check

# 执行升级
sudo bizyair upgrade
```

***

## 快速开始

### 使用交互式界面(推荐)

**启动 TUI**

```bash theme={null}
bizyair
```

**首次使用需要登录**

* 输入您的 API Key(从 [BizyAir](https://bizyair.ai) 获取)
* 按 Enter 确认

**选择功能**

| 菜单项  | 说明            |
| ---- | ------------- |
| 上传模型 | 交互式收集参数并上传    |
| 我的模型 | 在浏览器中查看已上传的模型 |
| 退出登录 | 清除本地 API Key  |
| 退出程序 | 退出 CLI        |

**上传模型**

* 按照界面提示逐步输入信息
* 支持文件选择器或手动输入路径
* 支持多版本上传
* 自动显示上传进度和速率

### 使用命令行

#### 登录

BizyAir CLI 使用 API Key 进行身份验证。要登录您的设备,运行以下命令:

```bash theme={null}
# 如果您已设置环境变量 BIZYAIR_API_KEY
bizyair login

# 或使用 --key/-k 选项指定
bizyair login -k $BIZYAIR_API_KEY
```

#### 上传模型

**单版本上传示例:**

```bash theme={null}
bizyair upload -n mymodel -t LoRA \
  -p /local/path/model.safetensors \
  -b "Flux.1 D" \
  -cover "/path/to/cover.jpg" \
  --intro "这是一个动漫风格的 LoRA 模型"
```

**多版本上传示例:**

```bash theme={null}
bizyair upload -n mymodel -t Checkpoint \
  -v "v1.0" -p /path/file1.safetensors -b SDXL --intro "第一版" -cover "/path/cover1.jpg" \
  -v "v2.0" -p /path/file2.safetensors -b "SD 1.5" --intro "第二版" -cover "/path/cover2.jpg"
```

**核心参数说明:**

| 参数              | 说明                                      |
| --------------- | --------------------------------------- |
| `-n, --name`    | 模型名称(必填)                                |
| `-t, --type`    | 模型类型(必填,如 LoRA、Checkpoint、Controlnet 等) |
| `-p, --path`    | 模型文件路径(必填,可多次指定)                        |
| `-b, --base`    | 基础模型(必填,如 "Flux.1 D"、SDXL、"SD 1.5" 等)   |
| `-cover`        | 封面文件或 URL(必填)                           |
| `-i, --intro`   | 模型介绍文本(必填)                              |
| `--intro-path`  | 从文件导入介绍(与 `-i` 二选一)                     |
| `-v, --version` | 版本名称(可选,默认 v1.0)                        |
| `--public`      | 是否公开版本(可选,默认 false)                     |

#### 封面上传(必填)

封面支持 **本地文件** 和 **URL** 两种方式,会自动上传到 OSS 并转换为 WebP 格式:

```bash theme={null}
# 使用本地文件
bizyair upload -n mymodel -t LoRA -p model.safetensors -b "Flux.1 D" \
  -cover "/path/to/cover.jpg" --intro "介绍文本"

# 使用 URL
bizyair upload -n mymodel -t LoRA -p model.safetensors -b "Flux.1 D" \
  -cover "https://example.com/cover.jpg" --intro "介绍文本"
```

**支持的格式:**

| 类型 | 扩展名                                  |
| -- | ------------------------------------ |
| 图片 | `.jpg` `.jpeg` `.png` `.gif` `.webp` |
| 视频 | `.mp4` `.webm` `.mov`(最大 100 MB)     |

> 💡 **WebP 转换**：图片封面会自动转换为 WebP 格式以优化加载速度。如果转换失败,会自动回退到原始格式。

#### 介绍文本输入

支持两种方式输入模型介绍(最多 5,000 字):

```bash theme={null}
# 直接输入文本
bizyair upload -n mymodel -t LoRA -p model.safetensors -b "Flux.1 D" \
  -cover cover.jpg --intro "这是模型的详细介绍..."

# 从文件导入(支持 .txt 和 .md)
bizyair upload -n mymodel -t LoRA -p model.safetensors -b "Flux.1 D" \
  -cover cover.jpg --intro-path intro.md
```

#### YAML 批量上传

使用 YAML 配置文件可以一次上传多个模型:

```bash theme={null}
bizyair upload -f config.yaml
```

详细配置说明请参考 [example.yaml](https://github.com/siliconflow/bizyair-cli/blob/main/example.yaml)。

**YAML 配置示例:**

```yaml theme={null}
models:
  - name: "anime_style_lora"
    type: "LoRA"
    versions:
      - name: "v1.0"
        base_model: "Flux.1 D"
        model_path: "models/anime_v1.safetensors"
        cover_path: "covers/anime_v1.jpg"
        intro: "第一版动漫风格模型"
        public: true

      - name: "v2.0"
        base_model: "Flux.1 D"
        model_path: "models/anime_v2.safetensors"
        cover_url: "https://example.com/cover.jpg"
        intro_path: "descriptions/v2_intro.txt"
        public: false

  - name: "realistic_checkpoint"
    type: "Checkpoint"
    versions:
      - base_model: "SD 1.5"
        model_path: "checkpoints/realistic.ckpt"
        cover_path: "covers/realistic.webp"
        intro_path: "descriptions/realistic.md"
```

**YAML 字段说明:**

| 字段                         | 说明                  |
| -------------------------- | ------------------- |
| `model_path`               | 模型文件路径(相对于 YAML 文件) |
| `cover_path` / `cover_url` | 封面文件或 URL(二选一)      |
| `intro` / `intro_path`     | 介绍文本或文件(二选一)        |
| `name`                     | 版本名称(可选,自动递增)       |
| `public`                   | 是否公开(可选,默认 false)   |

#### 断点续传

同一模型文件上传中断后,重新运行相同命令会自动从断点继续:

```bash theme={null}
# 第一次上传(中断)
bizyair upload -n mymodel -t Checkpoint -p large-model.safetensors -b SDXL \
  -cover cover.jpg --intro "介绍"
# ^C (中断)

# 重新运行相同命令,自动续传
bizyair upload -n mymodel -t Checkpoint -p large-model.safetensors -b SDXL \
  -cover cover.jpg --intro "介绍"
# ✓ 从断点继续上传
```

> 💡 断点续传的 checkpoint 文件保存在 `~/.bizyair/uploads/` 目录。

#### 查看模型

```bash theme={null}
# 查看我的模型(在浏览器中打开)
bizyair model ls
```

#### 退出登录

```bash theme={null}
bizyair logout
```

***

## 命令参考

**完整命令速查表:**

| 命令                         | 用途                          |
| -------------------------- | --------------------------- |
| `bizyair`                  | 启动交互式界面                     |
| `bizyair --version`        | 查看版本                        |
| `bizyair login`            | 使用环境变量 `BIZYAIR_API_KEY` 登录 |
| `bizyair login -k <KEY>`   | 用指定 Key 登录                  |
| `bizyair logout`           | 退出登录并清除本地凭据                 |
| `bizyair upload [flags]`   | 上传模型                        |
| `bizyair upload -f <file>` | 通过 YAML 批量上传                |
| `bizyair model ls`         | 查看我的模型(浏览器)                 |
| `bizyair upgrade --check`  | 检查更新                        |
| `bizyair upgrade`          | 执行升级                        |