CLI 概览

suya CLI 是面向 Subaya 的主要接口——同样服务于人类、AI agent 和 CI。你能通过平台做的一切 都从这里开始；位于 subaya-dev.com 的 Web 控制台用于结果、波形、报告 和审查。心智模型请参见核心概念，从安装到一次通过的仿真请参见 快速开始。

全局标志

这些标志在每个命令上都生效：

标志	描述
--host <url>	目标 API 主机。默认为 https://subaya-dev.com。
--token <token>	为本次调用使用一个显式的认证令牌。
--json	发出机器可读的 JSON 输出。
--pretty	为人类美化打印输出。
-q, --quiet	抑制非必要的输出。
-v, --verbose	打印额外的诊断细节。

--json 与 agent 和 CI 搭配良好；--pretty 是终端中友好的默认值。

项目配置——.subaya/config.toml

大多数项目范围的命令会从本地 .subaya/config.toml 文件读取其默认的 --project。一旦在某个目录中 初始化了项目（见 suya project），像 suya project show、suya sim run 和 suya repo status 这样的命令就会针对该项目运行，而无需你每次传入 --project。显式传入 --project <project-id> 即可覆盖。

认证

两种模式针对同一个 API 解析——完整细节见 认证与 API 密钥 和 suya auth 参考：

• SUBAYA_API_KEY — 面向 agent 和 CI 的环境变量。无需浏览器。
• suya auth login — 面向人类开发者的 OAuth 浏览器流程。

export SUBAYA_API_KEY="sk_..."
suya auth whoami

命令组

组	作用
suya auth	登录、登出并检查你的身份。
suya project	创建、列出并管理项目和阶段。
suya sim	运行云端仿真并检查结果。
suya hw	硬件验证运行和 agent 管理（BitCrucible）。
suya rag	搜索和阅读知识库。
suya plan	规划文档、工作项和图表。
suya repo	为项目创建或连接一个 GitHub 仓库。
suya device	浏览设备目录并分配一个设备。
会话	suya attach / suya detach 你的会话 pod。

更多命令组

这些组补全了整个界面：

• suya arch — 架构和嵌入式引脚规划（模块、引脚规划、外设/时钟配置、validate、generate、.ioc 提交）。
• suya req — 添加和列出项目的需求（suya req add、suya req list）。
• suya review — 代码和设计审查（create、show、list、comment、reply、resolve、approve 等）。
• suya diagram — 编写并将 Mermaid 图表渲染为 SVG/PNG（create、update、show、list、export、render、delete）。

顶层命令

命令	描述
suya version	打印版本元数据。
suya update [--check]	升级到最新发行版；--check 仅报告是否可用。
suya install [--skills] [--path <p>] [--force]	安装 Subaya 集成（suya-cli + planner skill 包）。
suya completion <shell>	为给定的 shell 打印 shell 自动补全。