Back to Blog

Common Convox CLI Commands


This guide walks you through common Convox commands used in a typical rack and application lifecycle.

It is designed to help you understand how to use Convox more effectively by detailing command options and contexts. Running the command convox by itself will list all available commands, providing a broad overview of your options. Additionally, you can append the --help option to any command to get more detailed information about its usage. Whether you're deploying applications, managing racks, or configuring settings, this guide provides the insights needed to navigate and utilize Convox commands proficiently. Learn how to target your commands correctly and manage your deployments with ease, ensuring a smooth operational flow across your projects.

Understanding Convox Command Contexts and Options

Convox commands are versatile and can be executed globally, at the rack level, or at the app level, depending on the scope of the action required:

  • Global Level: Commands that apply across all environments.
  • Rack Level: Commands that are specific to a single rack. You can specify the target rack by using the -r rackName option. If you have previously used convox switch rackName, this rack becomes your active rack, and you do not need to include the -r rackName option for further commands within this rack. However, you can still use -r rackName to target commands to a different rack, even when switched to another.
  • App Level: Commands that are specifically targeted at an application within a rack. When executing these commands, you must specify the application using the -a appName option. If you are operating within the application's directory and this directory's name matches the application name, Convox assumes you are referring to that application, and you can omit the -a appName option.

By understanding these levels and options, you can more effectively manage your infrastructure and application deployments with Convox. This guide aims to clarify how to target your commands accurately to ensure they affect the intended scope of your Convox environment.

Note: All examples provided in this guide include the full -a appName and -r rackName options for the sake of clarity and information.

Convox CLI Setup

These commands involve setting up and updating the Convox CLI.

convox login

Authenticate with the Convox Console using your login token. You can generate a new token from your Console Account Page.
$ convox login -t a1234567-acde-1234-abcde-123abc456def
Authenticating with OK

convox version

Check the current version of the Convox client and the current selected rack.
$ convox version
client: 3.18.0
server: 3.18.1

convox update‍

Update the Convox CLI to the latest version.
$ sudo convox update
Updating to 3.18.1... OK

Rack Configuration

Commands related to managing and switching between Convox racks.

‍convox racks

List all available racks.
$ convox racks
NAME                       PROVIDER  STATUS
my-organization/demo-rack  aws       running

convox switch

Switch to a specific rack. Once switched to a rack you will not need to add the -r rackName flag to commands to target the rack.
$ convox switch demo-rack
Switched to my-organization/demo-rack

convox rack

Display detailed information about a rack.
$ convox rack -r demo-rack
Name      demo-rack
Provider  aws
Status    running
Version   3.18.1

convox rack params‍

View parameters of the current rack. You can find the full list and details for rack parameters for each cloud provider in our documentation: AWS | GCP | Azure | Digital Ocean
$ convox rack params -r demo-rack
region   us-east-1
release  3.18.1

convox rack params set

Set a specific parameter for the rack. Some parameter changes require node recreation; this can take up to 10 minutes for the parameter to take effect. You can monitor the update status in the Update tab on the Convox Console after selecting your rack. Once updated, you can verify that the parameter is set by running convox rack params -r rackName.
$ convox rack params set build_node_enabled=true -r demo-rack
Updating parameters... OK

convox rack kubeconfig‍

Generate kubeconfig for the current rack and save it locally. This allows for kubectl commands to be sent directly to the rack's k8s cluster. By doing this, you gain direct command-line access to manage Kubernetes resources, enhancing your ability to perform detailed operations and troubleshooting.
$ convox rack kubeconfig -r demo-rack > ~/.kube/config

Application Management

These commands cover the lifecycle of applications from creation to deployment.

convox apps create

Create a new application. You can specify the application name immediately following the command. If no name is provided, the name of your local directory will be used by default.
$ convox apps create nodejs -r demo-rack
Creating nodejs... OK

convox deploy

