> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 全局标志、退出码与 CI

> 使用 Square Cloud CLI 的全局标志、JSON 输出、退出码和调试追踪，检查平台健康状况，并在脚本和 CI 中安全地运行 CLI。

## `squarecloud help`

```bash 用法 theme={"system"}
squarecloud help [command]
squarecloud [command] --help
```

列出所有命令，或说明某个命令。帮助内容会跟随你的[系统语言](/zh/cli-reference/installation#语言)。

```bash 输出 theme={"system"}
A command line application to manage your Square Cloud applications

Usage:
  squarecloud COMMAND [flags]
  squarecloud [command]

Available Commands:
  app         Manage your applications with these commands
  auth        Manage your Square Cloud login with these commands
  commit      Make a commit for your application
  db          Manage the databases of your account
  help        Help about any command
  status      Check the Square Cloud platform health
  upload      Upload a new application
  workspace   Manage your team workspaces
  zip         Zip the current folder

Flags:
  -h, --help      Show help for this command
      --json      Output raw JSON
  -v, --version   Print the CLI version

Use "squarecloud [command] --help" for more information about a command.
```

## 全局标志

| 标志 | 说明 |
| - | - |
| `--json` | 在输出数据的命令（`list`、`info`、`status`、`logs`、`auth whoami`、`upload` 等）上打印原始的机器可读 JSON。没有 JSON 输出的命令（`app start`、`app delete`、`commit`、`zip` 等）会报错并拒绝该标志。 |
| `-h`, `--help` | 显示任意命令的帮助。 |
| `-v`, `--version` | 打印 CLI 版本。仅适用于 `squarecloud` 本身。 |

破坏性命令还接受 `-y`/`--yes`，用于跳过 `y/N` 确认。各命令的页面中都会列出这一标志。

## `squarecloud status`

```bash 用法 theme={"system"}
squarecloud status [--json]
```

检查 Square Cloud 平台是否运行正常。此命令无需登录即可使用。要查看单个应用或数据库，请使用 [`squarecloud app status`](/zh/cli-reference/status-and-metrics#squarecloud-app-status) 或 [`squarecloud db status`](/zh/cli-reference/databases#squarecloud-db-status)。

```bash 输出 theme={"system"}
✓ <status message>
```

当平台报告问题时，该行会改为以 `X` 开头。另请参阅[状态页面](https://status.squarecloud.app/)。

## 调试

* 设置 **`SQUARECLOUD_DEBUG=1`** 会将每个 API 请求记录到 stderr：方法、路径、状态和耗时。请求头、查询字符串和请求体永远不会被记录，因此可以放心分享该输出。
* 读取请求在发生网络错误或平台短暂繁忙时会自动重试。
* 按下 **Ctrl+C** 会取消正在进行的请求；再按一次 Ctrl+C 会退出正在等待输入的命令。

```bash theme={"system"}
SQUARECLOUD_DEBUG=1 squarecloud app list
```

## 脚本与 CI

在无人值守的环境中运行时，CLI 的行为是可预测的：

* **身份验证：** 设置 `SQUARECLOUD_API_KEY`，而不是运行 `auth login`。参见[身份验证](/zh/cli-reference/authentication#ci-与脚本)。
* **显式传入 ID。** 应用和数据库选择器需要终端。参见 [CLI 如何找到你的应用](/zh/cli-reference/quickstart#cli-如何找到你的应用)。
* **退出码：** 每次失败都会以退出码 `1` 退出，包括通过 npm 安装 CLI 的情况。请检查退出码，而不是消息文本。
* **确认默认按拒绝处理。** 回答否，或者在没有终端且未传入 `-y` 的情况下运行需要确认的命令，都会以退出码 `1` 退出，且不做任何更改。需要确认的命令有 `app delete`、`app env replace`、`app env remove --all`、`app file delete`、覆盖现有文件的 `app file read -o`、`app network purge-cache`、`app snapshot restore`、`db delete`、`db snapshot restore`、`db credentials reset`、`workspace delete`、`workspace leave`、`workspace member remove`，以及会替换另一个账户密钥时的 `auth login`。
* **stdout 只包含结果。** 错误、"未登录"消息、确认提示、失败行和更新通知都会输出到 stderr。使用 `upload --json` 时，进度消息也会输出到 stderr。
* **解析 `--json`，而不是表格。** 在非英语系统上，表头和 `info` 的标签会被翻译。要强制使用英语，请使用 `LC_ALL=en_US.UTF-8` 运行。
* **已处于该状态即视为成功。** 启动正在运行的应用或数据库，或者停止已停止的应用或数据库，都会说明这一点并以退出码 `0` 退出。

要通过 GitHub Actions 部署，请参阅帮助中心的[自动部署工作流](https://help.squarecloud.app/en-us/article/workflow-github-actions-automated-deploy-ff34mk/)。

## 相关内容

| 命令 | API | JavaScript SDK |
| - | - | - |
| `status` | [`GET /v2/service/status`](/zh/api-reference/endpoint/service/status) | [`api.service.status()`](/zh/sdks/js/client) |