Cloudron CLI

Overview

The Cloudron CLI is a command line tool for building and installing custom apps.

All CLI commands operate on apps, not the server. For example, cloudron restart and cloudron uninstall operate on an app, not the server.

Installing

The CLI is distributed via npm. Install on Linux/Mac:

sudo npm install -g cloudron

The CLI is not tested on Windows but works with varying success. Windows users should use a Linux VM instead.

Do not install on the server

The CLI is intended to be installed on your PC/Mac and should NOT be installed on the server.

Updating

Update the CLI:

npm install -g cloudron@<version>

The version number can be found here.

Login

Authenticate with your server:

cloudron login my.example.com

A successful login stores the authentication token in ~/.cloudron.json.

Self-signed certificates

When using self-signed certificates, use the --allow-selfsigned option.

Listing apps

Display installed apps:

cloudron list

The Id is the unique app instance id. Location is the domain where the app is installed. Use either field as the argument to --app.

Viewing logs

View app logs:

cloudron logs --app blog.example.com
cloudron logs --app 52aae895-5b7d-4625-8d4c-52980248ac21

Pass -f to follow the logs. Not all apps log to stdout/stderr. Check the file system for logs:

cloudron exec --app blog.example.com       # shell into the app's file system
# tail -f /run/wordpress/wp-debug.log # note that log file path and name is app-specific

Pushing a file

Push a local file to the app's file system:

cloudron push --app blog.example.com dump.sql /tmp/dump.sql
cloudron push --app blog.example.com dump.sql /tmp/               # same as above. trailing slash is required

Push a directory recursively:

cloudron push --app blog.example.com files /tmp

Syncing files and directories

Use cloudron sync push and cloudron sync pull to transfer only changed files (size + mtime comparison), similar to rsync.

cloudron sync push --app blog.example.com ./local/ /app/data     # upload contents of local into /app/data
cloudron sync push --app blog.example.com ./local /app/data      # upload local dir itself into /app/data/local
cloudron sync push --app blog.example.com file.txt /app/data     # upload a single file
cloudron sync pull --app blog.example.com /app/data/ ./local     # download contents of /app/data into ./local
cloudron sync pull --app blog.example.com /app/data ./local      # download /app/data dir itself into ./local/data

A trailing slash on the source syncs its contents; without it, the directory itself is placed inside the destination (same convention as rsync).

Options:

• --delete removes files that exist only at the destination side.
• --force removes files blocking directory creation at the destination.

For directory workflows, prefer cloudron sync over cloudron push/pull. Use cloudron push/pull for simple one-off file copies or stdin/stdout style transfers.

Pulling a file

Pull a file from the app's file system:

cloudron pull --app blog.example.com /app/code/wp-includes/load.php .  # pulls file to current dir

Pull a directory:

cloudron pull --app blog.example.com /app/code/ .            # pulls content of code to current dir
cloudron pull --app blog.example.com /app/code/ code_backup  # pulls content of code to ./code_backup

Environment variables

Set environment variable(s):

cloudron env set --app blog.example.com RETRY_INTERVAL=4000 RETRY_TIMEOUT=12min

Unset an environment variable:

cloudron env unset --app blog.example.com RETRY_INTERVAL

List environment variables:

cloudron env list --app blog.example.com

Get a single environment variable:

cloudron env get --app blog.example.com RETRY_INTERVAL

App shell

Apps are containerized and run with a virtual file system. Navigate the file system:

cloudron exec --app blog.example.com

Apart from 3 special directories - /app/data, /run and /tmp, the file system is read-only. Changes to /run and /tmp are lost across restarts. These directories are also cleaned up periodically.

Execute a command

Execute arbitrary commands in the context of an app:

cloudron exec --app blog.example.com
# ls # list files in the app's current dir
# mysql --user=${MYSQL_USERNAME} --password=${MYSQL_PASSWORD} --host=${MYSQL_HOST} ${MYSQL_DATABASE} # connect to app's MySQL

Pass a command with options using -- to indicate end of arguments:

cloudron exec --app blog.example.com -- ls -l

If the command has environment variables, execute it using a shell:

cloudron exec --app blog.example.com -- bash -c 'mysql --user=${CLOUDRON_MYSQL_USERNAME} --password=${CLOUDRON_MYSQL_PASSWORD} --host=${CLOUDRON_MYSQL_HOST} ${CLOUDRON_MYSQL_DATABASE} -e "SHOW TABLES"';

CI/CD

Integrate the CLI in a CI/CD pipeline using --server and --token arguments. Get tokens at https://my.example.com/#/profile.

cloudron update --server my.example.com --token 001e7174c4cbad2272 --app blog.example.com --image username/image:tag