Deploy an application. The deployment process involves packaging, uploading the source, and building the application.
$ convox deploy -a nodejs -r demo-rack
Packaging source... OK
Uploading source... OK
Starting build... OK
2024-05-01T03:44:01Z system/k8s/atom/app Status: Updating => Running

convox apps

List all applications and their status in the rack. This command allows you to quickly view a snapshot of each application's deployment state within your active or specified rack.
$ convox apps -r demo-rack
nodejs  running  RVTLOODDBZQ

convox env set

Set an environment variable for an application. This command updates an environment variable or creates a new one, generating a new release in the process. This release must be promoted to apply the changes.
$ convox env set FOO=BAR -a nodejs -r demo-rack
Setting FOO... OK

convox env edit

This command launches an interactive editor allowing you to modify environment variables directly. Changes made through the editor will generate a new release that must be promoted to take effect.
$ convox env edit -a nodejs -r demo-rack
# Opens an interactive editor for environment variables.

convox releases

List releases of an application. This command displays a detailed list of all releases associated with a specified application, showing each release's ID, status, associated build, creation time, and description.
$ convox releases -a nodejs -r demo-rack
ID           STATUS  BUILD        CREATED              DESCRIPTION
RXYHIAAHXOZ          BDBCKOFVPCR  15 seconds from now  env add:FOO
RVTLOODDBZQ  active  BDBCKOFVPCR  3 minutes ago        build 01cddb4eb3

convox releases promote

Promote a specific release. This command allows you to set a specified release as the active one for an application.
$ convox releases promote RXYHIAAHXOZ -a nodejs -r demo-rack
Promoting RXYHIAAHXOZ...
2024-05-01T03:48:13Z system/k8s/atom/app Status: Running => Pending
2024-05-01T03:48:15Z system/k8s/web Scaled up replica set web-546648449c to 1
2024-05-01T03:49:31Z system/k8s/atom/app Status: Updating => Running

Service Management and Scaling

Commands focused on managing services and scaling applications.

convox services

List services associated with an application. This command provides a detailed view of all services that are part of a specified application, including each service's name, domain, and port mappings.
$ convox services -a nodejs -r demo-rack
SERVICE  DOMAIN                                    PORTS
web  443:3001

convox exec

Execute a command in a running container. This command allows you to interact directly with a specific service container within an application, executing commands as if you were inside the container. For example, you can drop into the shell of a service by running convox exec serviceName sh.
$ convox exec web sh -a nodejs -r demo-rack
/usr/src/app # ls
Dockerfile   app.js      convox.yml

convox ps

List processes running for an application. This command provides an overview of all active processes associated with a specified application, displaying details such as process ID, service type, current status, release ID, and the time each process started.
$ convox ps -a nodejs -r demo-rack
ID                    SERVICE  STATUS   RELEASE      STARTED       COMMAND
web-855d47f8f7-5hk79  web      running  RVTLOODDBZQ  1 minute ago

convox ps info

Get detailed information about a specific process. This command provides comprehensive details on an individual process running within an application, including the process ID, application name, command executed, instance details, associated release, service type, start time, and current status.
$ convox ps info web-546648449c-f4k2n -a nodejs -r demo-rack
Id        web-546648449c-f4k2n
App       nodejs
Instance  ip-10-1-96-207.ec2.internal
Service   web
Started   4 minutes ago
Status    running

convox scale

View and adjust the scaling settings for services within an application. This command displays the current scaling configurations for each service associated with an application, including desired and actual running instances, as well as allocated CPU and memory resources. You can also use this command to modify these settings to scale your services up or down based on your operational needs.
convox scale - View the current scaling settings for all services within an application.
$ convox scale -a nodejs -r demo-rack
web      1        1        256  512

convox scale serviceName

