CLI 概述

Workova CLI 是 Workova 的终端操作入口，适合批量处理、脚本调用和自动化集成场景。

什么是 Workova CLI

Workova CLI 允许您在终端中执行 Agent 对话、工作流运行、MCP 管理等操作，无需打开桌面端界面。典型使用场景包括：

• CI/CD 流水线中触发工作流
• 批量创建或更新 Agent 配置
• 脚本化管理 MCP 连接和 Skill 绑定
• 在无 GUI 环境中执行自动化任务

架构

Workova CLI 复用桌面端 runtime，不是独立的执行引擎。CLI 通过 runtime bridge 与桌面端通信，桌面端负责实际的任务执行、工具调用和 MCP 管理。

┌──────────┐    bridge     ┌─────────────────┐
│  CLI     │ ────────────> │  桌面端 runtime  │
└──────────┘               └─────────────────┘

命令语法

所有命令遵循 workova <domain>:<action> 格式：

workova runtime:health
workova agent:list
workova workflow-run:start --input '{"workflowId": "wf_abc"}'

域（domain）与操作（action）用冒号分隔，参数通过标准 flag 传递。

执行模型

CLI 命令按执行方式分为两类：

类型	说明	示例
bridge 执行	必须连接桌面端 runtime	agent:list、workflow-run:start、mcp:connect
本地执行	不依赖 bridge，可独立运行	auth:login、auth:status、account:profile

TIP

大部分命令需要 bridge 连接。请确保桌面端正在运行，或通过环境变量指定 bridge 地址。

Bridge 连接

CLI 启动时自动发现本地运行的桌面端实例并建立 bridge 连接。

当 bridge 不可用时，认证和账号类命令（auth:*、account:*）可降级为本地模式运行。其余命令将返回连接错误。

WARNING

降级模式下，依赖 runtime 的功能（Agent 执行、MCP 调用、工作流运行等）均不可用。

输入方式

需要传递结构化数据的命令支持两种输入方式：

# 内联 JSON
workova agent:create --input '{"name": "my-agent", "model": "claude-3"}'

# 从文件读取
workova agent:create --input-file ./agent-config.json

环境变量

变量	说明	默认值
WORKOVA_GUI_APP_PATH	桌面端应用路径	系统默认安装路径
WORKOVA_RUNTIME_BRIDGE_BIN	bridge 可执行文件路径	内置
WORKOVA_DISABLE_AUTO_DISCOVERY	禁用桌面端自动发现	false
WORKOVA_CLI_SESSION_FILE	会话文件路径	~/.workova/cli-session.json
WORKOVA_CLI_CONFIG_FILE	配置文件路径	~/.workova/cli-config.json

命令分组

分组	说明
auth	认证（登录、登出、状态查询）
account	账号管理（资料、配额、用量）
agent	Agent 管理（增删改查、Skill 绑定）
conversation / chat / run	对话与执行
workflow / workflow-run	工作流定义与运行
automation	自动化触发器
mcp	MCP 服务管理
skill / plugin	Skill 与插件管理

推荐首次运行

安装完成后，建议依次执行以下三条命令验证环境：

1. 检查 bridge 连接状态

workova runtime:health

{
  "success": true,
  "data": {
    "bridge": "connected",
    "runtime": "ready",
    "version": "1.5.0"
  }
}

2. 查看可用的 contracts

workova contracts:list

{
  "success": true,
  "data": {
    "contracts": [
      "agent",
      "conversation",
      "workflow",
      "mcp",
      "skill",
      "plugin",
      "automation"
    ]
  }
}

3. 确认登录状态

workova auth:status

{
  "success": true,
  "data": {
    "authenticated": true,
    "expired": false,
    "session": {
      "expires_at": "2026-04-06T10:00:00Z",
      "user": { "id": "usr_x9y8z7", "email": "user@example.com" }
    }
  }
}

首次运行故障排查

现象	原因	解决方案
runtime:health 返回 unavailable	桌面端未启动	启动 Workova 桌面端
contracts:list 无输出	bridge 未连接或 runtime 未就绪	等待桌面端完全启动后重试
auth:status 显示未登录	未执行登录或会话已过期	执行 workova auth:login

下一步

• 快速开始 - 从零开始使用 CLI
• 完整命令参考 - 所有命令和参数详情