# Loopal CLI 安装指南

本文档供 AI Agent 在用户设备上安装 Loopal CLI。用户可以这样提出请求：

```text
请根据 https://loopal.app/install/loopal.md，安装 Loopal CLI。
```

## 安装原则

- 只从 npm 官方仓库安装官方包 `loopal-cli`。
- 不使用 `curl | bash`，不执行来源不明的安装脚本。
- 不使用 `sudo npm install`；遇到全局目录权限问题时说明原因并采用安全方案。
- 安装过程不需要 Loopal API Key，不要要求用户提供或粘贴密钥。

## 一、检查运行环境

Loopal CLI 要求 Node.js 20 或更高版本。先执行：

```bash
node --version
npm --version
```

如果 Node.js 不存在或版本低于 20，应告知用户需要安装或升级 Node.js。安装系统级运行时前，应遵循当前环境的权限规则；无法安全处理时向用户确认，不要擅自修改系统环境。

## 二、检查现有安装

```bash
loopal --version
```

- 命令可以运行：记录当前版本，再按用户要求决定是否更新。
- 命令不存在：继续安装。

## 三、安装 Loopal CLI

在 macOS、Linux 或 Windows PowerShell 中执行：

```bash
npm install --global loopal-cli@latest --registry=https://registry.npmjs.org/
```

npm 会根据当前系统创建对应的 `loopal` 可执行入口；Windows 会生成命令包装文件，用户仍然直接执行 `loopal`。

如果全局安装因为目录权限失败，不要使用 `sudo`。可以先使用 npx 临时运行，并向用户说明全局安装尚未完成：

```bash
npx --yes --package loopal-cli@latest loopal --version
```

## 四、验证安装

安装命令成功后执行：

```bash
loopal --version
loopal --help
npm list --global loopal-cli --depth=0
```

验证要求：

1. 安装命令退出码为 `0`。
2. `loopal --version` 输出有效版本号。
3. `loopal --help` 能正常显示命令帮助。
4. npm 全局列表中存在 `loopal-cli`。

如果 npm 显示已安装，但终端找不到 `loopal`，检查 npm 全局前缀：

```bash
npm prefix --global
```

将对应的可执行目录加入 `PATH` 后重新打开终端。Windows 的 npm 全局命令通常位于 `%APPDATA%\npm`；macOS 和 Linux 通常位于全局前缀的 `bin` 目录。不要在不确认路径的情况下修改用户配置文件。

## 更新

```bash
npm install --global loopal-cli@latest --registry=https://registry.npmjs.org/
loopal --version
```

## 卸载

只有用户明确要求卸载时才执行：

```bash
npm uninstall --global loopal-cli
```

卸载 CLI 不会自动删除 `~/.loopal` 中的本地配置或凭证。

## 完成反馈

最后向用户报告：

- 安装或更新后的 Loopal CLI 版本。
- `loopal --help` 是否验证成功。
- 是否遇到 `PATH` 或权限问题。

不要在最终回复中输出 npm Token、Loopal API Key 或其他敏感凭证。