---
title: SuccApp CLI
navTitle: SuccApp CLI
---
# SuccApp CLI

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

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

## 适合场景{#suitable}

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

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

## 安装{#install}

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

```bash
npm install -g @succsoft/succapp
```

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

```bash
succapp --version
succapp --help
```

### 版本检查和升级提示{#version-check}

开始使用前，先执行：

```bash
succapp --version
```

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

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

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

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

```bash
SUCCAPP_NO_UPDATE_CHECK=1 succapp --version
```

## CLI 运行须知{#concepts}

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

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

### 命令分类{#domains}

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

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

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

### 参数输入和输出约定{#input-output}

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 | succapp model query --stdin` |

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

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

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

### 两种运行模式{#run-modes}

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

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

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

### Workspace{#workspace}

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

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

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

```bash
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 目录执行命令。

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

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

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

### Server URL{#server}

`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 环境提供默认服务器地址。 |

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

```bash
succapp server info <server-url>
```

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

```bash
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，而命令又必须访问服务器，就会停止执行并提示缺少服务器信息。

### 认证{#auth}

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

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

```bash
succapp auth login <server-url>
```

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

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

```bash
succapp auth login --pat <server-url>
```

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

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

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

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

## 模型数据查询{#model}

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

常用只读命令包括：

```bash
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 继续分析。

## 安全边界{#ai}

使用 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 仓库。