SuccApp CLI

SuccApp CLI 是面向终端、脚本和 AI Agent 的命令行工具，命令名为 succapp。它把 SuccApp 服务器、元数据文件、工作区同步、数据库查询和认证状态开放给命令行，让用户和 AI 可以在浏览器设计器之外完成查询、排查、同步和自动化操作。

在 AI 低代码开发 中，SuccApp CLI 是 AI Agent 与 SuccApp 产品服务器沟通的主要工具，它让 Agent 可以在终端里读取服务器状态、访问元数据文件、管理工作区、查询数据并用 --json 取得结构化结果；详细命令、参数和示例以 succapp --help 及各命令域的 --help 输出为准。

适合场景

SuccApp CLI 适合需要可重复执行、可脚本化或需要结构化输出的任务：

1. 初始化工作区、登录服务器、克隆项目和切换服务器。
2. 让 AI Agent 读取工作区状态、文件 diff、服务器文件、文件历史和数据库结构。
3. 在脚本、终端或 CI 中执行状态检查、同步、修复和验证。
4. 使用 --json 输出给 AI 或自动化流程继续处理。

安装

SuccApp CLI 可以使用 npm 全局安装，安装后本机可直接执行 succapp 命令：

npm install -g @succsoft/succapp

安装后先检查版本和帮助：

succapp --version
succapp --help

版本检查和升级提示

开始使用前，先执行：

succapp --version

这条命令会输出本机 CLI 版本，并在能识别当前服务器时按服务器版本推荐配套 CLI；识别不到服务器时，才按 npm 最新版本判断。看到升级提示时，直接执行提示中的 npm install -g ... 命令即可。

AI Agent 或脚本可以按下面方式判断：

情况	处理方式
提示已是最新版	继续执行后续命令。
提示升级到某个版本或 tag	先执行提示里的安装命令，再重新运行当前任务。
提示找不到适配当前服务器的 CLI	不要直接升级到 npm latest，先确认服务器是否也需要升级。
服务器返回客户端不兼容错误	按 CLI 输出的升级或降级建议处理。

版本检查不会改变命令结果。使用 --json 时，业务结果仍写到 stdout，升级提醒写到 stderr，AI Agent 可以继续稳定解析 stdout。需要在 CI、离线环境或受控终端中关闭检查时，可以设置：

SUCCAPP_NO_UPDATE_CHECK=1 succapp --version

CLI 运行须知

SuccApp CLI 每次执行都是一个短进程。它先解析命令，确定本次运行要访问的工作区、服务器和认证信息，再通过 SuccApp Dev Tool v2 接口访问服务器，最后把结果输出给人或 AI Agent。

succapp 命令
  -> 判断命令类别和运行模式
  -> 定位 workspace 和 server URL
  -> 读取本机认证信息
  -> 调用 SuccApp Dev Tool v2 接口
  -> 输出终端文本或 JSON 结果

命令分类

CLI 命令按能力域分组。日常使用时，先判断任务属于哪一类，再进入对应命令域查看 --help。

命令域	功能概述
workspace	面向本地 SuccApp 工作区，负责初始化、项目克隆、状态检查、拉取、推送、放弃修改、diff、文件历史和工作区修复。
server	直接访问 SuccApp 服务器，负责服务器连通性、项目、文件、历史、页面地址、脚本和缓存等操作。
auth	管理本机保存的服务器认证状态，负责登录、查看登录状态和退出登录。
db	通过 SuccApp 服务器访问数据源，负责查看数据源、schema、表结构，执行查询和受控数据操作。
model	通过 SuccApp 语义模型访问 .tbl 数据模型，负责查看模型摘要、字段、索引，并按模型表达式或 Query DSL 查询模型数据。

完整命令、参数和示例以 succapp --help 及各命令域的 --help 输出为准，手册只介绍使用思路和选择方式。

参数输入和输出约定

SuccApp CLI 的参数校验尽量在真正访问服务器前完成。缺少必要参数、传入空值、数字参数不合法，或同一类输入给了多个来源时，命令会先停止并提示用法错误。

