Cloud 66 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.

$ cx backups list --stack <application name> --latest 

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.

$ cx backups download --stack <application name> [--download <download directory>] <backup id>

Note

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

backups new

Creates a new database backup task for an application.

cx backups new --stack <application name> --dbtypes postgresql --frequency <schedule> --gzip <bool> --exclude-tables <table name> --run-on-replica <bool> --backup-type <type>

Note

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. Please read our separate guide on configuring Toolbelt.

containers list

Alias: container list

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

$ cx containers list --stack <application name> [--server <server name>][--environment <environment name>][--verbose]

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.

$ cx containers attach --stack <application name> <container ID>

containers stop

Alias: container stop

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

$ cx containers stop --stack <application name> <container ID>|<container name>

containers restart

Alias: container restart

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

$ cx containers restart --stack <application name> <container ID>|<container name>

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.

⚠️ 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.

$ cx databases promote-replica --stack <stack name> [--dbtype <database type>] <replica server name>

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.

$ cx databases resync-replica --stack <application name> --dbtype <database type> <replica server name>

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.

$ cx download --stack <application name> --server <server name> <path to source file> [<target 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.

$ cx env-vars list --stack <application name> <environment variables> [--history]

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: 

$ cx env-vars download --stack <application name> --environment-type <type> --file <filename> --file-type <file-type>

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.

$ cx env-vars set --stack <application name> [--apply-strategy] <key> <value> 

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.

$ cx env-vars upload --stack <application name> --file <filename> --file-type <type> [--apply-strategy <strategy>] [--delete]

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.

$ cx failover-groups list [--output <view>]

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.

$ cx failover-group add [--primary <primary app>] [--secondary <secondary app>] [--current <current app>] [--no-primary] [--no-secondary]

failover-groups delete

Deletes an existing Failover Group from a Cloud 66 account.

$ cx failover-groups delete --uid <failover UID>

failover-groups update

Updates an existing Failover Group on a Cloud 66 account.

$ cx failover-group update --uid <failover UID> [--primary <primary app>] [--secondary <secondary app>] [--current <app pointer>] [--no-primary] [--no-secondary]

gateways list

Lists all the gateway servers attached to a Cloud 66 account or organization.

$ cx --org <organization_name> gateways list [--verbose]

gateways add

Add a gateway server to a Cloud 66 account.

$ cx gateways add --name <gateway name> --address <gateway address> --username <gateway username> --private-ip <private ip of gateway>

gateways close

Close a gateway (prevents traffic flowing via the gateway).

$ cx gateways close --name <gateway name>

gateways open

Opens a gateway for use with Cloud 66 for a specified amount of time (TTL).

$ cx gateways open --name <gateway name> --key <path/to/gateway/key/file>  --ttl <time to live>

gateways remove

Remove a gateway from a Cloud 66 account.

$ cx gateways remove --name <gateway name>

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.

$ cx info --stack <application name --unmanaged

init

Initializes the Toolbelt. Please read our separate guide on installing and configuring Toolbelt.

init agent

Initializes the Toolbelt as a standalone (headless) agent. Please read our separate guide on installing and configuring Toolbelt.

jobs list

Alias: job list

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

$ cx jobs list --stack <application name> --server <server name>|<server ip>|<server role> --service <service name>

jobs run

Alias: job run

Runs the given job once with the given parameters.

$ cx jobs run --stack <application name> --arg [--arg option --arg option] <job name>

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.

$ cx lease --stack <application name> --port <port to open> [--from <from IP>] --tto <lease time>

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.

$ cx notifications download --stack <application name> --file <filename>

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.

$ cx notifications upload [--stack <application name> | --application-group <group name>] --file <filename>

open

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

$ cx open --stack <application name> <server name>

processes list

Alias: process list

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

$ cx processes list --stack <application name> [--server <server name>] [--name <process name>]

processes pause

Alias: process pause

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

$ cx processes pause --stack <application name> [--server <server name>] [<process name>]

processes restart

Alias: process restart

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

$ cx processes restart --stack <application name> [--server <server name>] [<process name>]

processes resume

Alias: process resume

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

$ cx processes resume --stack <application name> [--server <server name>] <process name>

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.

$ cx processes scale --stack <application name> [--server <server name>] [--name <process name>] [<count>]

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.

$ cx redeploy --stack <application name> --listen [-y] [--git-ref <git_ref>] [--service <service>] [--deploy-strategy <strategy>] [--rollout-strategy <strategy>] [--canary-percentage <percentage>] [--deployment-profile <profile name>]

register-server

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

$ cx register-server [--org <organization>] [--server <IP address>] [--file <filename.txt>] [--user <username>] [--key <private SSH key>] [--force-local-ip <bool>] [--tags <tagA,tagB>]

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)

