Octeth CLI Tool

The Octeth CLI tool helps you manage your Octeth installation from the command line. You'll find it at /opt/octeth/cli/octeth.sh on your server. This tool gives you control over containers, processes, logs, and other system operations.

All commands follow this pattern:

/opt/octeth/cli/octeth.sh <command>

TIP

You can run /opt/octeth/cli/octeth.sh help at any time to see a complete list of available commands.

Docker Container Management

These commands control the main Octeth containers that run your email marketing platform.

Starting Octeth containers:

/opt/octeth/cli/octeth.sh docker:up

This starts all Octeth containers. Use this command when you first set up Octeth or after stopping the containers.

Stopping Octeth containers:

/opt/octeth/cli/octeth.sh docker:down

This stops and removes all Octeth containers. Your data remains safe in Docker volumes.

Checking container status:

/opt/octeth/cli/octeth.sh docker:status

This shows you which containers are running and their current state. Use this to verify everything is working properly.

Restarting containers:

/opt/octeth/cli/octeth.sh docker:restart

This restarts all Octeth containers. Use this when you need to apply configuration changes.

Backend Process Management

Backend processes handle important tasks like sending emails and processing campaigns. These commands help you manage them.

Starting backend processes:

/opt/octeth/cli/octeth.sh backend:start

This starts all background workers that process your email campaigns and handle automation. Run this after starting Docker containers.

Stopping backend processes:

/opt/octeth/cli/octeth.sh backend:stop

This stops all background workers. Use this when you need to perform maintenance or updates.

Checking backend status:

/opt/octeth/cli/octeth.sh backend:status

This shows you which background processes are running. Use this to verify your email campaigns are being processed.

Restarting backend processes:

/opt/octeth/cli/octeth.sh backend:restart

This restarts all background workers. Use this when processes aren't responding or after configuration changes.

Send Engine Management

The send engine handles the actual delivery of your emails. You can scale it up or down based on your sending volume.

Starting the send engine:

/opt/octeth/cli/octeth.sh sendengine:start

This starts one send engine instance. The send engine connects to your SMTP servers and delivers emails.

Scaling the send engine:

/opt/octeth/cli/octeth.sh sendengine:scale 5

This adjusts the number of send engine instances. Increase this number when sending large campaigns to speed up delivery.

Checking send engine status:

/opt/octeth/cli/octeth.sh sendengine:status

This shows how many send engine instances are running and their current state.

Viewing send engine logs:

/opt/octeth/cli/octeth.sh sendengine:logs -f

This displays live logs from the send engine. Use this to monitor email delivery in real-time.

TIP

Start with one send engine instance and scale up only when needed. Each instance uses additional server resources.

Log Management

Logs help you understand what's happening in your Octeth system and troubleshoot issues.

Viewing live logs:

/opt/octeth/cli/octeth.sh logs:tail

This displays live error logs from Octeth. The logs update automatically as new entries appear.

Clearing log files:

/opt/octeth/cli/octeth.sh logs:reset

This clears all error log files. Use this to start fresh when troubleshooting or after resolving issues.

Creating a log snapshot:

/opt/octeth/cli/octeth.sh logs:snapshot

This creates a backup of all current log files. Use this before clearing logs or when you need to share logs with support.

Checking log file sizes:

/opt/octeth/cli/octeth.sh logs:size

This shows how much disk space your log files are using.

Fixing log file permissions:

/opt/octeth/cli/octeth.sh logs:fix-permissions

This fixes permission issues that prevent Octeth from writing to log files. Run this if you see permission denied errors.

Environment and Configuration

These commands help you view and modify your Octeth configuration settings.

Viewing a configuration value:

/opt/octeth/cli/octeth.sh env:get MYSQL_HOST

This displays the current value of a specific setting.

Changing a configuration value:

/opt/octeth/cli/octeth.sh env:set MYSQL_HOST 'localhost'

This updates a configuration setting. Restart the affected containers after making changes.

Searching configuration:

/opt/octeth/cli/octeth.sh env:search MYSQL

This finds all configuration settings that match your search term.

Viewing system configuration:

/opt/octeth/cli/octeth.sh config:list

This displays all active configuration values loaded by Octeth.

Getting a specific configuration value:

/opt/octeth/cli/octeth.sh config:get APP_URL

This displays the current value of a specific configuration constant.

Migrating from an old configuration file:

/opt/octeth/cli/octeth.sh config:migrate /path/to/old/config.inc.php