Specifically scale a service within an application. This command allows you to finely adjust the scaling settings for a specific service, such as the number of instances (--count), the amount of CPU (--cpu), and memory resources (--memory) allocated. Use this command to optimize resource usage and handle varying loads manually.
$ convox scale web --count 3 -a nodejs -r demo-rack
Scaling web...
$ kubectl get pods -n demo-rack-nodejs
NAME                   READY   STATUS    RESTARTS   AGE
web-546648449c-6vljv   0/1     Pending   0          24s
web-546648449c-dvlp7   0/1     Pending   0          24s
web-546648449c-jbsr4   1/1     Running   0          13m

Advanced Operations and Troubleshooting

Commands that involve more advanced operations like key management, SSH access, running detached processes, and monitoring.

convox certs

List SSL certificates managed by Convox for your applications. This command displays all SSL certificates currently registered with Convox, showing each certificate's ID, the domain it is associated with, and its expiration date.
$ convox certs -r demo-rack
ID               DOMAIN                                    EXPIRES
api-certificate         2 months from now
cert-web  2 months from now

convox instances

List all instances in the current rack along with their metrics. This command provides a detailed view of each instance operating within your rack, including information such as instance ID, status, uptime, number of processes running (PS), CPU usage, memory utilization, and network addresses.
$ convox instances -r demo-rack
ID                            STATUS   STARTED        PS  CPU    MEM     PUBLIC  PRIVATE
ip-10-1-122-207.ec2.internal  running  5 minutes ago  9   2.80%  52.00%
ip-10-1-145-130.ec2.internal  running  5 minutes ago  11  3.16%  54.26%
ip-10-1-214-115.ec2.internal  running  5 minutes ago  11  2.80%  55.23%

convox instances keyroll

Add SSH keys for instances in the rack. This command generates a new SSH key pair and applies it to the instances within the specified rack. If you do not pipe the output, the new private key will be displayed in your terminal. To securely save the key to a file without displaying it in the terminal, use the pipe command shown below to filter and redirect the output to a file named mykey.pem - or any other file name you choose.
$ convox instances keyroll -r demo-rack | grep -A 100 'BEGIN RSA PRIVATE KEY' > mykey.pem

convox instances ssh

SSH into a specific instance using a newly rotated key. After generating and saving your new SSH key with convox instances keyroll, use the key to establish a secure SSH connection to an instance. Specify the instance and key file as shown in the command below. This allows you to directly interact with the instance for troubleshooting and management purposes.
$ convox instances ssh ip-10-1-145-130.ec2.internal --key mykey.pem -r demo-rack
Last login: Wed Apr 24 04:40:21 2024 from
[ec2-user@ip-10-1-145-130 ~]$ exit

convox run

Execute a command in a new process within a service container. This command runs a specified command as a new process in a service container. You can run the command in detached mode using the -d option, which allows the command to operate in the background and frees up the terminal. Additionally, you can specify an entrypoint with -e and set a timeout for the command with -t timeout. This functionality is useful for various operations including administrative tasks, temporary modifications, or maintenance commands.
$ convox run web sleep 500 -d -a nodejs -r demo-rack
Running detached process... OK, web-kpklb

convox logs

View logs for an application. This command streams real-time logs from all components of the specified application, allowing you to monitor ongoing activities and troubleshoot issues as they occur.
$ convox logs -a nodejs -r demo-rack
2024-05-01T03:55:22Z service/web/web-546648449c-f4k2n PING
2024-05-01T03:55:27Z service/web/web-546648449c-f4k2n PING
2024-05-01T03:55:32Z service/web/web-546648449c-f4k2n PING
2024-05-01T03:55:37Z service/web/web-546648449c-f4k2n PING


As you have explored in this guide, mastering the use of Convox commands can significantly enhance your ability to manage and optimize your applications and racks effectively. By familiarizing yourself with the command options and contexts explained throughout this documentation, you are now equipped to navigate the Convox environment with confidence. Remember, the key to effective command usage is understanding when and where to apply them, and always ensuring that your commands are targeting the intended scope. For further details on each command, don't hesitate to use the --help option for on-the-fly assistance. Thank you for following this guide, and we hope it serves you well in managing your Convox deployments seamlessly.

Let your team focus on what matters.