One-off Commands
Convox allows you to execute one-off commands on your App. This can be used for starting a shell for debugging purposes or running administrative commands such as database migrations.
Spawning a new Process
Using convox run will start a new Process of the specified
Service on your current Rack and run your command inside the new Process.
Running Interactively
Running an interactive process will start a Process and connect your local terminal so that you can run commands and see output:
$ convox run web bash
root@web#
Running Detached
Running detached is useful for long-running tasks that you don't want to be disrupted:
$ convox run web bin/cleanup-database --detach -a my-app
Running detached process... OK, web-s43xf
convox logs -a my-app
convox ps stop web-s43xf -a my-app
The output of detached Processes will appear in the application logs
The two follow-up lines go to standard error. Add --wait to hold the command open until the Process finishes and exit with its own exit code, which suppresses those lines and lets a CI step fail when the command does:
$ convox run web bin/migrate --detach --wait -a my-app
Running detached process... OK, web-s43xf
See Detached Runs for --wait, --retain, and --id.
Running a command in an existing Process
Using convox exec will run a command inside an existing Process.
This can be useful for debugging a running Process.
$ convox ps
ID SERVICE STATUS RELEASE STARTED COMMAND
web-6844dc6f45-9wdss web running RABCDEFGHI 14 minutes ago bin/web
web-6844dc6f45-mj9mp web running RABCDEFGHI 14 minutes ago bin/web
$ convox exec web-6844dc6f45-9wdss bash
root@web#
You can also use a Service name with convox exec to select
a random Process of that Service.
$ convox exec web bash
root@web#
See Also
- CLI run Reference for the full
convox runcommand reference - CLI exec Reference for running commands in existing processes
- CLI ps Reference for inspecting a Process and its exit status
