# CLI 概述

`ml-cli` 是 MoreLogin 本地 `httpServer` 的命令行界面。它将 CLI 参数转换为 HTTP 请求，并将它们转发到 MoreLogin 客户端公开的本地 API。

## 概述

**它适合谁？**
DevOps 工程师、QA 自动化工程师以及喜欢在终端中工作或需要将 MoreLogin 集成到 CI/CD 管道（例如 GitHub Actions、Jenkins 或 shell 脚本）中的开发人员。

**它能做什么？**

- 直接从终端调用MoreLogin本地API，无需编写HTTP请求代码。
- 从一个统一的界面管理浏览器环境、代理、云手机和日程安排。
- 使用稳定的 CLI 标志而不是手动构建 JSON 有效负载。


**如何开始？**

1. 阅读下面的**先决条件**。
2. 下载并安装适合您平台的 CLI。
3. 检查[快速启动](/zh/cli/quick-start) 以运行您的第一个命令。


## 先决条件

在使用 `ml-cli` 之前，请确保满足以下要求：

- **MoreLogin 桌面客户端** 在同一台计算机上安装并运行
- 您有一个活跃的 MoreLogin 帐户，具有 **API 凭证**（API ID + API 密钥）


## 下载&安装

下载适合您平台的最新 `ml-cli` 二进制文件：

| 平台 | 架构 | 链接 |
|  --- | --- | --- |
| Windows | x64 | [下载](https://get.morelogin.com/client/prod/win/x64/2.6.1/ml-cli.exe) |
| macOS | x64（Intel） | [下载](https://get.morelogin.com/client/prod/mac/x64/2.6.1/ml-cli) |
| macOS | arm64（Apple Silicon） | [下载](https://get.morelogin.com/client/prod/mac/arm64/2.6.1/ml-cli) |
| Linux | x64 | [下载](https://get.morelogin.com/client/prod/linux/x64/2.6.1/ml-cli) |


### Windows

1. 为 CLI 创建一个目录，例如 `C:\Program Files\MoreLogin\`：

```powershell
New-Item -ItemType Directory -Force -Path "C:\Program Files\MoreLogin"
```
2. 将下载的 `ml-cli.exe` 移动到该目录中。
3. 将目录添加到您的系统 `PATH`：

```powershell
# Add to the current user's PATH permanently
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$currentPath;C:\Program Files\MoreLogin", "User")
```
4. **重新启动终端**（或打开一个新终端）以使更改生效。
5. 核实：

```powershell
ml-cli --version
```


### macOS

1. 使二进制可执行文件：

```bash
chmod +x ml-cli
```
2. 将其移至 `PATH` 中的目录：

```bash
sudo mv ml-cli /usr/local/bin/
```
> 如果 `/usr/local/bin` 不存在，请先创建：`sudo mkdir -p /usr/local/bin`
3. 在 macOS 上，下载的二进制文件可能会被 Gatekeeper 阻止。删除隔离属性：

```bash
xattr -d com.apple.quarantine /usr/local/bin/ml-cli
```
4. 验证：

```bash
ml-cli --version
```


### Linux

1. 使二进制可执行文件：

```bash
chmod +x ml-cli
```
2. 将其移至 `PATH` 中的目录：

```bash
sudo mv ml-cli /usr/local/bin/
```
3. 验证：

```bash
ml-cli --version
```


安装后，请参阅[快速入门](/zh/cli/quick-start) 连接到 MoreLogin 客户端并运行第一个命令。

## 核心能力

当前的 CLI 涵盖以下资源组：

- 服务状态和登录
- 通过 `env` 进行浏览器环境管理
- 通过 `cloudphone` 进行云手机管理
- 通过 `group` 进行分组管理
- 通过 `tag` 进行标签管理
- 通过 `proxy` 进行代理管理
- 通过 `schedule` 进行云手机日程管理


## 请求模型

CLI 支持两种输入方式：

- 显式标志，例如 `--env-id` 或 `--group-name`
- 通过 `--json-data` 的原始 JSON


它们可以组合起来。合并规则为：

- `--json-data` 提供基本请求正文
- 显式 CLI 标志覆盖来自 `--json-data` 的匹配键


这对于具有许多字段或嵌套有效负载的端点非常有用，因为专用标志太重。

## 退出代码

| 代码 | 含义 |
|  --- | --- |
| `0` | HTTP 请求已完成并收到响应。检查 JSON 正文以确定业务成功或失败。 |
| `1` | 本地 CLI 验证失败，或者当前平台不支持该命令。 |
| `2` | 端口解析失败、JSON解析失败或无法发送请求。 |


## 端口解析和故障排除

CLI 需要找到本地 `httpServer` 端口来发送请求。它按以下顺序检查：

1. `--port` 标志 — 在每次调用时显式传递端口
2. `ML_PORT` 环境变量 — 每个会话设置一次
3. IPC 自动发现 — CLI 从本地 IPC 管道读取端口（无需配置）


默认IPC路径：

| 平台 | 路径 |
|  --- | --- |
| macOS/Linux | `/tmp/MoreLogin-cli` |
| Windows | `\\.\pipe\MoreLogin-cli` |


如果您看到错误**“无法检测 MoreLogin 端口”**，请检查：

- MoreLogin桌面客户端是否正在运行？
- 如果使用 `--port`，端口号是否正确？
- 在 Linux / macOS 上，`/tmp/MoreLogin-cli` 是否存在？


## 文档地图

- [快速入门](/zh/cli/quick-start)
- [命令](/zh/cli/commands)