Skip to content

CLI Reference

Jump to bottom
Adam Cooke edited this page Mar 20, 2017 · 9 revisions

The procfile command line tool is your primary way of interacting with Procodile. It handles starting, stopping, restarting as well as providing information about the status of your application. This page outlines each of the commands that are available along with the additional options that they support.

Before get involves in the processes, there's one option that can be passed to all of these methods - --root or -r for short. This specifies the root of your application. If you don't pass one, we will use your current working directory as the root path.

start

The start command will start all your application's processes. If the Procodile supervisor process is not running, it will first start that for you. The supervisor process is designed to remaining running at all times so you shouldn't need to worry about this.

  • -p or --processes - by default all process types will be started, if you'd prefer to only start certain processes you can pass a list here. For example web,worker,cron.
  • -t or --tag - the tag to assign to any new processes started by this action. See the process tagging page for more information about this.

The following options are only available if the supervisor is not already running. If it is running, you'll need to stop it and then restart it with the options you need from below.

  • -f or --foreground - this will keep the Procodile application in the foreground rather than running it in the background. If you CTRL+C while running in the foreground, all processes will be stopped.
  • --clean - this will remove the contents of your pids directory before starting. This avoids the supervisor picking up any old processes and managing them when it shouldn't.
  • --no-respawn - this will disable all respawning of processes managed by Procodile. If a process stops working, it will stay like that until started again.
  • --stop-when-none - when enabled, the supervisor process will be stopped when there are no processes monitored.
  • -x or --proxy - this will enable proxy mode
  • -d or --dev - this is the same as specifying --foreground, --brittle, --proxy and --stop-when-none. It's ideal when you want to run your application in the foreground when developing it because processes with issues won't just be started blindly.
  • --ports - this allows you request that procodile allocates random ports to your processes. You should provide a list of process names that should have allocated ports. For example: --ports=web,websocket.

stop

This will stop your application's processes. By default, the Procodile supervisor process will continue to run in the background and will await your instructions.

  • -p or --processes - by default all process types will be stopped, if you'd prefer to only stop certain processes you can pass a list here. You can stop individual types or instances. For example web.2,worker to stop the web.2 process and all worker processes.
  • -s or --stop-supervisor - when stopping, the supervisor will remain running but if you'd like to stop it when all processes are stopped you can pass this option.
  • --wait - rather than returning immediately, the program will wait until all processes and the supervisor have stopped before exiting.

restart

This will restart your application's processes. This is usually run the most frequently and will likely be used each time you deploy code or make changes to your application code.

When restarting, Procodile will also ensure that the application is running the correct number of processes based on the quantity options specified in your configuration. If there are too many running when you restart, it'll stop them. If there aren't enough, it'll start some more.

  • -p or --processes - by default all process types will be restarted, if you'd prefer to only restart certain processes you can pass a list here. You can restart individual types or instances. For example web.2,worker to restart the web.2 process and all worker processes.
  • -t or --tag - the tag to assign to any new processes started by this action. See the process tagging page for more information about this.

status

This command will display the full status of all processes plus the supervisor process. It includes:

  • A full process list including the status of processes, the time they started, their PIDs, the number of times they have been re-spawned and their tag.
  • A list of active environment variables
  • Details about the supervisor process and your application root directory.

You can pass --json to this method to receive all status information as a JSON hash.

You can pass --simple to this method to receive a simple output about the current state of everything. This is a single word (OK, Issues or NotRunning) followed by a description of the state.

check_concurrency

If you make changes to the quantity of processes in your config files and wish to start/stop processes to match without running a full restart, you can use this method. It will compare the running processes against the quantities desired in the configuration files and start/stop as appropriate.

  • --no-reload - by default, running check_concurrency will reload the configuration before checking. You can pass this option to simply check concurrency against that data in memory from the last time the config was loaded.

reload

If you make changes to your Procfile or Procfile.options files you can push these updates into the running supervisor using the reload command.

  • If you increase or decrease the quantity of processes required, they will be changed the next you start/restart a process or when you run check_concurrency.
  • If you change a command, the old command will continue to run until you next restart.
  • Changes to environment variables will apply next time a process is started.
  • Changes to the restart mode of a process will apply straight away so this will be used on the next restart.
  • Changes to app_name, log_path and pid_root will not be updated until the supervisor is restarted.

kill

It is rare you'll need this command. This will look in your pids directory and send KILL signals to every process mentioned. This is why it's important that the directory is only used for Procodile managed processes.

run

This allows you to execute a command with the environment variables you have configured in your Procfile.options already set. You might use this for invoking a test suite or another one-off command.

procodile run -- bundle exec rake test
procodile run -E test -- bundle exec rake test

console

This runs your configured console_command with your environment set. It's basically the same as run but you don't need to enter the full console command because it's been pre-configured. Refer to configuration on how to set the command.

Clone this wiki locally