CLI Reference

The procodile command line tool is the primary way to interact with your application. It starts and stops processes, reloads configuration, reports status, and manages scheduled jobs. This page outlines each of the commands that are available along with the additional options that they support.

All commands accept:

--root (or -r) to specify the application root. It may be either an absolute path or a relative path. --procfile PATH to specify the Procfile path. It may be an absolute path, a relative path, or a different filename in the current directory.

--root controls the application root and other root-based paths, such as pid_root, the default log_path, sock_path, child-process chdir, and other root-relative paths. --procfile controls which Procfile is read. The matching options files are always derived from the Procfile path.

If both are omitted, Procodile uses the current working directory and Procfile.

These two options can be used together. The examples below show the resulting paths in common cases.

Example: only --root

• procodile -r /my_app1
• application root: /my_app1
• Procfile path: /my_app1/Procfile
• options path: /my_app1/Procfile.options
• local options path: /my_app1/Procfile.local

Example: only --procfile

• procodile --procfile PFile
• Procfile path: <current-working-directory>/PFile
• application root: <current-working-directory>
• options path: <current-working-directory>/PFile.options
• local options path: <current-working-directory>/PFile.local

Example: both --root and --procfile

• procodile -r /my_app1 --procfile /my_app2/PFile
• application root: /my_app1
• Procfile path: /my_app2/PFile
• options path: /my_app2/PFile.options
• local options path: /my_app2/PFile.local

In other words, --root and --procfile may point at different directories. Procodile allows this, but it is usually clearer to keep them aligned.

start Command

procodile start starts processes from the current configuration. If the supervisor is not already running, it will be started first. The supervisor process is designed to remain running at all times so you shouldn't need to worry about this.

• -d, --dev — this is the same as specifying --foreground, --no-respawn, --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.
• -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, --tag TAGNAME — assign a tag to newly started processes. See Process Tagging.
• --ports PROCESS:PORT,... — assign explicit ports to processes when they are started. For example: --ports=web:3001,websocket:3002.

To target processes, use -p/--processes. Extra positional arguments such as procodile start app1 are rejected.

The following options only apply when the supervisor itself is being started:

• -f, --foreground — this will keep the Procodile application in the foreground rather than running it in the background. Pressing CTRL+C stops the supervisor and all managed processes.
• --clean — remove the PID 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.
• --no-supervisor — do not start the supervisor if it is not already running.
• --no-processes — start only the supervisor. Do not start any processes.
• --stop-when-none — stop the supervisor when there are no processes being monitored.
• -x, --proxy — enable proxy mode. See Ports & Proxy.
• --env-file [ENV_FILE] — load and override the supervisor's environment variables from an env file. If no file is provided, .env is used. See Environment Files.

Start and Scheduled Processes

Scheduled processes are not executed immediately by start. Starting them enables their schedules and allows them to run at the next matching cron time.

If you run start -p some_scheduled_job, the job is enabled again, but it is still not executed immediately.

stop Command

procodile stop stops running processes. By default, the supervisor keeps running in the background.

• -p, --processes a,b,c - 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, --stop-supervisor — stop the supervisor after all managed processes have stopped.
• --wait — wait until the supervisor has stopped before returning. This is typically used together with --stop-supervisor.

To target processes, use -p/--processes. Extra positional arguments such as procodile stop app1 are rejected.

Stopping Scheduled Processes

For scheduled processes:

• job refers to the scheduled task itself. Running stop -p job only disables future runs.
• job.3 refers to a specific currently running instance, You can get the instance name from procodile status. Stopping a currently running scheduled instance, for example with procodile stop -p job.3, will also disable any future runs of that scheduled task.

Stop and Removed Processes

If a process has been removed from the Procfile but is still running, stop -p process_name is still allowed. This is the supported way to terminate a removed-but-still-running process.

restart Command

procodile restart restarts configured processes and also ensures the configured quantity is correct.

By default, Procodile sends TERM, waits for the process to stop, and then starts a replacement. This is the default and safest restart mode. Other modes can help support zero-downtime deployments. See Restart Modes.

• -p, --processes a,b,c — 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, --tag TAGNAME — assign a tag to newly started processes. See the Process Tagging page for more information about this.

To target processes, use -p/--processes. Extra positional arguments such as procodile restart app1 are rejected.

Restart and Scheduled Processes

Scheduled processes are handled differently:

• restart -p scheduled_job does not execute the job immediately.
• Instead, it reloads and re-enables the schedule for that job.
• restart -p scheduled_job.3 restarts the currently running scheduled instance while also re-enabling future scheduling if it was previously disabled.
• A full restart skips scheduled processes entirely. They are not restarted as normal long-running processes.

Restart and Removed Processes

Restart only operates on process names that still exist in the current configuration.

If a process has been removed from the Procfile, restart -p that_process will fail with a message explaining that the process has been removed and can only be stopped.

During a full restart, removed-but-still-running processes are skipped and reported as such in the command output.

status Command

procodile status prints the current state of the supervisor and all known processes.

It includes:

• process configuration details
• instance status, PIDs, and respawn counts
• environment information
• supervisor information
• runtime issues, when present

procodile status --simple prints a condensed single-line summary:

• OK
• Runtime Issues
• Issues
• NotRunning

Additional output formats:

• --json — machine-readable JSON
• --json-pretty — pretty-printed JSON

Status and Scheduled Processes

Scheduled processes include schedule-specific fields such as:

• Schedule
• Last Started At
• Last Finished At
• Last Exit Status
• Last Run Duration

They do not display daemon-only fields such as quantity or restart mode.

Status and Proxy Information

Status output includes supervisor-level proxy state and process-level proxy listener settings:

• Proxy Enabled — whether the supervisor was started with proxy mode enabled
• Proxy Listener — the configured proxy address and port for a process

Status and Removed Processes

If a process has been removed from the Procfile but is still running, status will show that explicitly.

check_concurrency Command

procodile check_concurrency compares the running process counts against the configured quantities and starts or stops normal long-running processes as needed.

It does not drive scheduled processes.

• --no-reload — skip reloading configuration before checking.

log Command

procodile log shows the main Procodile log by default, or a specific process log when --process is provided.

• -f — follow the log and print new lines as they are written.
• -n LINES — show the last LINES lines.
• -p, --process PROCESS — show the log for the given process instead of the main Procodile log.

reload Command

procodile reload reloads the Procfile and the options files into the running supervisor.

Current behavior is:

• command changes take effect for future starts and restarts
• if the supervisor is already running with proxy mode enabled, process-level proxy listener changes take effect immediately
• changes to env-file values and configured env values apply to future process starts and restarts
• restart mode changes apply to the next restart
• scheduled process changes are applied immediately
• fixed invalid schedules can be restored with reload

If a process is removed from the Procfile, Procodile marks it as removed. If it is still running, it remains visible in status output until it is stopped.

For environment precedence and reload behavior, see Environment Files.

For proxy behavior, see Ports & Proxy.

kill Command

procodile kill is an emergency command. It reads PIDs in your pids directory and sends KILL to those processes. This is why it's important that the directory is only used for Procodile managed processes.

run or exec Command

procodile run executes a one-off command with the configured environment already loaded. run and exec are equivalent.

procodile run -- bundle exec rake test
procodile exec -- bundle exec rake db:migrate

console Command

procodile console runs your configured console_command with the application environment loaded. See Configuration for details.