This analyzes an old monolithic config.inc.php file and generates a migration report. Use this when upgrading from an older Octeth installation that used a single configuration file instead of the current modular system (environment files + config/global/*.php).

The report shows:

• Environment variables to set — Settings that differ from new defaults, grouped by config file. Copy these values into your .oempro_env file.
• Array constant differences — Changes in const arrays like OEMPRO_SERVICE_HOSTNAMES. Edit the corresponding const_*.php files in config/global/.
• Data structures — Large data structures (bounce patterns, custom field presets, TinyMCE settings, DNS templates) that are now in dedicated config files. Review these only if you customized them.
• Dynamic values — Constants that referenced variables or other constants. Each one includes guidance on where to configure it in the new system.
• Obsolete settings — Old constants that no longer exist, with explanations of what replaced them.
• Matching defaults — Constants that already match the new default values. No action needed for these.

Example:

/opt/octeth/cli/octeth.sh config:migrate data/config.inc.old.php

TIP

This command is read-only. It does not modify any files — it only analyzes and reports. You apply the changes manually based on the report.

WARNING

Always restart the appropriate containers after changing configuration values to apply your changes.

Database Operations

These commands help you manage your Octeth database and run maintenance tasks.

Running database updates:

/opt/octeth/cli/octeth.sh migrate

This applies database updates needed for new Octeth versions. Always run this after upgrading Octeth.

Opening the ClickHouse database:

/opt/octeth/cli/octeth.sh clickhouse:client

This opens an interactive session with the ClickHouse database where Octeth stores analytics data.

Running a ClickHouse query:

/opt/octeth/cli/octeth.sh clickhouse:query "SHOW TABLES"

This runs a single query against the ClickHouse database and displays the results.

Switching MySQL configuration:

/opt/octeth/cli/octeth.sh mysql:switch-config standard

This changes MySQL performance settings. Options include development, small, standard, and highperf. Choose based on your server's resources.

DANGER

Switching MySQL configuration will temporarily stop your database and all backend processes. Only do this during a maintenance window.

Viewing MySQL slow query log:

/opt/octeth/cli/octeth.sh mysql:slow-log

This displays slow database queries that may be affecting performance. By default, it shows the last 50 queries. Use this when diagnosing performance issues or troubleshooting slow campaign sending.

You can specify how many lines to display:

/opt/octeth/cli/octeth.sh mysql:slow-log --lines=100

TIP

If you see queries taking several seconds to complete, contact Octeth support. They can help optimize your database performance.

Cache Management

Octeth uses caching to improve performance. These commands help you manage cached data.

Viewing cached data:

/opt/octeth/cli/octeth.sh cache:get 'subscriber_count_123'

This displays the value stored in cache for a specific key.

Listing cache keys:

/opt/octeth/cli/octeth.sh cache:list 'subscriber_*'

This shows all cache keys matching your pattern.

Removing cached data:

/opt/octeth/cli/octeth.sh cache:forget 'subscriber_count_123'

This deletes a specific cached value. Octeth will recreate it when needed.

Clearing multiple cache entries:

/opt/octeth/cli/octeth.sh cache:flush 'subscriber_counts_*'

This removes all cache entries matching your pattern. Use this carefully as it can temporarily slow down your system.

Viewing cache statistics:

/opt/octeth/cli/octeth.sh cache:stats

This shows information about your cache system including memory usage.

Installation and Setup

These commands help you install and configure Octeth.

Starting a fresh installation:

/opt/octeth/cli/octeth.sh install:start

This guides you through setting up a new Octeth installation. Only use this on a fresh server or after running install:reset.

Resetting your installation:

/opt/octeth/cli/octeth.sh install:reset

This removes all Octeth data and configuration, returning your server to a clean state.

DANGER

This command permanently deletes all your data, campaigns, subscribers, and settings. Use only when you want to start completely fresh.

Unattended installation (CI, automation, AI agents)

install:start and install:reset are interactive by default. Add --yes (or -y) to run them without any prompt at all — useful from a provisioning script, a CI job, or an AI coding agent that has no terminal to type into.

In non-interactive mode a missing required value is never turned into a prompt: the command prints which flag is missing and exits with a non-zero status, so an automated run can never hang waiting on input.

Unattended reset:

/opt/octeth/cli/octeth.sh install:reset --yes

Unattended development install:

/opt/octeth/cli/octeth.sh install:start --dev --yes

Unattended production-style install. Write the admin password and the license key to mode-600 files first, so neither appears on the command line:

(umask 077 && read -rsp 'Admin password: ' pw && printf '%s\n' "$pw" > /root/octeth-admin.pw)
(umask 077 && read -rsp 'License key: ' key && printf '%s\n' "$key" > /root/octeth-license)

/opt/octeth/cli/octeth.sh install:start --yes --accept-eula \
  --app-url https://mailer.example.com/ \
  --admin-name "Jane Doe" \
  --admin-email jane@example.com \
  --admin-username jane \
  --admin-password-file /root/octeth-admin.pw \
  --license-key-file /root/octeth-license

The license key is the signed key from your license page at my.octeth.com, for the --app-url domain. Delete both files once the installation has finished.

Flag	Purpose
-y, --yes	Suppress every prompt. Missing or invalid values are fatal, never re-prompted.
--accept-eula	Accept the EULA without prompting. Required together with --yes unless --dev is used (--dev accepts it automatically).
--force	Continue when configuration files from an earlier installation are present. It only overrides the abort — it deletes nothing.
--app-url <url>	Application URL, http:// or https://.
--admin-name <name>	Administrator full name.
--admin-email <email>	Administrator email address.
--admin-username <username>	Administrator username: 3-32 characters, starts with a letter, letters/digits/underscore.
--admin-password-file <path>	Read the administrator password from the first line of a file. Use - to read it from standard input (requires --yes). Recommended.
--admin-password <password>	Administrator password on the command line. See the warning below.
--license-key-file <path>	Read the Octeth license key from a file (the one-line key or the BEGIN/END block), or from standard input with - (requires --yes).
--license-key <key>	Octeth license key: the signed key for the --app-url domain from my.octeth.com. It is verified once the containers start, before it is written to .oempro_env, and an invalid key stops and rolls back the installation with the reason. A short OCT-... key is refused before anything is installed. May be empty: the installation then runs with the Community limits until a key is set on Settings > License. With --yes, leaving out every license-key source means an empty key, not a prompt.

Without a license-key option, the interactive installer asks for the key. Paste the one-line key or the whole BEGIN/END block, or press Enter to leave it empty. A short key is refused and the question is asked again.

The installer also reads these environment variables when the matching flags are not given:

Variable	Purpose
OCTETH_ADMIN_PASSWORD	Administrator password.
OCTETH_LICENSE_KEY	Octeth license key, as --license-key. May be empty.

Precedence is --admin-password, then --admin-password-file, then OCTETH_ADMIN_PASSWORD, and the same order for the license key. Passing both flags for the same value is an error, and only one of the two file flags can read standard input.

Values given with these flags go through exactly the same validation as the interactive prompts. An invalid value always exits non-zero rather than asking again.

WARNING

--admin-password puts the password on the command line, where it is visible in the process list (ps) and in shell history. Use --admin-password-file instead. An environment variable keeps the password out of ps, but other processes running as the same user can still read it, so a file is the safer choice.

The installer never prints a secret, so its output is safe to keep in a log. A supplied admin password is shown as (set, not shown), the license key shows only its last four characters, and the generated CADDY_DOMAIN_VERIFY_CODE is written to .oempro_env without being displayed. If you accept the auto-generated admin password in an interactive install, it is shown only when the output goes to a terminal. Otherwise, for example when the output is piped to tee, it is saved to .oempro_admin_password (mode 600) in the installation directory. Delete that file after you have stored the password. install:reset also removes it.

TIP

--force does not delete anything. To install onto a genuinely clean slate, run install:reset --yes first, then install:start.

Service passwords (MySQL, RabbitMQ, ClickHouse, Supervisor) are always generated automatically and cannot be set with a flag.

Installing CLI tools globally:

/opt/octeth/cli/octeth.sh cli:install

This makes the Octeth CLI tool available from anywhere on your server. After running this, you can use octeth instead of /opt/octeth/cli/octeth.sh.

System Health and Testing

These commands help you verify that Octeth is working correctly.

Checking system health:

/opt/octeth/cli/octeth.sh health:check

This runs a comprehensive check of all Octeth services and displays their status. Use this to verify everything is working properly.

Setting up the test database:

/opt/octeth/cli/octeth.sh test:setup

This prepares a test database for running automated tests. Only needed if you're testing new features or troubleshooting.

Running tests:

/opt/octeth/cli/octeth.sh test:run all

This runs all automated tests to verify Octeth functionality. Mainly used by support staff or when troubleshooting complex issues.

System Utilities

These commands perform maintenance tasks and fix common issues.

Fixing file permissions:

/opt/octeth/cli/octeth.sh permissions:fix

This corrects file and folder permissions that may prevent Octeth from working properly. Run this if you see permission errors. It sets the data/ directories to 0777, and gives system/storage and system/bootstrap/cache owner root, group www-data, mode 2775 on directories and 0664 on files (before v6.0.1 these two were also set to 0777).

Installing dependencies:

/opt/octeth/cli/octeth.sh composer:install

This installs or updates required software packages. Run this after upgrading Octeth or when instructed by support.

Regenerating authentication tokens:

/opt/octeth/cli/octeth.sh regenerate-auth-tokens

This fixes authentication issues where users can't log in. Use this if users report login problems after password changes.

TIP

Most day-to-day operations only require the backend:start, backend:stop, and backend:status commands. The other commands are typically used during setup, upgrades, or troubleshooting.