$ cx run --stack <application name> [--server <server name> | <IP address>] [--service <service name>] [--container <container name>] [--interactive] '<commands>'

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

$ cx servers list --stack <application name> --columns="<list of columns, comma separated>" <server name>

servers reboot

Alias: server reboot

Reboot a specific server.

$ cx servers reboot --stack <application name> --server <server name>

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 arguments. To change each server setting, use the server-set command.

$ cx servers settings list --stack <application name> --server <server name> <setting>

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.

$ cx services info --stack <application name> [--server <server name>] <service name> 

services list

Alias: service list

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

$ cx services list --stack <application name> [--server <server name>] [<service name>]

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 is provided it will query only the specified server.

$ cx services pause --stack <application name> [--server <server name>] <service name>

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 is provided it will query only the specified server.

$ cx services restart --stack <application name> [--server <server name>] <service name>

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 is provided it will query only the specified server.

$ cx services resume --stack <application name> [--server <server name>] <service name>

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.

$ cx services scale --stack <application name> <service name> <count>

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.

$ cx services stop --stack <application name> [--server <server name>] <service name>

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.

$ cx settings list --stack <application name> <setting>

settings set

Alias: setting set

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

$ cx settings set --stack <application name> <setting> <values>

Available settings

Setting Default Description
allowed.web.source nil i.e. 0.0.0.0 IP 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.prefix nil If you change your default Rails assets folder, you can set it here
continuous.deploy false Enable 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.size true Enable/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.frequency daily For application specific log files accepted value: hourly  daily  weekly  monthly
logrotate.app.keep.count 14 The number of log files to keep for each logfile
logrotate.server.frequency daily For server specific log files accepted values: hourly  daily  weekly monthly
logrotate.server.keep.count 14 The number of log files to keep for each logfile
maintenance.mode false Enable or disable maintenance mode on the application.
reconfigure.nginx true If set to true, it will regenerate Nginx configuration and restart it (only on the next deployment)
run.deploy.command true Enable or disable option run deploy command on every deployment (“database migrations” for Rails stacks).
stack.name   View your application name

skycap listen

Polls your Skycap application and prints workflow events when they are triggered, effectively running the commands embedded in the workflow on the client machine.

$ cx skycap listen --stack <application name> [--log-level <level>] [--interval <time>]

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.

If your server deployed behind a gateway, you need to provide the private key in order to pass through the gateway.

$ cx ssh  [--gateway-key <path to gateway key>] --stack <application name> <server name>|<server ip>|<server role> --vv

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.

$ cx stacks clear-caches --stack <application name>

stacks configure download

Alias: stack configure download

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

$ cx stacks configure download --file <filename> --stack <application name> --output <output path>

stacks configure list-versions

Alias: stack configure list-versions

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

$ cx stacks configure list-versions --file <filename> --stack <application name> --version <file version type>

stacks configure upload

Alias: stack configure upload

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

$ cx stacks configure upload --file <filename> --stack <application name> --comments <comment>

stacks configuration list

Alias: stack configuration list

List all the available configurations on an application.

$ cx stacks configuration list --stack <application name>

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.

$ cx stacks configuration apply --stack <application name> --type <config type>

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.

$ cx stacks configuration download --stack <application name> --type <config type> --output <filename>

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.

$ cx stacks configuration upload --stack <application name> --type <config type> --source <source file> --no-apply --commit-message <message>

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.

$ cx stacks list [<application name>] [--output <output style>]

stacks create

Alias: stack create

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

$ cx stacks create --name <new application name> --service_yaml <service definition>

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

$ cx stacks listen --stack <application name>

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.

$ cx stacks reboot --stack <application name> --group <server group> --strategy <reboot strategy> -y

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.

$ cx stacks restart --stack <application name>

stacks ssl

Alias: stack ssl

Add an SSL certificate to a stack.

$ cx stacks ssl --stack <application name> --type <certificate type> --domain <domain name> --ssl-termination --cert <certificate file> --key <SSL key file> --intermediate <intermediate cert file> --overwrite

tags add

Add tags to a given entity.

$ cx tags add --entity <entity type> --id <entity ID> --tags <tag>

tags delete

Remove tags from a given entity.

$ cx tags delete --entity <entity type> --id <entity ID> --tags <tag>

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.

$ cx tail --stack <application name> <server name> | <server ip> | <server role> /optional/log/path/<log filename>

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)

Applications using gateways (Bastion servers) are not supported.

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)

$ cx tunnel --stack <application name> --server <server name> | <server IP> | <server role> --local <local port> --remote <remote port>

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)

$ cx upload --stack <application name> --server <server name> | <server IP> | <server role> /path/to/source/file /path/to/target/directory

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.

$ cx --org <organization name> users list

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.

$ cx users apply-profile <user email> --json <access profile>

users show

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

$ cx users show <user email> --json <filename>