Command Line Interface

Cloud 66 Toolbelt

Configuring Toolbelt

Installation

  1. Download the cx executable to a directory in your PATH
  2. Initialize it by running cx stacks list
  3. Authenticate using your browser

For more detailed help on installation please refer to our Getting Started guide.

Installing on a server (headless)

To install Toolbelt on a server (without a browser):

  1. Install and authenticate cx on your local machine (see above)
  2. Log into your server via your terminal and move to the .cloud66 directory (under home)
  3. Create a file named cx.json in that folder
  4. Go to the terminal on your local machine, where you already have Toolbelt authorised and execute cx dump-token, which will give you your authorisation token
  5. Copy this token and paste it into the (remote) cx.json file that you created in Step 3
  6. Save the file and then run cx stacks list on the server to confirm that Toolbelt is initialised

Running Toolbelt inside a Docker container

You can run the Cloud 66 Toolbelt inside a Docker container, although this is not officially supported.

Step 1: Start an ubuntu container

We start a generic Ubuntu container (Cloud 66 runs on Ubuntu servers)

$ docker run -it ubuntu:latest /bin/bash

Step 2: Install required/useful tools

Toolbelt relies on three tools - curl, nano and ssh - so we install these packages.

$ apt update
$ apt install curl nano ssh -y

Step 3: Create some default folders

We need to create some default folders to support Toolbelt’s requirements.

$ mkdir -p ~/.ssh
$ mkdir -p ~/.cloud66

Step 4: Install Toolbelt

Now we install the Toolbelt by CURLing the installation shell script on S3:

$ curl -sSL https://s3.amazonaws.com/downloads.cloud66.com/cx_installation/cx_install.sh | bash

Step 5: Register Toolbelt

Finally we need to register Toolbelt:

  1. Install and authenticate cx on your local machine
  2. SSH into your container and move to the .cloud66 directory (under home)
  3. Create a file named cx.json in that folder
  4. Go to the terminal on your local machine, where you already have Toolbelt authorised and execute cx dump-token, which will give you your authorisation token
  5. Copy this token and paste it into the (container’s) cx.json file that you created in Step 3
  6. Save the file and then run cx stacks list from inside the container to confirm that Toolbelt is initialised

After this, you should be able to use cx commands inside the container.

Shortcuts

Toolbelt has some useful shortcuts to help speed up your workflow.

Running cx in a git directory

To make life easier for you, the Cloud 66 toolbelt detects the Git URL and branch for each directory it is run in. As such, you won’t have to specify which application you want to run the toolbelt on if you’re in the git folder and branch of one of your applications.

Naming shortcuts

We apply naming shortcuts to both application and server names, as well as server roles in the toolbelt, so you don’t have to type their full names. We just need you to type enough of a name for it to be unique.

For example, if you only have one application that starts with m, you can simply type m. Similarly, if you only have one web server, you can type w instead of web

Toolbelt commands

These commands are listed alphabetically by top level command name.

backups list

Lists all the managed backups of an application grouped by their database type and/or backup schedule.

backups download

Download a managed database backup via the command line. If the backup spans multiple files, the command will automatically concatenate them into a single file.

Managed backups only

This command only applies to managed backups and not the unmanaged ones.

backups new

Creates a new database backup task for an application.

Managed backups only

This command only applies to managed backups and not the unmanaged ones.

config

Allows you to configure multiple profiles in cx to support multiple Cloud 66 accounts.

containers list

Alias: container list

Lists all the containers running on an application or server (depending on your parameters).

containers attach

Alias: container attach

Connect to a container (by container name) and print the STDOUT output stream of the container process. This is roughly equivalent to tailing the logs of a container.

If you need to connect to a container in order to execute commands, you should use the cx run command and specify the name of the container.

containers stop

Alias: container stop

Stops a specific container on a given stack by container ID or name (supports partial IDs and names).

containers restart

Alias: container restart

Restarts a particular container on a given stack by container ID or name (supports partial IDs and names).

databases promote-replica

