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.

!!! warning "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>

Login​

Authenticate with your server:

cloudron login my.example.com

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

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

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