EVA CLI 命令参考

登录态：login / logout / whoami / auth status

• eva login [--port <port>] [--no-open] — 通过浏览器登录，JWT 存入系统钥匙串。

  • --port <port>：固定回环端口(默认由 OS 随机选空闲端口)。

  • --no-open：不自动打开浏览器，只打印授权 URL 供手动复制。

  • 换用户登录时会重置本地 current tenant/project，避免仍指向上一个用户的资源。

• eva logout — 登出，清除当前保存的 token。

• eva whoami — 显示当前登录身份(evaUserId / platformRole / profile)。

• eva auth status — 显示登录状态与 token 过期时间，三态：not signed in / expired / signed in。

租户：tenant init | list | use | current

init / list 直接调用后端;use / current 只读写本地 config。

• eva tenant init — 初始化 / 获取你的默认租户(幂等;身份取自 JWT)。

• eva tenant list — 列出你所属的租户，当前租户以 * 标记。

• eva tenant use <tenantId> — 设置当前租户(仅本地)。

• eva tenant current — 显示当前租户(本地)。

项目：project list | create | use | current | archive

list / create / archive 调用后端(tenantId 拼进 URL path);use / current 只读写本地 config。

• eva project list [--tenant <tenantId>] — 列出租户下的项目(默认当前租户)，当前项目以 * 标记，并显示 default / 状态标签。

• eva project create <name> [--tenant <tenantId>] [--description <text>] — 在租户下创建项目。

• eva project use <projectId> — 设置当前项目(仅本地)。

• eva project current — 显示当前项目(本地)。

• eva project archive <projectId> [-y] — 归档项目(软删除，后端无硬删除);默认交互确认，-y / --yes 跳过。

API Key：key create | list | rm | show | save

均在某个 project 下操作：默认用当前项目，--project <projectId> 可覆盖。

• eva key create <name> [--project <id>] [--description <text>] [--ttl <90d|180d|365d|never>] [--no-show-key] — 签发一把新 Key，完整明文默认只回显一次。

  • 不带 --ttl 且在交互终端(TTY)时，弹菜单选有效期;非交互(--json / 非 TTY)默认 never(永久)。

  • --no-show-key：不回显明文——终端不打印 raw_full_key，--json 输出里也置为 null。适合 CI / 随后立即 eva key save 注入 .env 的场景，避免明文落进终端或日志。此时明文将无法再次取回(user 类型 Key 可用 eva key show <id> 事后查看)。

• eva key list [--project <id>] [--status <ACTIVE|SUSPENDED|REVOKED>] [--page <n>] [--size <n>] — 列出项目下的 Key(脱敏)，含 EXPIRES_AT 列。--page 为 0 基页码。

• eva key rm <credentialId> [--project <id>] [-y] — 吊销 Key(吊销即删除，不可撤回);-y / --yes 跳过确认。

• eva key show <credentialId> [--project <id>] — 显示某把 Key 的完整明文(仅 user 类型 Key)。

• eva key save [--key-name <name>] [--project <id>] [--dir <path>] — 把一把 user 类型 Key 的明文写进工程 .env。

  • 目标文件名 / 变量名按最近的 .eva/project.json 绑定解析，兜底 .env + EVA_GATEWAY_API_KEY。

  • 默认从当前项目的 ACTIVE user 类型 Key 里随机取一把;--key-name 指定具体 Key。

  • --dir 指定用于解析绑定 / 写入 .env 的目录(默认当前目录)。

  • 明文只落文件、不回显;--json 会输出写入的路径与变量名。

脚手架：init

• eva init [name] [--template <id>] [--dir <path>] [--from <path|git-url>] [--project <id>] [--new-project] [--tenant <id>] [-y]

  • 默认仅初始化项目：创建 / 绑定项目 + 设为当前 + 写 .eva/project.json 绑定。不签 Key、不写 .env、不打印明文。

  • --template <id>：额外拉取 quickstart 模板文件(仍不写 .env)。

  • --dir <path>：基目录;给定 name 则在其下创建 <dir>/<name>，仅给 --dir 则使用其本身;两者均未给定时 name 即相对当前目录的目录。

  • --from <path|git-url>：覆盖模板来源(配合 --template)。

  • --project <id>：绑定到已有项目(跳过复用 / 新建)。

  • --new-project：强制新建项目而非复用。

  • --tenant <id>：指定租户(默认当前租户 / 自动 init)。

  • -y / --yes:目标目录已有文件时跳过覆盖确认(配合 --template)。