Alias: database promote-replica Alias: database promote-slave (deprecated) Alias: databases promote-slave (deprecated)

Promotes the specified replica database server to a standalone master. The replica will be reconfigured as the new standalone DB. Providing the database type is optional and is only necessary for shared servers where we can’t automatically determine the target database type.

Could result in downtime

This action could result in application downtime, it is advisable to choose a low traffic time to perform this action, and to place your application in maintenance mode.

The existing master and other replicas will need to be removed after this process as after this the new configuration will have only a single database. You will be able to configure replication again by scaling up new servers.

In the case of any servers not being accessible during this time, those servers will remain unchanged. It is therefore important to stop/shut down those servers in this case (or to manually stop the DB service on those servers) as having multiple masters in a cluster could cause problems throughout the cluster.

databases resync-replica

Alias: database resync-replica Alias: database resync-slave (deprecated) Alias: databases resync-slave (deprecated)

Re-syncs the specified replica database server with its master database server. From time-to-time your replica database may go out of sync with its master. This action attempts to re-sync your specified replica server. This can happen depending on many factors (such as DB size, frequency of change, networking between servers etc).

The server provided must have already been configured as a replication replica via the Cloud 66 UI. Providing the database type is optional and is only necessary for shared servers where we can’t automatically determine the target database type.

download

Use this command to download a copy of file from the remote server to your local computer. If you don’t specify a target directory, the file will be downloaded to your current local directory.

dump-token

Prints the content of the cx token file with no new lines.

Usage

$ cx dump-token

env-vars list

Prints environment variables (both keys and values) for your application to terminal. If environment variable keys are specified, the list will be limited to those keys. The --history option lists any recent changes to each variable.

env-vars download

Downloads the environment variables from an application and writes them to a file. This file can either use the same format as web download (dotenv) or json.

You can specify which kinds of variables to download using environment-type with the following variables:

  • all returns all environment variables
  • user returns user-created environment variables
  • generated returns environment variables generated by Cloud 66
  • locked returns non-editable environment variables that were generated by Cloud 66

env-vars set

Adds (or updates) a single environment variables for your application. You can use the --apply-strategy option to specify when Cloud 66 will apply the change in environment variables to your servers. The default is immediately.

env-vars upload

Set the environment variables for an application based on a file in either dotenv or json format.

You must specify an apply-strategy for your upload process. They can either be applied immediately or on the next deployment.

failover-groups list

Lists the Failover Groups for a Cloud 66 account. Info includes the Failover Group ID, address, attached applications and current active application.

failover-groups add

Adds a new Failover Group to a Cloud 66 account. You can create an empty Failover Group with neither primary nor secondary app set.

failover-groups delete

Deletes an existing Failover Group from a Cloud 66 account.

failover-groups update

Updates an existing Failover Group on a Cloud 66 account.

help

Shows a full list of commands or detailed help for one command.

Usage

$ cx help
$ cx <command> --help

info

Shows information about your account, toolbelt and the specified stack or the current directory.

init

Initializes the Toolbelt.

init agent

Initializes the Toolbelt as a standalone (headless) agent.

jobs list

Alias: job list

Lists all automated (scheduled) jobs on an application or a server.

jobs run

Alias: job run

Runs the given job once with the given parameters.

lease

This will open the firewall of the given server for a limited time. 'Time to open' is in minutes. By default the firewall closes after 20 minutes. The maximum time to open is 240 minutes.

login

Opens the default web browser and logs into the associated Cloud 66 account. This makes it easier to login to Cloud 66 web UI by streamlining your login through a registered and authenticated Toolbelt.

Usage

$ cx login

notifications download

Download all the alert settings for a given application as a YAML formatted file.

notifications upload

Uploads notifications in a YAML formatted file. Settings in the file will replace any existing settings. If an application group is specified, all of the apps in the group will be updated.

open

Opens the default web browser and opens the web end-point of a given application.

processes list

Alias: process list

List the details of the processes running on an application or a server.

processes pause

Alias: process pause

Pauses all processes for the given service and/or server.

