CLI 命令行
Forgexa CLI（forgexa）是一个轻量级命令行客户端，用于在终端管理工作空间、项目、需求、执行和门禁。
系统前置条件
Forgexa CLI 是一个 Python 包，运行前需要安装 Python 3.9 或更高版本。
检查 Python 版本
bash
# macOS / Linux
python3 --version
# Windows
python --version输出应为 Python 3.9.x 或更高版本。如果命令未找到，或版本低于 3.9，请先安装 Python。
安装 Python
- 从 python.org/downloads 下载 Windows 安装包。
- 运行安装程序。在第一个界面 勾选"Add Python to PATH"，再点击 Install。
- 打开新的终端窗口，验证：powershell
python --version
请勿使用 Microsoft Store 版本
Windows 11 在 %LOCALAPPDATA%\Microsoft\WindowsApps 中放置了一个 python.exe 占位符，点击后会打开应用商店而不是运行 Python。请务必从 python.org 安装。
检查 pip
Python 3.9+ 已内置 pip，验证是否可用：
bash
# macOS / Linux
python3 -m pip --version
# Windows
python -m pip --version如果 pip 缺失，执行以下命令安装：
bash
python3 -m ensurepip --upgrade安装
bash
# 从 PyPI 安装
pip install forgexa-cli
# 或使用 pipx（推荐，隔离安装）
pipx install forgexa-cli
# 验证
forgexa version升级
CLI 随平台版本同步迭代更新，建议每次平台升级后一并升级 CLI。
方式一 — 使用 pip 或 pipx 升级
bash
# 使用 pip 升级
pip install --upgrade forgexa-cli
# 使用 pipx 升级
pipx upgrade forgexa-cli
# 查看当前安装版本
forgexa version方式二 — 使用 CLI 自升级
bash
# 升级到最新已发布版本
forgexa upgrade
# 升级到指定已发布版本
forgexa upgrade --target-version 1.12.3
# 查看当前安装版本
forgexa versionforgexa upgrade 会自动识别当前是通过 pipx 还是 pip 安装，并调用对应的升级流程。升级前会先停止本地 daemon，避免新旧代码混合运行。
适用安装来源
forgexa upgrade 适用于标准的 PyPI / pipx 安装。如果当前是 editable、本地路径或 VCS 安装，请按原始安装方式手动升级。
保持版本同步
CLI 版本应与平台版本保持一致。如果遇到异常报错或命令缺失，优先尝试升级 CLI。
配置
服务器地址按以下优先级解析：
--server-url参数（单次命令覆盖）FORGEXA_SERVER_URL环境变量~/.forgexa/config（由forgexa login --server <url>或forgexa config set保存）- 内置默认值：
https://api.forgexa.net
| 环境变量 | 默认值 | 说明 |
|---|---|---|
FORGEXA_SERVER_URL | https://api.forgexa.net | 服务器地址 |
FORGEXA_TOKEN | — | Bearer 令牌（覆盖 ~/.forgexa/config） |
bash
# 查看当前配置（服务器地址、认证状态、配置文件路径）
forgexa config show
# 永久设置服务器地址
forgexa config set server-url https://your-server.com全局参数
| 参数 | 说明 |
|---|---|
--server-url <URL> | 仅本次命令覆盖服务器地址 |
--format table|json|quiet | 输出格式（默认：table） |
认证
bash
# 登录（令牌和服务器地址保存到 ~/.forgexa/config）
forgexa login
# 一步完成登录，指定服务器和账号
forgexa login --server https://your-server.com --email user@example.com
# 退出（删除保存的令牌）
forgexa logout工作空间
bash
# 列出工作空间
forgexa workspace list
# 创建工作空间
forgexa workspace create "My Team"项目
bash
# 列出工作空间中的项目
forgexa project list --workspace <workspace-id>
# 查看项目状态摘要
forgexa project status --project <project-id>
# 创建项目
forgexa project create "My App" --workspace <workspace-id>
# 创建项目并指定技术栈
forgexa project create "My App" --workspace <workspace-id> --stack "Python FastAPI"需求
bash
# 列出需求
forgexa requirement list --project <project-id>
# 创建需求
forgexa requirement create "用户注册 API" --project <project-id>
# 创建需求并附带描述
forgexa requirement create "用户注册 API" --project <project-id> --description "支持 OAuth2"
# 分析需求（AI 驱动）
forgexa requirement analyze --id <requirement-id>看板 & 工作项
bash
# 显示看板
forgexa board --project <project-id>执行
bash
# 列出执行
forgexa run list --project <project-id>
# 启动执行
forgexa run start <execution-id>门禁
bash
# 列出待审核门禁
forgexa gates pending
# 批准门禁
forgexa gates approve --gate <gate-id>
# 批准并附带评论
forgexa gates approve --gate <gate-id> --comment "LGTM"
# 拒绝门禁并附带原因
forgexa gates reject --gate <gate-id> --reason "缺少错误处理"工作流
bash
# 显示当前工作流策略
forgexa workflow show --project <project-id>
# 从 WORKFLOW.md 重载工作流
forgexa workflow reload --project <project-id>预算
bash
# 显示工作空间预算
forgexa budget --workspace <workspace-id>
# 显示项目预算
forgexa budget --project <project-id>守护进程 & 运行时
本地守护进程（forgexa daemon）负责发现本机已安装的 AI Agent CLI（Claude Code、OpenAI Codex、Gemini CLI、Kimi Code、GitHub Copilot 等），将其注册到 Forgexa 服务器，并轮询执行任务。
快捷命令
所有 forgexa daemon <cmd> 均有对应的顶层快捷方式，可省略 daemon 前缀：
| 完整形式 | 快捷形式 |
|---|---|
forgexa daemon start -d | forgexa start -d |
forgexa daemon stop | forgexa stop |
forgexa daemon restart | forgexa restart |
forgexa daemon status | forgexa status |
forgexa daemon logs -f | forgexa logs -f |
forgexa daemon agents | forgexa agents |
两种形式完全等价。
启动
bash
# 后台启动（推荐）
# 自动防止重复启动，等待服务注册完成后以友好格式展示已发现的 Agent 列表。
forgexa daemon start -d
# 指定服务器地址并后台启动
forgexa daemon start -d --server-url https://your-server.com
# 前台启动（阻塞终端，Ctrl+C 停止）
# 先扫描并展示已发现的 Agent，再启动守护进程主循环。
# 原始日志默认不输出到终端——如需查看请使用 `forgexa daemon logs -f`。
forgexa daemon start后台启动后，CLI 最长等待约 12 秒，待守护进程向服务器注册完成后自动打印已发现的 Agent 列表：
Daemon starting in background
PID : 12345
Server : https://app.forgexa.net
Logs : /Users/you/.forgexa/daemon/daemon.log
Runtime ready (id: abc12345 status: online)
3 agent(s) discovered:
✓ claude Claude Code 1.5.8 [L3]
✓ codex @openai/codex 0.3 [L3]
✓ kimi Kimi Code 1.0.2 [L2]
Stop : forgexa daemon stop
Logs : forgexa daemon logs -f重启
bash
# 停止当前运行的守护进程，以后台方式启动一个新实例
forgexa daemon restart
# 重启并连接到指定服务器
forgexa daemon restart --server-url https://your-server.com停止
bash
forgexa daemon stop状态
bash
# 紧凑表格——显示本地 PID、已注册运行时及每个运行时发现的 Agent
forgexa daemon status
# 展开模式，逐 Agent 显示版本号和兼容级别
forgexa daemon status --verbose
# 显示所有用户的运行时（平台管理员专用）
forgexa daemon status --all紧凑表格示例：
Local daemon : running (PID 12345)
Log file : /Users/you/.forgexa/daemon/daemon.log
ID Daemon Device Status Agents Active/Max Heartbeat
-------- -------- -------- ------- ------------------- ---------- -------------------
abc12345 my-mac MacBook online claude, codex, kimi 0/5 2026-06-26 10:30:00日志
bash
# 显示最后 50 行并退出
forgexa daemon logs
# 显示最后 100 行并退出
forgexa daemon logs -n 100
# 实时滚动输出新日志（类似 tail -f）
forgexa daemon logs -f
# 显示最后 200 行后继续追踪
forgexa daemon logs -n 200 -f日志文件路径：~/.forgexa/daemon/daemon.log（单文件最大 50 MB，滚动保留 5 份备份）。
Agent 列表
专用视图，汇总所有已注册守护进程下的全部 AI Agent 信息。
bash
# 列出所有 Agent，包含版本号和兼容级别
forgexa daemon agents
# 包含所有用户的运行时（管理员专用）
forgexa daemon agents --all输出示例：
Runtime Daemon Device Status Agent Version Compat
-------- -------- -------- ------- ------ ------------------- ------
abc12345 my-mac MacBook online claude Claude Code 1.5.8 L3
codex @openai/codex 0.3 L3
kimi Kimi Code 1.0.2 L2兼容级别说明：L3 全自主执行（推荐）、L2 质量良好、L1 基础能力。
运行时列表
bash
# 列出账号下所有已注册的运行时
forgexa runtimes list
# 包含所有用户的运行时（管理员专用）
forgexa runtimes list --all