# 安装百积木 CLI

通过百积木客户端安装 baijimu CLI，完成首次登录、版本检查和工作区验证。

`baijimu` CLI 是在本机访问百积木工作区、项目 Git、Bundle、运行时和托管服务的
标准命令行入口。CLI 安装与具体的前端、后端或 Bundle 开发流程相互独立；安装一次后，
可以在多个项目和外部 Agent 中复用。

## 官方安装方式

百积木客户端安装包会同时安装 `baijimu` CLI。请从
[百积木客户端](/local-client/)进入官方下载流程，并选择与当前操作系统及 CPU
架构匹配的安装包：

| 操作系统    | 安装包                            |
| ------- | ------------------------------ |
| Windows | `.msi`                         |
| macOS   | `.dmg`；Apple 芯片优先选择 Apple 芯片版本 |
| Linux   | `.deb` 或 `.AppImage`           |

安装完成后启动百积木客户端，并按客户端提示登录、授权当前设备。不要从未知网站下载
`baijimu` 可执行文件，也不要用 `cargo install`、复制其他设备的二进制或复制他人的
认证文件代替官方安装。

> **CLI 与客户端的关系**
>
> 客户端负责设备连接和本地 Connector，CLI 负责命令行操作。二者随同一个官方安装包
> 交付，但用途不同；只需要命令行能力时，也应通过官方安装包装好 CLI。

## 验证命令是否可用

安装完成后关闭并重新打开终端，让终端重新加载 `PATH`，然后执行：

```bash
baijimu --version
baijimu --help
```

第一条命令应输出版本号，第二条命令应显示顶层命令组。需要确认某项能力时，继续运行
`baijimu <command> --help`，只读取与当前任务有关的子命令。

macOS 或 Linux 可以用下面的命令检查终端实际找到的程序：

```bash
command -v baijimu
```

Windows PowerShell 使用：

```powershell
Get-Command baijimu
```

如果客户端已经安装，但终端仍提示找不到 `baijimu`，先完全退出并重新打开终端和外部
Agent。仍然失败时，检查当前进程的 `PATH` 是否包含客户端安装器写入的 CLI 目录；不要
自行移动可执行文件，也不要用另一个来源的同名程序覆盖它。

## 首次登录

在终端执行：

```bash
baijimu auth login
```

CLI 会发起设备授权，并提示在浏览器中完成登录和批准。授权结束后验证真实登录状态：

```bash
baijimu auth status --verify
```

不要把 token、API Key、cookie 或本机认证文件内容粘贴到终端脚本、Git Remote URL、
代码仓库或 Agent 对话中。

## 选择默认工作区

登录成功后列出有权访问的工作区：

```bash
baijimu workspace list
```

确认准确的工作区 ID 后，将它设为本机默认工作区：

```bash
baijimu workspace use <workspaceId>
baijimu workspace current
```

设置默认工作区后，支持该行为的命令可以省略 `workspaceId`。执行写入、构建或发布前，
仍应回查当前工作区，避免把操作写入错误环境。

## 安装验收

满足以下条件才算安装完成：

1. 新终端能找到 `baijimu`。
2. `baijimu --version` 返回明确版本号。
3. `baijimu --help` 和目标命令的分级 `--help` 正常返回。
4. `baijimu auth status --verify` 确认服务端登录有效。
5. `baijimu workspace current` 显示预期工作区。

完成安装后，命令参数和能力发现方式见[百积木 CLI 文档](/cli/)。