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

# Il tuo primo deploy con la CLI

> Installa la CLI di Square Cloud, accedi, effettua il deploy di un progetto con squarecloud upload, leggi i log e pubblica ogni modifica con squarecloud commit.

Questa guida porta un progetto dalla tua macchina a un'applicazione in esecuzione su Square Cloud, poi mostra come pubblicare una modifica. Bastano pochi minuti.

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

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

    Verifica che funzioni con `squarecloud --version`. Se il comando non viene trovato, consulta [Installazione](/it/cli-reference/installation#verificare-linstallazione).
  </Step>

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

    La CLI mostra un codice breve e apre la pagina di autorizzazione nel browser. Digita lì il codice e approva. La pagina [Autenticazione](/it/cli-reference/authentication) spiega le chiavi API e l'uso in CI.
  </Step>

  <Step title="Aggiungi un file di configurazione">
    Nella radice del progetto crea un file `squarecloud.app`. Indica a Square Cloud quale file eseguire, quanta memoria riservare e quale versione del runtime usare:

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

    Per un sito, aggiungi `SUBDOMAIN=<name>` per pubblicarlo su `<name>.squareweb.app`. Ogni chiave è spiegata nella [guida al file di configurazione](/it/getting-started/config-file).
  </Step>

  <Step title="Carica il progetto">
    Dalla cartella del progetto, esegui:

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

    La CLI comprime la cartella, escludendo ciò che elenca [`squarecloud.ignore`](/it/getting-started/squarecloud-ignore) (più `node_modules`, `.git` e i lockfile per impostazione predefinita), e crea una nuova applicazione:

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

    Scrive anche l'ID della nuova applicazione nel file di configurazione, così i comandi successivi sanno a quale app ti riferisci:

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

  <Step title="Controlla che sia in esecuzione">
    ```bash theme={"system"}
    squarecloud app status
    squarecloud app logs
    ```

    Non serve alcun ID: entrambi leggono la riga `ID=`. Per seguire l'output in tempo reale, esegui `squarecloud app realtime` e premi `Ctrl+C` per fermarlo.
  </Step>

  <Step title="Pubblica una modifica">
    Modifica il codice, poi invia la cartella alla stessa applicazione e riavviala:

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

    `upload` crea ogni volta una nuova applicazione; `commit` aggiorna quella che hai già e ne mantiene ID, dominio e impostazioni.
  </Step>
</Steps>

## Come la CLI trova la tua app

I comandi che agiscono su una singola applicazione mostrano `[appID]` nella sintassi: l'ID è facoltativo. La CLI sceglie l'applicazione in quest'ordine:

1. **L'ID che passi.** È il primo argomento, oppure `--app <appID>` nei comandi i cui argomenti sono altro: `app env set`, `remove` e `replace`, tutti i comandi `app file`, `app deploy webhook`, `app deploy github link` e `unlink`, e `app network domain`.
2. **La riga `ID=`** del file `squarecloud.app` nella cartella corrente (oppure `squarecloud.config`; se esistono entrambi, vince `squarecloud.app`).
3. **Un selettore** che elenca le tue applicazioni, quando la CLI è eseguita in un terminale. Usa le frecce e `Enter`; `Esc` annulla.

Alcuni comandi funzionano diversamente:

* `commit` non apre mai il selettore. Senza un argomento né una riga `ID=`, si ferma con exit code 1 e chiede un ID.
* `app snapshot restore` richiede sempre l'ID dell'applicazione come primo argomento.
* I database non hanno un file di configurazione: i comandi `db` accettano l'ID del database oppure aprono un selettore dei tuoi database.
* I comandi `workspace` che agiscono su un workspace richiedono sempre il suo ID.

Per trovare un ID, esegui [`squarecloud app list`](/it/cli-reference/apps#squarecloud-app-list). Negli script e in CI passa sempre l'ID o mantieni la riga `ID=`: il selettore ha bisogno di un terminale interattivo.

### Dove viene salvato l'ID dell'app

`upload` scrive `ID=<appID>` solo quando la cartella ha già un file di configurazione, che comunque serve per l'upload. Modifica soltanto quella riga e lascia invariate le altre chiavi e i commenti. Square Cloud ignora la riga quando legge il file, quindi può restare nello zip.

Eseguire di nuovo `upload` dalla stessa cartella crea un'altra applicazione e aggiorna la riga `ID=` perché punti a quella. Per aggiornare l'applicazione che hai già, usa `commit`. Per lavorare con un'altra applicazione da questa cartella, modifica o elimina la riga.

## Prossimi passi

<CardGroup cols={2}>
  <Card title="Upload e commit" icon="upload" href="/it/cli-reference/deploy">
    Tutti i flag di upload, commit e zip, e cosa finisce nello zip.
  </Card>

  <Card title="Variabili d'ambiente" icon="key" href="/it/cli-reference/environment-variables">
    Imposta le variabili dal terminale o caricale da un file .env.
  </Card>

  <Card title="Deploy da GitHub" icon="github" href="/it/cli-reference/github-deploys">
    Effettua il deploy a ogni push tramite la GitHub App di Square Cloud.
  </Card>

  <Card title="Flag globali e CI" icon="terminal" href="/it/cli-reference/global-flags-and-ci">
    Output JSON, exit code ed esecuzione della CLI nelle pipeline.
  </Card>
</CardGroup>