> ## 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.

# 用 CLI 部署你的第一个应用

> 安装 Square Cloud CLI 并登录，用 squarecloud upload 部署项目，查看日志，之后的每次改动都用 squarecloud commit 发布。

本指南带你把本地项目变成在 Square Cloud 上运行的应用，并演示如何发布改动，只需几分钟。

<Steps>
  <Step title="安装 CLI">
    <CodeGroup>
      ```bash macOS, Linux and WSL theme={"system"}
      curl -fsSL https://cli.squarecloud.app/install | bash
      ```

      ```bash Windows (needs Node.js) theme={"system"}
      npm install -g @squarecloud/cli
      ```
    </CodeGroup>

    用 `squarecloud --version` 确认安装成功。如果提示找不到命令，请参阅[安装](/zh/cli-reference/installation#验证安装)。
  </Step>

  <Step title="登录">
    ```bash theme={"system"}
    squarecloud auth login
    ```

    CLI 会显示一个短代码，并在浏览器中打开授权页面。在页面中输入该代码并批准即可。API 密钥和 CI 的用法见[身份验证](/zh/cli-reference/authentication)。
  </Step>

  <Step title="添加配置文件">
    在项目根目录创建 `squarecloud.app` 文件。它告诉 Square Cloud 要运行哪个文件、预留多少内存以及使用哪个运行时版本：

    ```systemd squarecloud.app theme={"system"}
    MAIN=index.js
    MEMORY=512
    VERSION=recommended
    DISPLAY_NAME=My first app
    ```

    如果是网站，添加 `SUBDOMAIN=<name>`，即可在 `<name>.squareweb.app` 上发布。每个键的说明见[配置文件指南](/zh/getting-started/config-file)。
  </Step>

  <Step title="上传项目">
    在项目文件夹中运行：

    ```bash theme={"system"}
    squarecloud upload
    ```

    CLI 会压缩该文件夹，排除 [`squarecloud.ignore`](/zh/getting-started/squarecloud-ignore) 中列出的内容（默认还会排除 `node_modules`、`.git` 和锁文件），然后创建一个新应用：

    ```bash 输出 theme={"system"}
    Compressing the current directory.
    Uploading the zip file to Square Cloud.

    ✓ Application uploaded to Square Cloud!
      Open it at https://squarecloud.app/dashboard/applications/<appID>
    ```

    它还会把新应用的 ID 写入你的配置文件，让后续命令知道你指的是哪个应用：

    ```systemd squarecloud.app theme={"system"}
    MAIN=index.js
    MEMORY=512
    VERSION=recommended
    DISPLAY_NAME=My first app
    ID=<appID>
    ```
  </Step>

  <Step title="确认应用正在运行">
    ```bash theme={"system"}
    squarecloud app status
    squarecloud app logs
    ```

    不需要传入 ID：这两个命令都会读取 `ID=` 行。要实时查看输出，运行 `squarecloud app realtime`，按 `Ctrl+C` 停止。
  </Step>

  <Step title="发布改动">
    修改代码后，把文件夹发送到同一个应用并重启它：

    ```bash theme={"system"}
    squarecloud commit --restart
    ```

    `upload` 每次都会创建一个新应用；`commit` 则更新你已有的应用，并保留它的 ID、域名和设置。
  </Step>
</Steps>

## CLI 如何找到你的应用

作用于单个应用的命令在用法中显示为 `[appID]`：ID 是可选的。CLI 按以下顺序确定应用：

1. **你传入的 ID。** 它是第一个参数；如果命令的参数另有用途，则用 `--app <appID>` 传入，这类命令有：`app env set`、`remove` 和 `replace`，所有 `app file` 命令，`app deploy webhook`，`app deploy github link` 和 `unlink`，以及 `app network domain`。
2. **当前文件夹中 `squarecloud.app` 文件的 `ID=` 行**（也可以是 `squarecloud.config`；两者都存在时以 `squarecloud.app` 为准）。
3. **选择器**：当 CLI 在终端中运行时，会列出你的应用供你选择。用方向键和 `Enter` 选择，按 `Esc` 取消。

有几个命令的行为不同：

* `commit` 从不打开选择器。既没有参数也没有 `ID=` 行时，它会以退出码 1 停止并要求提供 ID。
* `app snapshot restore` 总是把应用 ID 作为第一个参数。
* 数据库没有配置文件：`db` 命令接受数据库 ID，或打开你的数据库选择器。
* 作用于某个 workspace 的 `workspace` 命令总是需要传入它的 ID。

要查找 ID，运行 [`squarecloud app list`](/zh/cli-reference/apps#squarecloud-app-list)。在脚本和 CI 中，请始终传入 ID 或保留 `ID=` 行：选择器需要交互式终端。

### 应用 ID 保存在哪里

只有当文件夹中已有配置文件时（上传本来就需要它），`upload` 才会写入 `ID=<appID>`。它只修改这一行，其他键和注释保持不变。Square Cloud 读取该文件时会忽略这一行，所以它可以留在 zip 中。

在同一文件夹中再次运行 `upload` 会创建另一个应用，并让 `ID=` 行指向新应用。要更新已有的应用，请使用 `commit`。要在这个文件夹中操作另一个应用，请修改或删除这一行。

## 后续步骤

<CardGroup cols={2}>
  <Card title="上传与 commit" icon="upload" href="/zh/cli-reference/deploy">
    upload、commit 和 zip 的全部标志，以及 zip 中包含哪些内容。
  </Card>

  <Card title="环境变量" icon="key" href="/zh/cli-reference/environment-variables">
    在终端中设置变量，或从 .env 文件加载。
  </Card>

  <Card title="GitHub 部署" icon="github" href="/zh/cli-reference/github-deploys">
    通过 Square Cloud GitHub App 在每次推送时自动部署。
  </Card>

  <Card title="全局标志与 CI" icon="terminal" href="/zh/cli-reference/global-flags-and-ci">
    JSON 输出、退出码，以及在流水线中运行 CLI。
  </Card>
</CardGroup>