CLI Commands

Command-line interface tools for ForkBB installation and maintenance

Overview

ForkBB provides a command-line interface (cli.php) for performing administrative tasks such as installing the forum software and managing the email queue. All commands are executed through PHP’s CLI SAPI.

CLI commands must be run from the console using PHP CLI. They will not work when accessed through a web browser.

Basic Usage

All CLI commands follow this basic syntax:

php cli.php [command] [options]

Available Commands

install

Installs ForkBB from the command line with all necessary configuration parameters.

This command is only available when config/install.php exists and config/main.php does not yet exist.

Syntax

php cli.php install \
  --installlang=LANGUAGE \
  --dbtype=DATABASE_TYPE \
  --dbhost=DB_HOST \
  --dbname=DB_NAME \
  --dbuser=DB_USERNAME \
  --dbpass=DB_PASSWORD \
  --dbprefix=DB_PREFIX \
  --username=ADMIN_LOGIN \
  --password="ADMIN_PASSWORD" \
  --email=ADMIN_EMAIL \
  --title="FORUM_TITLE" \
  --descr="FORUM_DESCRIPTION" \
  --baseurl=FORUM_URL \
  --defaultlang=DEFAULT_LANGUAGE \
  --defaultstyle=DEFAULT_STYLE \
  --cookie_domain=COOKIE_DOMAIN \
  --cookie_path=COOKIE_PATH \
  --cookie_secure=COOKIE_SECURE

Parameters

installlang · string · required

Installation language. Options: en, es, fr, ru

dbtype · string · required

Database type. Options: mysql_innodb, mysql, pgsql, sqlite

dbhost · string · required

Database host (e.g., localhost or 127.0.0.1)

dbname · string · required

Database name

dbuser · string · required

Database username

dbpass · string · required

Database password

dbprefix · string · required

Database table prefix (can be empty)

username · string · required

Administrator username

password · string · required

Administrator password. Must be at least 16 characters or contain multiple words.

email · string · required

Administrator email address

title · string · required

Forum title

descr · string

Forum description. Use EMPTY for no description or provide text in quotes.

baseurl · string · required

Forum base URL (e.g., https://forum.example.com)

defaultlang · string · required

Default language for the forum. Options: en, es, fr, ru

defaultstyle · string · required

Default theme/style. Default: ForkBB

cookie_domain · string

Cookie domain (can be empty)

cookie_path · string

Cookie path. Default: /

cookie_secure · string

Whether to use secure cookies. Options: 1 (HTTPS only) or 0 (any)

Example

1. Navigate to the ForkBB directory

   cd /path/to/forkbb/app
   
2. Run the installation command

   php cli.php install \
     --installlang=en \
     --dbtype=mysql_innodb \
     --dbhost=localhost \
     --dbname=forkbb \
     --dbuser=forkbb_user \
     --dbpass="secure_password" \
     --dbprefix=fbb_ \
     --username=admin \
     --password="Strong Admin Password 123" \
     --email=[e-mail] \
     --title="My ForkBB Forum" \
     --descr="A community discussion forum" \
     --baseurl=https://forum.example.com \
     --defaultlang=en \
     --defaultstyle=ForkBB \
     --cookie_domain= \
     --cookie_path=/ \
     --cookie_secure=1
   
3. Verify installation

   If successful, the command will output Ok. Any errors will be displayed with detailed messages.

Use quotes around parameters that contain spaces or special characters.

send_mail

Processes the email queue and sends pending emails. This command is designed to be run periodically via cron or task scheduler.

This command requires config/main.php to exist (i.e., ForkBB must be installed).

Syntax

php cli.php send_mail [--log=LEVEL]

Parameters

log · string

Logging level:

• 1 - Log only when tasks are completed or the script cannot obtain an exclusive lock
• 2 - Log every execution regardless of result

Example

1. Process email queue with minimal logging

   php cli.php send_mail --log=1
   
2. Set up a cron job for automated processing

   # Process email queue every 5 minutes
   */5 * * * * /usr/bin/php /path/to/forkbb/app/cli.php send_mail --log=1
   

How It Works

1. The command retrieves pending emails from the queue
2. Each email is processed through the Mail service
3. The queue uses exclusive locking to prevent concurrent execution
4. Completed tasks are logged based on the --log parameter
5. The result indicates the number of tasks completed (or false if locked)

Use --log=1 for cron jobs to minimize log entries while still capturing important events.

test

A diagnostic command that writes a test entry to the ForkBB log to verify CLI functionality.

This command requires config/main.php to exist (i.e., ForkBB must be installed).

Syntax

php cli.php test

Example

php cli.php test

This command outputs Ok on success and logs the following information:

• PHP version
• PHP SAPI (always cli)
• Execution time
• User information (guest user)

Use this command to verify that the CLI environment is properly configured before running other commands.

Error Handling

Invalid Command

If you specify a command that doesn’t exist or isn’t available in the current context:

Invalid command. [command_name]

Application Not Configured

If neither config/main.php nor config/install.php exists:

Application is not configured

Command Availability

• install: Only available when ForkBB is not yet installed
• test and send_mail: Only available when ForkBB is fully installed

Best Practices

Use absolute paths

When setting up automated tasks (cron jobs), always use absolute paths to the PHP binary and cli.php script:

/usr/bin/php /var/www/forkbb/app/cli.php send_mail --log=1

Secure your credentials

When running the install command, ensure that your shell history doesn’t capture sensitive data. Consider using environment variables or configuration files for sensitive parameters.

Monitor log files

Enable logging for send_mail operations to track email delivery and troubleshoot issues:

php cli.php send_mail --log=2

Test before automating

Before setting up cron jobs, manually test commands to ensure they work correctly in your environment.

Troubleshooting

Permission denied errors

Ensure the PHP CLI binary has execute permissions and the script is readable:

chmod +x cli.php

Database connection failures

Verify that your database credentials are correct and the database server is accessible from the command line environment.

Email queue not processing

Check that:

• The database connection is working
• The mail configuration in config/main.php is correct
• The send_mail command has proper file system permissions
• No other process has locked the queue

Related Resources

Installation Guide

Complete installation instructions including web-based setup

Configuration

Learn about ForkBB configuration options

Database Documentation

Database connection and query management

Container Service

Understanding the dependency injection container