processes restart

Alias: process restart

Restarts all processes on the given service and/or server.

processes resume

Alias: process resume

Resumes all paused processes on the given service and/or server.

processes scale

Alias: process scale

Starts <count> processes from the given process definition. <count> can be an absolute value like 2 or a relative value like [+2] or [-3] If server is provided, will start <count> processes on that server. If server is not provided, will start <count> processes on every server. NOTE: the square brackets are required for relative count values.

redeploy

Alias: stacks redeploy

Enqueues redeployment of an existing application. If the app is already building, another build will be enqueued and performed immediately after the current one is finished.

register-server

A shortcut to run the server registration script on a group of servers.

run

Execute a command directly on a remote server, in a service, or in a existing container. To do this it:

  1. Opens the firewall for SSH from your IP address temporarily (20 minutes)
  2. Downloads your SSH key if you don’t have it
  3. Starts a SSH session
  4. Executes the command specified and returns its output.

You need to have the correct access permissions to use this command. You can use either the server name (e.g. lion) or the server IP (e.g. 123.123.123.123) or the server role (e.g. web). If a role is specified the command will connect to the first server with that role.

This command is only supported on Linux and OS X clients (for Windows you can run this in a virtual machine if necessary)

servers list

Alias: server list

List details for all the servers used by an application including name, IP address, server role and the date/time it was created. The <name> argument can be a list of server names entered as separate parameters. The optional <columns> argument sets the type of server info to display in each column, and their order.

Column options: availability-zone, cores, created-at, distro, distro-version, dns, health, is-kubernetes-master, memory, name, notifications, private-ip, product-uuid, public-ip, region, roles, root-disk-size, root-disk-type, subnet-id, uid, vendor-uid, vpc-id

servers reboot

Alias: server reboot

Reboot a specific server.

servers settings list

Alias: server settings list

Lists all the settings applicable to the given server. It also shows the key, value and the readonly flag for each setting. Settings can be a list of multiple <setting> arguments. To change each server setting, use the server-set command.

services info

Alias: service info

Get info for given the service. The list of available services can be obtained through the services list command. If the server is provided it will only query the specified server.

services list

Alias: service list

List all the services and running containers of a whole application or a specific server.

services pause

Alias: service pause

Pauses all the containers for the given service. The list of available services can be obtained through the list services command. If <server name> is provided it will query only the specified server.

services restart

Alias: service restart

Restarts all the containers for the given service. The list of available services can be obtained through the list services command. If <server name> is provided it will query only the specified server.

services resume

Alias: service resume

Resumes all the containers from the given service that were previously paused. The list of available services can be obtained through the list services command. If <server name> is provided it will query only the specified server.

services scale

Alias: service scale

Starts <count> containers for the given service across the stack. If <count> is an absolute value like 2, then that will be the total of <count> containers across the application. If <count> is a relative value like [+2] or [-3], then the current total count of containers across the application will be changed by <count>. NOTE: the square brackets are required for relative count values.

services stop

Alias: service stop

Stops all the containers for the given service. The list of available services can be obtained through the list services command. If <server name> is provided it will query only the specified server.

settings list

Alias: setting list

Lists all the settings for the given application, including the key, value and readonly flag for each setting. You can use <setting> multiples times to query multiple services.

settings set

Alias: setting set

Sets and applies the value of a setting to an application.

Available settings

