A command line application to manage your Square Cloud applications, databases and workspaces.
macOS, Linux and WSL, without sudo:
curl -fsSL https://cli.squarecloud.app/install | shThe script installs into ~/.local/bin (or $SQUARECLOUD_INSTALL_DIR)
after checking the download against the release's checksums.txt. If that
folder is not in your PATH, it asks before adding it to your shell's startup
file; without a terminal to ask, it prints the line to add.
Windows (PowerShell, no administrator rights):
irm https://raw.githubusercontent.com/squarecloudofc/cli/master/scripts/install.ps1 | iexIt installs into %LocalAppData%\squarecloud\bin and adds that folder to your
user PATH.
Debian, Ubuntu, Fedora and RHEL: download the .deb or .rpm for your
architecture from the latest release
and install it:
sudo apt install ./squarecloud_*.deb # Debian, Ubuntu
sudo dnf install ./squarecloud-*.rpm # Fedora, RHELWith npm, on any system:
npm install -g @squarecloud/cliEvery release signs checksums.txt, which lists the SHA-256 of every archive
and package, with cosign keyless signing. To
check a release by hand:
cosign verify-blob checksums.txt \
--bundle checksums.txt.sigstore.json \
--certificate-identity-regexp '^https://github.com/squarecloudofc/cli/.github/workflows/release.yml@refs/tags/v' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
sha256sum --ignore-missing -c checksums.txtsquarecloud auth login # sign in through the browser
squarecloud init # write a squarecloud.app for the current directory
squarecloud upload # zip & upload the current directory as a new app
squarecloud commit -r # commit the current directory and restart
squarecloud app logs -f # print the latest logs and follow new ones (interactive app picker)Commands that print data (list, info, status, logs, whoami,
upload, ...) accept --json for raw machine-readable output; the others
reject it with an error. App/db IDs can be omitted: the CLI falls back to the
squarecloud.app config file or an interactive picker.
upload, commit and zip leave out what squarecloud.ignore, in the
project root, lists. It is the same file, with the same rules, that the
Square Cloud VS Code extension reads:
- gitignore syntax:
#comments,!to re-include,dir/for folders only,/buildfor the root only,*,?,[abc]and**(**/tmp,logs/**,a/**/b). The last matching line wins, and a file inside an ignored folder cannot be re-included. Matching ignores case. - Always ignored first (re-include with
!):node_modules,.git,.github,.vscode,package-lock.json,pnpm-lock.yaml,yarn.lock. - Symbolic links to files are uploaded as the file; links to folders and broken links are skipped with a note.
dist/
*.log
!keep.log
/build
.envOlder names (.squareignore, .squarecloudignore, square.ignore) are
still read when squarecloud.ignore is missing, with a warning to rename.
squarecloud auth login shows a short code and opens
https://squarecloud.app/account/security/authorize in your browser. Type the
code there and approve; the CLI receives a new API key with only the
permissions its commands use. Keys issued this way expire after 90 days
(auth whoami shows the date); run auth login again to renew. Press
Ctrl+C to cancel.
| Option | Use it when |
|---|---|
--no-browser |
The browser cannot be opened from this machine (SSH, containers). The URL is printed; open it anywhere. |
--token <key> |
You already have an API key. It is checked before being saved. |
--with-token |
Scripts and CI: reads the key from stdin, e.g. echo "$KEY" | squarecloud auth login --with-token. |
For CI, create an API key in the dashboard and set SQUARECLOUD_API_KEY:
every command uses it instead of the saved key, and auth login is not
needed. With CI=true the browser login refuses to run, since its key
expires and only a person can renew it. Without a terminal and without one
of these options, auth login exits with a hint.
If this machine is already logged in to another account, auth login asks
before replacing it (--yes skips the question).
auth whoami shows the account, its plan and, for browser logins, when the
key expires and its scopes. auth logout removes the saved key from this
machine. If a command reports that the session expired, the key was revoked
or it lacks a permission, run squarecloud auth login again.
The key goes to the system keychain: Windows Credential Manager, the macOS
Keychain, or the Secret Service on Linux (GNOME Keyring, KWallet). Where there
is none (containers, WSL without D-Bus), it stays in the CLI's config file,
readable only by your user, and auth login says so. A key saved in the file
by an older version moves to the keychain the next time it is used.
auth logout removes it from both places.
--profile <name> (or SQUARECLOUD_PROFILE=<name>) picks a separate login,
with its own keychain entry; without either, the default profile is used.
squarecloud auth login --profile work # log in to a second account
squarecloud app list --profile work # use it for one command
export SQUARECLOUD_PROFILE=work # or for every command in this shellSQUARECLOUD_API_KEY, when set, wins over every profile.
| Command | Description |
|---|---|
auth login / logout / whoami |
Manage your Square Cloud session |
status |
Square Cloud platform health, open incidents and affected components |
init [--yes] [--force] |
Create a squarecloud.app for the project in the current folder |
upgrade [--check] |
Update the CLI to the latest release |
integration install / uninstall [--dry-run] |
Add or remove "Send to Square Cloud" in the Windows Explorer menu |
zip |
Zip the current folder |
upload |
Upload a new application (also app upload) |
commit [app id] [--restart] [--path <dir>] |
Commit the current dir or --file (also app commit) |
| Command | Description |
|---|---|
app list |
List your applications |
app info [id] |
Detailed application info |
app status [id] [--all] [--raw] |
Runtime status (one app or every app) |
app logs [id] [-f] |
Most recent logs; --follow (-f) keeps printing new lines until Ctrl+C |
app metrics [id] [--range 24h|7d] |
CPU, RAM, network, disk I/O and storage metrics |
app realtime [id] |
Stream live logs (stderr lines go to stderr) and status changes until Ctrl+C |
app start / restart / stop [id] |
Lifecycle signals |
app delete [id] |
Delete an application |
app domains |
Every domain configured across your apps |
app load-balancers |
Custom domains grouped by app |
app env list/set/remove/replace |
Environment variables (set KEY=VAL..., --from-file .env; replace needs at least one variable, remove --all clears them all) |
app file list/read/write/move/delete |
Remote file manager (write --from <file> is binary-safe; read -o <file> creates new files with 0600 permissions) |
app deploy list/current/webhook/github link|unlink |
Deployments & Git integrations |
app network dns/domain/analytics/errors/logs/performance/purge-cache |
DNS, custom domain & edge observability |
app snapshot list/create/restore |
Application snapshots |
| Command | Description |
|---|---|
db list |
List your databases |
db create --name --memory --type --version |
Create a database |
db info/status/metrics [id] |
Inspect a database (metrics --range 24h|7d) |
db start/stop [id] |
Lifecycle signals |
db update [id] --name/--memory |
Update a database |
db delete [id] |
Delete a database |
db credentials certificate/reset |
TLS certificate & credential rotation |
db snapshot list/create/restore |
Database snapshots |
| Command | Description |
|---|---|
blob list [prefix] |
List your files in Square Cloud Blob, optionally under a prefix (avatars/) |
blob upload <file> [--name <name>] [--private] |
Upload a file; prints its ID and URL |
blob url <id> |
Print a download link (only the link goes to stdout) |
blob delete <id> |
Delete a file for good (asks first; -y skips) |
blob stats |
Files stored and storage used of your plan |
| Command | Description |
|---|---|
workspace list/create/info/delete/leave |
Manage workspaces |
workspace app add/remove |
Share apps with a workspace |
workspace member add/update/remove/invite-code |
Manage members |
Destructive commands (delete, env replace, env remove --all,
credentials reset, purge-cache, snapshot restore, file read -o over an
existing file, ...) ask for confirmation; pass -y to skip. Answering no, or running without a terminal (CI) and without -y,
exits with code 1 and changes nothing. snapshot list <id> prints the
version IDs that snapshot restore takes. Starting a running app or database (or stopping a stopped one) is
reported as such, not as an error.
A snapshot restore that takes longer than about 90 seconds keeps running on
the server. snapshot restore then follows it, printing each step, until it
succeeds or fails (exit code 1 with the reason); Ctrl+C stops watching, not
the restore. --no-wait returns at that point instead of following it. A snapshot download link
is valid for 1 hour.
app metrics --range 7d shows hourly averages and peaks on Pro and Enterprise
plans (apps of 512 MB or more). Other plans get the last 24 hours, with a note
on stderr.
app logs -f and app realtime open the stream again when the API ends it
(after 10 minutes), so they run until Ctrl+C. They stop with an error when 3
reopens in a row bring no logs or status.
status shows a check mark when the platform is online, a warning sign during
maintenance or degradation, and a question mark when the check itself could
not run, which does not mean the platform is down.
app env set and replace make the application receive each value exactly as
typed. The application reads its variables through a shell, so a value with
spaces or characters such as $, &, ; or | is sent in quotes: single
quotes, or double quotes when the value has a single quote. A value already in
one pair of quotes is kept as written, so 'URL="${HOST}:3000"' still refers
to another variable.
blob upload names the object after the file, without its extension (the
service keeps the extension); --name picks another name. A file above
90 MiB goes up in parts, six at a time, sized from the limits the service
sends, with the progress on stderr. A failed or canceled upload is aborted, so
it does not hold one of your open-upload slots. Only what is safe to repeat is
retried: reads, and parts. A private file has no public URL: blob url <id>
makes a temporary link.
$ squarecloud blob upload backup.tar.gz
Uploading backup.tar.gz (1.20 GB)...
Sent part 77 of 77
✓ Uploaded as 123456789/backup.tar.gz
https://blob.squarecloud.dev/123456789/backup.tar.gzKeys from an auth login before this version lack the Blob permissions: the
first Blob command then asks you to run squarecloud auth login again. A key
in SQUARECLOUD_API_KEY needs blob:read and blob:write.
squarecloud integration install # add the menu entry
squarecloud integration install --dry-run # only print the registry values
squarecloud integration uninstall # remove every key it addedintegration install adds "Send to Square Cloud" to the right-click menu of
folders and .zip files (on Windows 11, under "Show more options"). It writes
under HKEY_CURRENT_USER\Software\Classes, so it needs no administrator
rights, and it points at the squarecloud.exe that ran it: run it again after
moving the CLI. A folder whose squarecloud.app has an ID is committed to that
application; any other folder or .zip is uploaded as a new application. A
Windows notification shows the result.
macOS and Linux have no such command, but a shortcut takes a few lines. In
Nautilus (GNOME Files), save this as
~/.local/share/nautilus/scripts/Send to Square Cloud and make it executable:
#!/bin/sh
cd "$1" && squarecloud uploadOn macOS, create a Quick Action in Automator that receives folders in Finder
and runs the shell script cd "$1" && squarecloud upload, with "Pass input"
set to "as arguments".
Messages, help and flag descriptions follow your system language, detected on
every run: the LANGUAGE, LC_ALL, LC_MESSAGES or LANG variable when set,
otherwise the OS display language (on Windows, the display language, not the
regional format). A language without a translation falls back to English. To pick one for a single run: LC_ALL=pt_BR squarecloud --help.
Set SQUARECLOUD_DEBUG=1 to trace every API request to stderr: method, path,
status and duration. Headers, query strings and bodies are never logged, so the
output is safe to share.
squarecloud init writes the squarecloud.app file
(squarecloud.config on macOS) of the project in the current folder. It
detects MAIN (the main of package.json, or index.js, main.py,
main.go, index.html...), uses the folder name as DISPLAY_NAME, the
minimum MEMORY (256 MB, or 512 MB for a website or API, which also gets a
SUBDOMAIN) and VERSION=recommended, and asks for an optional START
command and AUTORESTART. It can also create a starter squarecloud.ignore.
--yes takes the detected values without asking; an existing file is kept
unless you pass --force.
squarecloud upgrade # download the latest release and replace this binary
squarecloud upgrade --check # only tell whether a new version existsupgrade downloads the archive for your system from the GitHub release,
checks it against the release's checksums.txt and replaces the binary (on
Windows the running one is kept as squarecloud.exe.old and deleted on the
next run). A copy that npm or the system package manager installed is theirs
to update, so upgrade says how instead:
npm install -g @squarecloud/cli@latest # installed with npm
sudo apt install ./squarecloud_*.deb # from a .deb: download the new one from the release
sudo dnf install ./squarecloud-*.rpm # from an .rpm: sameA binary in /usr/bin counts as installed from a package: the .deb and
.rpm put it there, and the install scripts never do.
