# EVA CLI

EVA CLI 是 EVA Platform 的官方命令行工具，方便用户或者AI Agent在终端完成 EVA 应用的初始化与本地运行。

你可以使用EVA CLI工具完成：

- 账号登录：登录 EVA 账号。

- 平台资源管理：管理租户，项目与API Key。

- 本地项目初始化：创建本地项目，可选拉取官方模板。

如需在深入开发前先运行官方 Demo，可从下文的「快速开始」入手。Demo 运行成功后，若希望AI 编码助手贴合 EVA 的最新用法，可再安装 EVA Skills（通过 skills\.sh 安装，不由本 CLI 分发 ）。

## 快速开始

有两种上手方式：让 AI 编码助手代劳（**Start by agent**）或手动执行命令（**Start manually**）。

### Agent执行（推荐）

详情参考[EVA SDK Skill 文档](./eva-skill)

### 手动执行

若想自己在终端逐步执行，先安装 CLI，再运行官方 starter。

#### 安装

```Bash
npm install -g @autoark-ai/eva-cli
eva --version
eva --help
```

#### 运行官方 starter

运行官方 starter 的最短路径如下：

```Bash
eva login                                # 浏览器登录
eva init my-demo --template browser      # 创建项目 + 拉取模板
cd my-demo
eva key create my-key                    # 签发 API Key
eva key save                             # 把 Key 写进 .env(EVA_GATEWAY_API_KEY)
npm install
npm run dev
```

##### 命令说明：

- eva login：浏览器登录。

- eva init my\-demo \-\-template browser：核心命令。创建本地项目目录`my-demo`，克隆官方 browser quickstart模板，并创建\./my\-demo/\.eva 文件夹（请勿删除）。本命令**不**签发api key。

所有支持的模板项目可使用命令\``eva template list`\`查询

- eva key create ：签发 API Key 并在终端打印一次完整明文。

- eva key save：把API Key以EVA_GATEWAY_API_KEY 写进 \.env（明文只落文件，不回显到终端 ）。

- npm install 从 npm 拉取 模板对应的SDK（browser对应的是 @autoark\-ai/eva\-client\-sdk\-ts ）

- npm run dev 启动应用。

应用启动成功后即可继续开发应用。若命令执行失败，可参考下文「问题排查」章节，自助逐项排查。

## 从零搭建项目（不使用官方 starter ）

初始化已有本地项目，使用vibe coding继续开发：

```Bash
eva login
eva init my-demo          # 创建/绑定项目 + 写 .eva/project.json 绑定(不签 Key、不写 .env)
cd my-demo
eva key create my-key    # 签发 API Key(完整明文只显示一次)
eva key save             # 以 EVA_GATEWAY_API_KEY 写进 .env(不回显明文)
```

`eva init my-demo`命令（没有\-\-template参数）不会拉取模板，仅创建创建\./my\-demo/\.eva 文件夹（请勿删除）。您可直接使用CLI工具，或者vibe coding开始您的开发工作。

```Bash
eva template list          # 查询支持的模版列表
eva template pull browser  # 拉取模版到当前目录，支持--dir 拉取到指定目录
```

使用`eva template pull`拉取模版时，CLI会校验目标目录是否为空（此校验忽略\.env和\.eva文件夹），如果为空，直接把模版拉到目标目录下。如果非空，则报错，提示用户拉取模版的目标目录只能为空目录。

## 使用命令管理项目与 Key

仅当您为plus及以上套餐用户时，您可以创建新的云端project，用以api key等项目资源。在CLI中，您可以使用以下命令：

```Bash
eva project create my-project    # 创建云端项目。basic用户会报错。
eva project use <projectId>      # 切换到目标project（同时改变cli命令上下文, 默认是default project）
eva key create my-key            # 在签发上下文project中创建api key，完整明文只返回一次
eva key save                     # 把 Key 以 EVA_GATEWAY_API_KEY 为key，写入当前文件夹的.env文件
```

## 问题排查

### `eva` 命令不可用

全局重装，并确认 npm 全局 bin 目录在 `PATH` 上：

```Bash
npm install -g @autoark-ai/eva-cli
which eva                          # 装好后应能打印出 eva 的路径（Windows 用 where eva）
# 若 which/where 找不到，说明全局 bin 目录不在 PATH 上，先定位它：
npm prefix -g                      # 全局前缀，bin 目录在 <前缀>/bin（Windows 即该前缀目录本身）
```

### 无法登录

login命令没有自动打开浏览器：eva login \-\-no\-open，复制 URL 到本机浏览器继续操作。

### 模板拉取失败

browser quickstart 从公开 GitHub 仓库经 HTTPS 克隆（无需 SSH Key ）。失败时请检查网络或使用\-\-from参数指定git source：

```Bash
eva template pull browser --dir my-demo --from <git-url|local-path>
```

### `npm install` 找不到 SDK

`npm install` 从 npm 解析 `@autoark-ai/eva-client-sdk-ts`。确认您ts项目中的`package.json` 声明了sdk包依赖，且本机有 npm registry 访问权限。

### 项目或凭证状态异常

检查登录态与当前上下文：

```Bash
eva auth status          # 登录状态 + token 过期时间
eva whoami               # 当前身份
eva project current      # 当前项目
eva key list             # 当前项目下的 Key(脱敏)
```

## 命令一览

| 命令                                                          | 说明                                                                                                                |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `eva login` / `logout` / `whoami`                             | 浏览器登录 / 登出 / 查看当前身份                                                                                    |
| `eva auth status`                                             | 查看登录状态与 token 过期时间                                                                                       |
| `eva tenant init` / `list` / `use` / `current`                | 初始化默认租户 / 列出租户 / 切换当前租户 / 查看当前租户                                                             |
| `eva project list` / `create` / `use` / `current` / `archive` | 列出 / 创建 / 切换当前 / 查看当前 / 归档项目                                                                        |
| `eva key create` / `list` / `rm` / `show` / `save`            | 签发 Key / 列出\(脱敏\) / 吊销 / 查看明文 / 写入 `.env`                                                             |
| `eva init <name>`                                             | 初始化项目：创建/绑定项目 \+ 写 `.eva/project.json` 绑定\(不签 Key、不写 `.env`\);加 `--template <id>` 同时铺设模板 |
| `eva template list` / `pull`                                  | 列出可用模板 / 拉取模板到目录\(免登录\)                                                                             |

用 `eva <命令> --help` 查看子命令与参数。

命令详情请见[eva\-cli命令参考](./eva-cli-command)