SettingDefaultDescription
allowed.web.sourcenil i.e. 0.0.0.0IP addresses that are allowed to access a stacks web servers (with IP addresses in the command or a CSV file with IP addresses as input)
asset.prefixnilIf you change your default Rails assets folder, you can set it here
continuous.deployfalseEnable or disable continuous deployment on Github.
custom.build.command-Set custom build command. Only applies to Sinatra or Padrino stacks
custom.deploy.command-Set custom deploy command. Only applies to Sinatra or Padrino stacks
db.check.backup.sizetrueEnable/Disable Check free space before taking backup
git.branch-Change the Git branch of the application repository
git.repository-Change the Git repository URL
logrotate.app.frequencydailyFor application specific log files accepted value: hourly  daily  weekly  monthly
logrotate.app.keep.count14The number of log files to keep for each logfile
logrotate.server.frequencydailyFor server specific log files accepted values: hourly  daily  weekly monthly
logrotate.server.keep.count14The number of log files to keep for each logfile
maintenance.modefalseEnable or disable maintenance mode on the application.
reconfigure.nginxtrueIf set to true, it will regenerate Nginx configuration and restart it (only on the next deployment)
run.deploy.commandtrueEnable or disable option run deploy command on every deployment ("database migrations" for Rails stacks).
stack.nameView your application name

ssh

Allows direct SSH shell into your servers by opening the firewall temporarily for the source IP address, downloading the SSH key and starting a SSH session with one command.

Your server SSH key is downloaded to ~/.ssh and re-used in subsequent SSH connections via the toolbelt. You need to have shell to server rights over the application to use this command.

stacks clear-caches

Alias: stack clear-caches

For improved performance, Cloud 66 caches volatile code. It is possible for a those caches to become invalid if you switch branches, change git repository URL, rebase or force a commit. Since switching branch or changing git repository URL is done via the Cloud 66 interface, your volatile caches will automatically be purged. However, rebasing or forcing a commit is external to Cloud 66 and therefore doesn’t trigger the purge, so this command can be used to manually purge the existing volatile caches.

stacks configure download

Alias: stack configure download

Download configuration files such as a service.yml or manifest.yml. (containerized apps only)

stacks configure list-versions

Alias: stack configure list-versions

List the versions of configuration files such as a service.yml or manifest.yml. (containerized apps only)

stacks configure upload

Alias: stack configure upload

Upload configuration files such as a service.yml or manifest.yml. (containerized apps only)

stacks configuration list

Alias: stack configuration list

List all the available configurations on an application.

stacks configuration apply

Alias: stack configuration apply

Applies the latest configuration to an application. You can find all the types of configuration available on your application using the stacks configuration list function.

stacks configuration download

Alias: stack configuration download

Gets the content of the specified configuration file from the given application and either prints it to screen or saves it as a file. You can find all the types of configuration available on your application using the stacks configuration list function.

stacks configuration upload

Alias: stack configuration upload

Updates the content of the specified configuration type on the stack and (optionally) applies it. You can find all the types of configuration available on your application using the stacks configuration list function.

stacks list

Alias: stack list

Lists applications. Shows the application name, environment, and last deploy time. You can query (multiple) applications by name - but the command will display all applications by default.

stacks create

Alias: stack create

Creates a new Cloud 66 application based on a service definition (service.yml) and an optional application Manifest (manifest.yml).

stacks listen

Alias: stack listen

Acts like a tail for all the deployment logs for an application (to tail a specific log file, see the function below).

stacks reboot

Alias: stack reboot

Reboots groups of servers in your application. Valid values for the <group> argument are all, web, haproxy, and db. Database specific values like mysql or redis are also supported.

<strategy> specifies whether you want your web servers to be rebooted in parallel or in serial. For serial reboots web servers are removed and re-added to the load balancer one by one. Non-web server will always be rebooted in parallel. If this value is left unspecified, Cloud 66 will determine the best strategy based on your infrastructure layout.

stacks redeploy

Alias: stack redeploy

Triggers the deployment of an application. Alias of redeploy function.

stacks restart

Alias: stack restart

Sends a restart signal to all application components. This means different things for different components. For a web server, it means a restart of nginx. For an application server, this might be a restart of the worker processes.

stacks ssl

Alias: stack ssl

Add an SSL certificate to a stack.

tags add

Add tags to a given entity.

tags delete

Remove tags from a given entity.

tail

Runs a Linux tail command on the specified server and given log file. You must specify the log file name including the extension. If you don’t specify a path, or specify a relative path, then we will assume <stack-directory>/current/log (i.e. the subdirectory und $STACK_PATH) as the current directory. You can specify a different (absolute) log path as needed.