常见输入来源有几类：

输入来源	说明	示例
位置参数	直接跟在命令后面，适合短路径、模型名、表名或短 SQL。	succapp model show <model>
选项值	通过 --name=value 或 --name value 传入，适合过滤、排序、行数和短文本。	succapp model select <model> --max-rows=20
文件	通过 --file、--query-file 等选项从本地文件读取内容。	succapp model query --query-file=./query.json
标准输入	通过管道把内容传给命令，适合 AI Agent 或脚本临时生成的 SQL、JSON 或 token。	`cat query.json

同一类业务输入通常只能选择一个来源。例如 db query 的 SQL 可以来自 <sql>、--file 或管道 stdin；model query 的 Query DSL 可以来自 --query、--query-file 或 --stdin。不要同时传多个来源。

导出类命令还有两个固定约定：

1. db export 和 model export 必须指定 --output，导出结果写入本地文件，不把完整数据写到 stdout。
2. 输出文件已存在时，命令会停止并要求确认；确认覆盖时显式加 --force。

两种运行模式

SuccApp CLI 有两种大的运行模式：基于本地工作区运行，或者临时直连服务器运行。

运行模式	说明	适合场景
本地工作区模式	CLI 在一个 SuccApp 工作区 中运行，基于本地文件、同步基线和服务器状态完成检查、拉取和推送。	完整低代码应用开发、AI 修改元数据、工作区版本管理、多人协作和需要可审计 diff 的改动。
即时远程模式	CLI 不依赖本地 workspace，直接根据 server URL 访问服务器。	临时查询、只读排查、查看服务器文件或历史、生产环境只读检查，以及测试服务器上的小范围确认。

简单判断方式是：只要任务会产生需要保留、评审、回退或发布的修改，就优先使用本地工作区模式；如果只是临时读取服务器信息，可以使用即时远程模式。

Workspace

CLI 的 workspace 命令域以 SuccApp 工作区 为运行边界。工作区结构、mirror、AI 协作文件和 Git 协作约定由工作区页统一说明；这里主要说明 CLI 的使用方式。

只要任务会产生需要保留、评审、回退或发布的修改，就优先在工作区中执行 CLI 命令。临时只读查询或小范围排查，可以使用即时远程模式。

典型起步方式是先初始化工作区，再从服务器克隆项目：

succapp auth login <server-url>
succapp workspace init --server <server-url>
succapp workspace project clone <project>

进入工作区后，workspace status、workspace file diff、workspace file compile、workspace pull、workspace discard、workspace push 等命令会围绕本地文件和服务器基线工作。如果终端不在工作区目录，也可以显式指定 workspace 目录执行命令。

修改仪表板、报表、页面、模型等元数据后，可以把本地文件内容发送到当前服务器做一次编译校验：

succapp workspace file compile path/to/file.dash
succapp workspace file compile path/to/file.dash --json

该命令只校验本地内容，不保存文件，也不修改服务器内容。校验失败时，CLI 会返回服务器编译得到的错误信息，适合 AI Agent 和脚本在推送前发现表达式、组件配置或模型结构错误。

Server URL

server URL 是 SuccApp 服务器地址，例如 http://localhost:8080，也可以是团队提供的测试服务器或生产服务器地址。CLI 要访问服务器时，必须先确定本次命令的 server URL。

CLI 获取 server URL 的来源按优先级可以理解为：

来源	说明
命令中的服务器位置参数	适合即时远程模式，例如直接对某个服务器执行 server ping 或查看服务器文件。
全局 --server	适合本次命令显式指定服务器，通常不写入当前工作区配置；例外是已初始化但还没有活跃服务器的工作区执行 succapp workspace project clone --server <server-url> 时，CLI 会把该服务器添加为活跃服务器后再克隆项目。
workspace 活跃服务器	在本地工作区模式下最常见，workspace 命令默认使用当前工作区配置的活跃服务器。
SUCCAPP_SERVER 环境变量	适合脚本或 CI 环境提供默认服务器地址。

需要快速确认服务器状态时，可以执行：

succapp server info <server-url>

命令会输出产品版本、Dev Tool API 版本，以及服务端返回的各类元数据文件最新版本。默认只展示 product 和 metadata 范围。需要查看 sys、jvm、env 等更多明细时，可以使用 --scope 指定范围：

succapp server info <server-url> --scope jvm
succapp server info <server-url> --scope=env,jvm
succapp server info <server-url> --scope=all

--scope 可以重复使用，也可以用逗号传入多个范围；--scope=all 与 --all 都表示展示全部范围。

脚本或 AI Agent 需要读取这些信息时，使用 --json。其中元数据版本在 info.metadataVersions 中；需要保留服务端详细信息原始结构时，使用 --raw --json。

如果 CLI 无法从这些来源得到 server URL，而命令又必须访问服务器，就会停止执行并提示缺少服务器信息。

认证

除少量连通性检查外，访问服务器项目、文件、同步和数据库能力通常都需要认证。SuccApp CLI 的认证以 server URL 为索引保存：登录时先验证凭证，验证成功后把对应服务器的认证信息保存到本机；后续命令访问同一个服务器时，会自动读取这份本机认证信息。

默认登录方式是 OAuth2 浏览器授权：

succapp auth login <server-url>

执行后，CLI 会打开浏览器进入 SuccApp 授权页。授权完成后，CLI 保存本机认证状态，并在后续命令中自动刷新 OAuth2 access token。

脚本、CI、远程终端或无浏览器环境可以显式使用 PAT：

succapp auth login --pat <server-url>

交互终端会提示输入 PAT，也可以从标准输入传入：

printf "%s" "$PAT" | succapp auth login --pat <server-url>

登录成功后，CLI 会保存可用于访问服务器的 Bearer token，并在后续命令中自动带上认证信息。由于认证信息按服务器地址匹配，服务器地址变更、测试和生产环境切换、或使用不同域名访问同一服务器时，可能需要重新认证或确认当前命令使用的 server URL。

PAT、OAuth2 access token 和 refresh token 只应保存在本机认证状态或受控密钥环境中，不应写入 Git 仓库、项目脚本、文档或日志。认证方式和本机文件结构见认证配置。

模型数据查询

db 命令面向数据库和物理表，model 命令面向 SuccApp 语义模型。需要了解数据源、schema 或物理表结构时使用 succapp db；需要按 .tbl 模型查看字段、维键、度量、索引或执行模型查询时使用 succapp model。

常用只读命令包括：

succapp model list --limit 20
succapp model show /Demo/data/tables/APP/Customer.tbl
succapp model fields /Demo/data/tables/APP/Customer.tbl --dim
succapp model indexes /Demo/data/tables/APP/Customer.tbl
succapp model select /Demo/data/tables/APP/Customer.tbl --where "STATUS='ACTIVE'" --max-rows 20
succapp model query --query-file ./query.json --json

model select 适合对单个 .tbl 做快速查询，--where 使用 SuccApp 表达式语法。model query 适合执行 SuccApp Query DSL，请直接传入 succ.meta.dw.Query JSON 对象，返回行数上限等查询选项写入 options。查询生产环境或敏感数据时，应限制返回行数，并优先使用 --json 交给 AI Agent 继续分析。

安全边界

使用 SuccApp CLI 时，建议遵守以下边界：

1. 写操作前先执行只读命令，例如 status、file diff、server file info、db table describe。
2. 生产服务器上默认只做只读排查；需要写入时必须等待人工确认和发布流程。
3. workspace discard --force、workspace push、server file update、server file remove、db exec、数据源修改和删除都属于高风险操作。
4. 使用 --force 前必须明确影响范围和回退方式。
5. AI Agent 读取命令结果时优先使用 --json，但 CLI 结果只能证明命令执行结果，不能替代产品页面和业务流程验证。
6. PAT、OAuth2 access token 和 refresh token 只放在本机认证状态或受控密钥环境中，不写入 Git 仓库。