# 快速入门

此快速入门假定您已经安装了 `ml-cli`（请参阅[下载和安装](/zh/cli#download--installation)）并且 MoreLogin 客户端正在本地运行。

## 1. 检查服务

确认本地 `httpServer` 可达：

```bash
ml-cli status
```

如果 MoreLogin 未运行，CLI 将在端口解析期间失败。

## 2. 认证

如果端点需要认证，请先登录：

```bash
ml-cli login --api-id your-api-id --api-key your-api-key
```

您还可以通过环境变量提供令牌：

```bash
export ML_API_KEY=your-token
ml-cli env list
```

## 3. 列出浏览器

列出浏览器环境：

```bash
ml-cli env list
ml-cli env list --page-no 1 --page-size 20
ml-cli env list --env-name test
```

## 4. 启动浏览器

您可以通过 `id`、`envId` 或 `uniqueId/sn` 启动环境：

```bash
ml-cli env start --id 1001
ml-cli env start --env-id 1868548141708648448
ml-cli env start --unique-id SN001
```

## 5. 创建并分配代理

首先创建一个代理：

```bash
ml-cli proxy create \
  --proxy-name local-http \
  --proxy-ip 127.0.0.1 \
  --proxy-port 7890 \
  --proxy-type 0 \
  --proxy-provider 0
```

然后将其分配给环境：

```bash
ml-cli env set-proxy \
  --env-ids 1001 \
  --proxy-ip 127.0.0.1 \
  --proxy-port 7890 \
  --proxy-type 0 \
  --proxy-provider 0 \
  --proxy-name local-http
```

## 6. 使用云手机

列出云手机：

```bash
ml-cli cloudphone list
```

创建云手机：

```bash
ml-cli cloudphone create --sku-id 10004 --quantity 1
```

获取详细信息：

```bash
ml-cli cloudphone info --id 123456
```

## 7. 查询时间表

列出计划模板和任务：

```bash
ml-cli schedule template-market --page-no 1 --page-size 20
ml-cli schedule list --page-no 1 --page-size 20
```

创建一次性任务：

```bash
ml-cli schedule create-once-task \
  --cloud-phone-id 123456 \
  --schedule-name once-task-demo \
  --template-id 888 \
  --template-parameter '{}'
```

## 8. 使用 `--json-data`

对于具有许多字段的端点，传递原始 JSON 通常更快：

```bash
ml-cli env create-advanced \
  --json-data '{"browserTypeId":1,"operatorSystemId":1,"envName":"cli-adv-test"}'
```

CLI 标志和 `--json-data` 可以组合。显式标志会覆盖 JSON 负载中的匹配键：

```bash
ml-cli env set-proxy \
  --env-ids 1001 \
  --json-data '{"proxy":{"proxyProvider":"0","proxyIp":"1.1.1.1"}}' \
  --proxy-ip 127.0.0.1
```

## 9. 通过管道传输至 `jq`

CLI 打印原始 JSON，它与 shell 管道配合良好：

```bash
ml-cli status | jq '.status'
ml-cli env processes | jq '.data[].pid'
```

## 10. 常见故障案例

- `Could not detect MoreLogin port`：MoreLogin 未运行、IPC 不可用或未提供 `--port`
- 业务失败，退出代码为 `0`：HTTP 请求成功，但 JSON 响应包含应用程序级错误
- Linux 上的 `ml-cli env arrange`：当前实现不支持它并立即退出