# Використання AI-агента

На цій сторінці пояснюється, як використовувати `ml-cli` з помічниками кодування на основі ШІ, такими як Codex, Claude Code, Cursor, Gemini CLI та іншими.

## Скопіювати в агент

Скопіюйте текст нижче та вставте його у вашого ШІ-помічника для автоматичного налаштування MoreLogin CLI:

```text
Set up MoreLogin CLI for me, then use it whenever I ask you to operate MoreLogin.

Official docs:
https://guide.morelogin.com/cli

Goal:
- Install or update `ml-cli`.
- Verify MoreLogin Desktop local API access.
- Read the built-in agent package and guide.
- After setup, ask what MoreLogin task I want to automate first.

First detect my OS and CPU architecture, then run the matching install command.

Windows x64 PowerShell:

```powershell
$dir = "$env:USERPROFILE\.morelogin\bin"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
Invoke-WebRequest -Uri "https://releases.morelogin.com/prod/MoreLogin_AirDrop_window_x64_cli/2.6.3/MoreLogin_AirDrop_window_x64_cli_2.6.3.0.exe" -OutFile "$dir\ml-cli.exe"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($userPath -notlike "*$dir*") { [Environment]::SetEnvironmentVariable("Path", "$userPath;$dir", "User") }
& "$dir\ml-cli.exe" --version
```

macOS Intel x64:

```bash
mkdir -p "$HOME/.local/bin"
curl -L "https://releases.morelogin.com/prod/MoreLogin_AirDrop_darwin_x64_cli/2.6.3/MoreLogin_AirDrop_darwin_x64_cli_2.6.3.0" -o "$HOME/.local/bin/ml-cli"
chmod +x "$HOME/.local/bin/ml-cli"
export PATH="$HOME/.local/bin:$PATH"
ml-cli --version
```

macOS Apple Silicon arm64:

```bash
mkdir -p "$HOME/.local/bin"
curl -L "https://releases.morelogin.com/prod/MoreLogin_AirDrop_darwin_arm64_cli/2.6.3/MoreLogin_AirDrop_darwin_arm64_cli_2.6.3.0" -o "$HOME/.local/bin/ml-cli"
chmod +x "$HOME/.local/bin/ml-cli"
export PATH="$HOME/.local/bin:$PATH"
ml-cli --version
```

Linux x64:

```bash
mkdir -p "$HOME/.local/bin"
curl -L "https://releases.morelogin.com/prod/MoreLogin_AirDrop_linux_x64_cli/2.6.3/MoreLogin_AirDrop_linux_x64_cli_2.6.3.0" -o "$HOME/.local/bin/ml-cli"
chmod +x "$HOME/.local/bin/ml-cli"
export PATH="$HOME/.local/bin:$PATH"
ml-cli --version
```

After installation, run:

```bash
ml-cli --help
ml-cli doctor --output-json
ml-cli agent-bootstrap
ml-cli agent-package
ml-cli agent-guide
```

For long-term use, install persistent rules for my AI agent:

```bash
ml-cli agent-list
ml-cli agent-init --agent <agent> --scope user --dry-run
ml-cli agent-init --agent <agent> --scope user --write
```

Use the correct `<agent>` value for my AI client. Supported values are listed by `ml-cli agent-list`, including `codex`, `claude-code`, `cursor`, `gemini`, `qwen-code`, `opencode`, `openclaw`, `trae`, `hermes`, `qclaw`, `easyclaw`, and `workbuddy`.

Use `ml-cli` for MoreLogin browser profiles, environment lists, cloud phones, proxies, groups, tags, schedules, and local API status.

Do not guess IDs, payload fields, or command formats. If unsure, inspect help first:

```bash
ml-cli env --help
ml-cli cloudphone --help
ml-cli proxy --help
ml-cli schedule --help
```

Operation timing:
- `env start` / `env open` takes 3-5 seconds; use `--timeout 30`.
- `cloudphone power-on` / `cloudphone open` takes 30-90 seconds; always use `--timeout 120`.
- All other commands complete within the default `--timeout 15`.

Natural language routing rules:
- "How many browser profiles are on the first page?" -> run `ml-cli env list --page-no 1 --page-size 20`, then count `data.dataList`.
- "Open P-1" -> run `ml-cli --timeout 30 env open --name P-1`.
- "Find browser profiles by group, tag, name, or remark containing Amazon" -> run `ml-cli env find --keyword Amazon`.
- "Open the profile whose group, tag, name, or remark contains Amazon" -> run `ml-cli --timeout 30 env open --keyword Amazon`.
- "Open cloud phone CP-204 and show the window" -> run `ml-cli --timeout 120 cloudphone open --keyword CP-204 --headless false`.
- "Close cloud phone CP-204" -> run `ml-cli --timeout 30 cloudphone close --keyword CP-204`.
- "Create a new browser profile" -> run `ml-cli env create-quick`.
- "Delete browser profile P-1" -> find it first with `ml-cli env find --name P-1`, confirm with the user, then run `ml-cli env delete --env-ids <id>`.
- "Create a proxy" -> run `ml-cli proxy create --proxy-ip <ip> --proxy-port <port> --proxy-provider 0`.
- "Show all tags" -> run `ml-cli tag list`.
- "Create a group called test" -> run `ml-cli group create --group-name test`.
- "Set proxy for profile P-1" -> find the profile first, then run `ml-cli env set-proxy --env-ids <id> --proxy-ip <ip> --proxy-port <port> --proxy-type 0 --proxy-provider 0`.

Candidate selection rule:
- `env open`, `cloudphone open`, and `cloudphone close` may operate only when exactly one candidate matches.
- If zero or multiple candidates match, show the candidates and ask me which one to operate.

Local access rule:
MoreLogin CLI connects to `127.0.0.1:<port>`, usually `127.0.0.1:40000`. Started browser profiles may expose `127.0.0.1:<debugPort>`.
If Codex, Claude Code, Cursor, or another AI client reports `connect EPERM 127.0.0.1:40000`, `connect EPERM 127.0.0.1:<debugPort>`, `connection refused`, `request timeout`, or `Could not detect MoreLogin port`, treat it as local sandbox/permission first. Request local access approval or elevated execution and rerun the same command. Do not repeatedly start the same profile after an EPERM error; check status first.

When a command fails, show the original MoreLogin response. Do not redact proxy passwords, phone numbers, device identifiers, or other fields unless I explicitly ask you to. For scripts, add `--fail-on-business-error` when a non-zero top-level JSON `code` should fail the command.

Future updates:
- To update `ml-cli`, run `ml-cli self-update`. Or rerun this setup prompt and overwrite the existing binary with the newest official download.
- To update persistent agent rules, rerun `ml-cli agent-init --agent <agent> --scope <scope> --write`.
- Restart the AI agent if it only loads memory/rules files on startup.

After verification, tell me:
- install path
- `ml-cli --version`
- `ml-cli doctor --output-json` result
- available top-level commands

Then ask me what MoreLogin task I want to automate first.
```