模板：template list | pull

独立拉取模板，免登录、不初始化项目。

• eva template list — 列出可用的 quickstart 模板。

• eva template pull <id> [--dir <path>] [--from <path|git-url>] — 将模板克隆到目录。要求目标目录为空目录（忽略 .env/.eva）

  • --dir：目标目录(默认：当前目录)。

  • --from：覆盖模板来源(本地路径或 git URL)。

Agent 配置：agent list | create | show | update | publish | rm

Agent 配置面（config plane）操作，归属 project 维度：默认用当前项目，--project <id> 可覆盖。

• eva agent list [--project <id>] [--page <n>] [--size <n>] — 列出项目下的 Agent（NAME / UUID / STATUS / UPDATED_AT）。--page 为 1 基页码。

• eva agent create [name] [--project <id>] [--tenant <id>] [--description <text>] [--config <json>] [--config-file <path>] [--no-wizard] [-y] — 创建 Agent。

  • 交互终端（TTY）默认走分步配置向导：ASR（模型 + 采样率）→ TTS（模型 + 音色）→ LLM（模型）→ 情感识别（默认标签多选 + 自定义扩展）→ 系统提示词 → 开场白 → 设备指令（command + 参数）→ 挂载自定义 MCP 工具（≤20 个），汇总确认后一次提交。
  • --config <json> / --config-file <path>：直接给完整配置，跳导向导（两者互斥）。
  • 非交互（--json / 非 TTY / --no-wizard）必须显式给 --config 或 --config-file，否则报 config_required。
  • 提交前按模型市场校验 asr/tts/llm 的模型可用性（尽力而为，市场查询失败则跳过不阻塞）。-y 跳过最终确认。

• eva agent show <uuid> — 查看 Agent 详情，含完整 config JSON。

• eva agent update <uuid> [--name <name>] [--description <text>] [--config <json>] [--config-file <path>] — 更新 Agent：--name / --description 各自独立更新；config 为整体替换（无按字段合并）——建议先 eva agent show <uuid> 拿到完整 config，改后再整体提交，只传部分会清空未传的分组。

• eva agent publish <uuid> [-y] — 把当前草稿配置发布为新不可变版本并指向线上流量（幂等）；-y 跳过确认。

• eva agent rm <uuid> [-y] — 软删除 Agent。

config 主要分组：asr {model, sample_rate}、tts {model, voice_id}、llm {model}、emotion {enabled, labels}、system_prompt、greeting_message、commands [{command_id, description, params}]、tools [{uuid, name}]（挂载引用，上限 20）。

自定义工具（MCP）：tool list | create | show | rm

自定义 MCP 工具管理，归属 tenant 维度（工具在租户内共享、可被多个 Agent 挂载），故为独立顶层命令。

• eva tool list [--tenant <id>] [--page <n>] [--size <n>] [--type mcp] — 列出租户下未软删的自定义工具。--page 为 1 基页码；--type 过滤类型（目前仅 mcp）。

• eva tool create [name] [--tenant <id>] [--type mcp] [--description <text>] [--config <json>] [--config-file <path>] [--no-wizard] [-y] — 创建自定义 MCP 工具。

  • 工具名只允许字母、数字、下划线、连字符（如 amap-mcp）。
  • config 形状：{"type":"sse"|"streamable_http","url":"...","requestHeaders":{...}}；交互向导会依次收集传输类型 / Server URL / 请求头（可空）。
  • 非交互必须显式给 --config 或 --config-file。
  • 服务端落库前会对 MCP Server 做连通性探测，失败报 invalid_mcp_configuration、不落任何行。

• eva tool show <uuid> — 查看工具详情，含 config。

• eva tool rm <uuid> [-f|--force] [-y] — 软删除工具；被已发布 Agent 挂载时会被拦截（tool_in_use），--force 连带移除那些挂载行。

全局选项

• --json：JSON 输出(数据走 stdout，错误走 stderr，形如 { error： { code， message， hint } });供脚本 / CI

• --verbose：输出调试信息到 stderr(绝不打印 token / 明文 Key)

• --no-color：关闭彩色输出