Skip to main content
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.
1

Install the CLI

Check that it works with squarecloud --version. If the command is not found, see Installation.
2

Log in

The CLI shows a short code and opens the authorization page in your browser. Type the code there and approve. The Authentication page covers API keys and CI.
3

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:
squarecloud.app
For a website, add SUBDOMAIN=<name> to publish it at <name>.squareweb.app. Every key is explained in the configuration file guide.
4

Upload the project

From the project folder, run:
The CLI zips the folder, leaving out what squarecloud.ignore lists (plus node_modules, .git and lockfiles by default), and creates a new application:
Output
It also writes the new application’s ID into your configuration file, so the next commands know which app you mean:
squarecloud.app
5

Check that it runs

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

Ship a change

Edit your code, then send the folder to the same application and restart it:
upload creates a new application every time; commit updates the one you already have and keeps its ID, domain and settings.

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

Upload and commit

Every flag of upload, commit and zip, and what goes in the zip.

Environment variables

Set variables from the terminal or load them from a .env file.

GitHub deploys

Deploy on every push through the Square Cloud GitHub App.

Global flags and CI

JSON output, exit codes and running the CLI in pipelines.