Ви також можете згенерувати той самий текст із встановленого CLI:

```bash
ml-cli install-prompt
```

## Команда Agent Guide

Після встановлення агенти повинні прочитати вбудований посібник:

```bash
ml-cli agent-guide
```

Посібник повідомляє агенту:

- коли використовувати `ml-cli`
- як виявляти формати команд
- як зіставляти природну мову з командами
- коли запитувати підтвердження
- як обробляти помилки локальної пісочниці, такі як `connect EPERM 127.0.0.1:40000`


## Команда Doctor

Використовуйте `doctor` для перевірки підключення до локального API:

```bash
ml-cli doctor
ml-cli doctor --output-json
```

`doctor` перевіряє виявлення порту та викликає кінцеву точку статусу MoreLogin.

## Зручні команди для профілів браузера

Використовуйте ці команди, коли користувачі посилаються на профілі за іменем:

```bash
ml-cli env find --name P-1
ml-cli env find --keyword Amazon
ml-cli env open --name P-1
ml-cli env open --keyword "team-a"
ml-cli env open --name P-1 --exact
```

`env find --keyword` шукає за назвою середовища, назвою групи, назвою тегу та приміткою через локальний API MoreLogin.
`env open` запускає профіль лише при точному збігу одного кандидата. Якщо збігаються кілька профілів, виводить список кандидатів і завершується без запуску.

## Зручні команди для хмарних телефонів

Використовуйте ці команди, коли користувачі посилаються на хмарні телефони за іменем:

```bash
ml-cli cloudphone find --name CP-1
ml-cli cloudphone find --keyword "android-test"
ml-cli --timeout 120 cloudphone open --name CP-1
ml-cli --timeout 120 cloudphone open --keyword "android-test"
ml-cli --timeout 120 cloudphone open --name CP-1 --headless false
ml-cli --timeout 30 cloudphone close --name CP-1
ml-cli --timeout 30 cloudphone close --keyword "android-test"
ml-cli --timeout 120 cloudphone open --name CP-1 --exact
```

`cloudphone find --keyword` шукає за назвою хмарного телефону, назвою групи, назвою тегу та приміткою через локальний API MoreLogin.
`cloudphone open` та `cloudphone close` працюють лише при точному збігу одного кандидата. Якщо збігаються кілька телефонів, виводять список кандидатів і завершуються без зміни стану.
Для `--headless`: `false` відображає вікно хмарного телефону, `true` — не відображає. Значення API за замовчуванням — `true`.

## Приклади природною мовою

Після налаштування ви можете запитати:

```text
Скільки профілів браузера на першій сторінці в MoreLogin?
```

```text
Покажи мені першу сторінку профілів браузера MoreLogin, включаючи ім'я, ID та статус.
```

```text
Відкрий профіль P-1.
```

```text
Перевір, чи запущений профіль P-1.
```

```text
Закрий профіль P-1.
```

```text
Знайди профілі браузера, в іменах яких є Amazon.
```

```text
Знайди профілі, в назві середовища, групи, тегу або примітці яких є Amazon.
```

```text
Відкрий середовище браузера, група або тег якого містить Amazon. Якщо кілька — спочатку покажи кандидатів.
```

```text
Запусти перший профіль браузера і скажи мені порт налагодження.
```

```text
Покажи всі групи MoreLogin.
```

```text
Покажи всі теги MoreLogin.
```

```text
Покажи першу сторінку записів проксі.
```

```text
Покажи список хмарних телефонів.
```

```text
Відкрий хмарний телефон CP-1.
```

```text
Знайди хмарні телефони, група, тег або примітка яких містить Android.
```

```text
Відкрий хмарний телефон, ім'я, група, тег або примітка якого містить CP-204, і покажи вікно.
```

```text
Закрий хмарний телефон CP-1.
```

```text
Прочитай довідку ml-cli і підсумуй основні команди для профілів браузера.
```