This command is only supported on Linux and OS X.

test

Checks if cx is properly installed and authenticated.

Usage:

$ cx test

tunnel

Opens an SSH tunnel between your local machine and the remote server on a specific port. This is useful when connecting to remote databases or other services using local tools.

tunnel does the following:

  1. Opens a lease in port 22 for your local IP address
  2. Fetches your SSH key from your Cloud 66 account
  3. Starts an SSH tunnel between your machine and the server on the given ports
  4. Closes the tunnel when you exit the Toolbelt (Ctrl-C)

If a role is specified the command will connect to the first server with that role.

To specify the ports for the tunnel, use --local and --remote arguments. For example, if you need to connect to a MySQL server, you can use 3307 locally and 3306 (MySQL port on the server) as the remote port. Once the tunnel is established, you can use your favourite MySQL client to connect to the server on 127.0.0.1 and the local port (3307 in this case).

If a local port is not specified, cx will use "remote + 1" as a convention for the local port. For example, if you only specify --remote 5432 without explicitly specifying local, cx will use 5433 as the local port.

This command is only supported on Linux and OS X (for Windows you can run this in a virtual machine if necessary)

update

This command runs automatically. You should not need to run it manually. You can use it to force cx to use a certain version.

Usage:

$ cx update --force <version>

upload

Copies a file from your local computer to the remote server. Uploads the files to the /tmp directory by default, unless a path is specified.

This command open the firewall for SSH from your IP address temporarily (20 minutes), downloads the keys if you don't have them and starts a SSH session. If a role is specified the command will connect to the first server with that role.

This command is only supported on Linux and OS X (for Windows you can run this in a virtual machine if necessary)

users list

Shows a list of all the users in an organization that you have rights to manage. You can find your <organization name> by using cx info.

users apply-profile

Apply Profile allows you to apply a user’s Access Profile to another one. To use this command you need to have an Access Profile as a json file. This can be generated using the users show command with the json option. Once you have the file you can modify it to make any changes you require in the Access Profile.

Any missing attribute for the json Access Profile will be left unchanged even if override is used. Also, override doesn’t have any effect on the contents of the account_profile section.

users show

Returns details about a user. You can dump these as a json file for use with the users apply-profile function.

Configuration profile commands

You can configure your Toolbelt to work with multiple Cloud 66 accounts and/or organizations using configuration profiles.

config create

Creates a new configuration profile

$ cx config create <name> [--org <org name>]

config use

Switches to using the named configuration profile.

$ cx config use <name>

config rename

Renames an existing configuration profile.

$ cx config rename <old name> <new name>

config delete

Delete a configuration profile.

$ cx config delete <name>

config list

Lists all your configuration profiles.

$ cx config list

config show

Show the details for a profile

$ cx config show <name>

config update

Set a configuration profile to point to an organization.

cx config update NAME [--org <org name>]

Setting up a profile:

  1. Run cx config create <name> where <name> is your chosen profile name
  2. Run cx config use <name> to switch to the new profile and initialize it by running cx stacks list
  3. Authenticate using your browser (be sure to log into the correct account)

For more detailed help on installation please refer to our Getting Started guide.

Default profile

You always have a default profile which cannot be deleted or renamed.

Switching between profiles

To switch between profiles, use cx config use <name>

All commands from that point onwards will run against the <name> profile. This is persisted between different terminal sessions until it's changed.

Setting Profile per command

If you would like to run a command with a different profile other than the current profile, you can use the --profile argument with all commands:

cx --profile NAME stacks list

Using profiles with organizations

When you create a profile you can specify the organization to which this new profile should be linked. For example:

cx config create hobby --org my_private_sandbox

...will create a profile named "hobby" that is linked to a Cloud 66 organization named "my_private_sandbox".

If you're unsure about the name of an organization you can run the cx info command and looking at the Name field. You can also see this by logging into your Dashboard, visiting Account Settings and clicking on Organisations in the Account panel on the left.

Previous
Getting started with Cloud 66 Toolbelt