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

# Deploy your first app with the CLI

> Install the Square Cloud CLI, log in, deploy a project with squarecloud upload, read its logs and ship every later change with squarecloud commit.

This guide takes a project from your machine to a running application on Square Cloud, then shows how to ship a change. It takes a few minutes.

<Steps>
  <Step title="Install the 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>

    Check that it works with `squarecloud --version`. If the command is not found, see [Installation](/en/cli-reference/installation#verify-the-installation).
  </Step>

  <Step title="Log in">
    ```bash theme={"system"}
    squarecloud auth login
    ```

    The CLI shows a short code and opens the authorization page in your browser. Type the code there and approve. The [Authentication](/en/cli-reference/authentication) page covers API keys and CI.
  </Step>

  <Step title="Add a configuration file">
    In the root of your project, create a `squarecloud.app` file. It tells Square Cloud which file to run, how much memory to reserve and which runtime version to use:

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

    For a website, add `SUBDOMAIN=<name>` to publish it at `<name>.squareweb.app`. Every key is explained in the [configuration file guide](/en/getting-started/config-file).
  </Step>

  <Step title="Upload the project">
    From the project folder, run:

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

    The CLI zips the folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists (plus `node_modules`, `.git` and lockfiles by default), and creates a new application:

    ```bash Output 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>
    ```

    It also writes the new application's ID into your configuration file, so the next commands know which app you mean:

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

  <Step title="Check that it runs">
    ```bash theme={"system"}
    squarecloud app status
    squarecloud app logs
    ```

    No ID needed: both read the `ID=` line. To follow the output live, run `squarecloud app realtime` and press `Ctrl+C` to stop.
  </Step>

  <Step title="Ship a change">
    Edit your code, then send the folder to the same application and restart it:

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

    `upload` creates a new application every time; `commit` updates the one you already have and keeps its ID, domain and settings.
  </Step>
</Steps>

## How the CLI finds your app

Commands that act on one application show `[appID]` in their usage: the ID is optional. The CLI picks the application in this order:

1. **The ID you pass.** It is the first argument, or `--app <appID>` on commands whose arguments are something else: `app env set`, `remove` and `replace`, every `app file` command, `app deploy webhook`, `app deploy github link` and `unlink`, and `app network domain`.
2. **The `ID=` line** of the `squarecloud.app` file in the current folder (or `squarecloud.config`; when both exist, `squarecloud.app` wins).
3. **A picker** listing your applications, when the CLI runs in a terminal. Use the arrow keys and `Enter`; `Esc` cancels.

A few commands work differently:

* `commit` never opens the picker. Without an argument or an `ID=` line, it stops with exit code 1 and asks for one.
* `app snapshot restore` always takes the application ID as its first argument.
* Databases have no configuration file: `db` commands take the database ID or open a picker of your databases.
* `workspace` commands that act on a workspace always take its ID.

To find an ID, run [`squarecloud app list`](/en/cli-reference/apps#squarecloud-app-list). In scripts and CI, always pass the ID or keep the `ID=` line: the picker needs an interactive terminal.

### Where the app ID is saved

`upload` writes `ID=<appID>` only when the folder already has a configuration file, which the upload needs anyway. It changes that one line and keeps your other keys and comments as they are. Square Cloud ignores the line when it reads the file, so it can stay in the zip.

Running `upload` again from the same folder creates another application and points the `ID=` line at it. To update the application you have, use `commit`. To work with a different application from this folder, edit or delete the line.

## Next steps

<CardGroup cols={2}>
  <Card title="Upload and commit" icon="upload" href="/en/cli-reference/deploy">
    Every flag of upload, commit and zip, and what goes in the zip.
  </Card>

  <Card title="Environment variables" icon="key" href="/en/cli-reference/environment-variables">
    Set variables from the terminal or load them from a .env file.
  </Card>

  <Card title="GitHub deploys" icon="github" href="/en/cli-reference/github-deploys">
    Deploy on every push through the Square Cloud GitHub App.
  </Card>

  <Card title="Global flags and CI" icon="terminal" href="/en/cli-reference/global-flags-and-ci">
    JSON output, exit codes and running the CLI in pipelines.
  </Card>
</CardGroup>