HomeInstallation and Upgrade ManualHelpSpot 4 - Installation & SetupHelpSpot Commands

11. HelpSpot Commands

HelpSpot 4.0.0 now comes with a command-line tool, which has some tools to help you automate a few things. The functionality of this is limited for now, but will likely expand with added features.



The hs command installed with HelpSpot is the command line utility. On Linux servers, you can run it using PHP:

# List the available commands and options:
$ php hs


On Windows, you need to run the hs command using the PHP that comes with HelpSpot using Cmd or PowerShell, and let it know which configuration file to use:

> C:\'Program Files (x86)'\helpspot\php\php.exe -c C:\'Program Files (x86)'\helpspot\php\php.ini C:\'Program Files (x86)'\helpspot\helpspot\hs

It might be easier to first "change directory" into the HelpSpot directory so these file paths are shorter:

> cd C:\'Program Files (x86)'\helpspot\helpspot
> ..\php\php.exe -c ..\php\php.ini .\hs

For both Linux and Windows, running hs without any parameters will simply list out the available commands.

Here are the commands available for HelpSpot:


HelpSpot can be installed via the command line instead of using the web interface. This might be useful for automating the install of HelpSpot.

The simplest way to use this command is to download the HelpSpot files, and then run the "install" command. This will ask you for the information it needs to complete the installation.

php hs install

This asks you all the information needed to install HelpSpot. You can also pass the command all the needed information directly, allowing the install to be automated. The following are the flags/options you can set:

Note that you can run `php hs install -h`, which will show you the available flags/options to use for the install command.


You can use this tool to update HelpSpot as well. This will be useful when versions greater than 4.0.0 is released. For example, you can run this command when updating from version 4.0.0 to 4.0.1.

Once you update the HelpSpot files on your server, you can run the update command:

php hs update

This will gather the old version and new version of HelpSpot and run any scripted or database updates needed. This will not install the latest HelpSpot file - that step must still be done outside of this command line tool.

This command is much simpler than the install command, as it will determine the needed information from available system information.


This command will allow you to save your file attachments from the database (the default location prior to HelpSpot version 4) to your server file system. This command can only be used after you convert your database from version 3 to version 4, due to differences in the database structure.

This command will delete file attachment data from your database. We highly suggest backing up your database before running this command.

To begin saving database attachments to the filesystem, run the following command.

php hs attachments:tofile

This will ask you the file path to save your attachments. The default value is the data/documents directory, which HelpSpot 4 comes with for this purpose.

Note that you can run `php hs attachments:tofile -h`, which will show you the available flags/options to use for the install command.

This command may take a considerable amount of time, depending on the size of your database. The command can safely be run multiple times, including if it stops on failure or timeout.


The convert commands are used specifically to update HelpSpot from Version 3 to Version 4. HelpSpot requires a conversion of the current data from its current character set to UTF-8 (in order to support multiple language alphabets and characters properly). This process can take a relatively long time and should be run via the command-line, which has no time limit like an update from within the browser may have.

Before updating from Version 3 to Version 4, you must create a new, empty database that is setup for UTF-8 character sets. The new database credentials should be added into the config.php file. However, keep a note of the old credentials, as the conversion process requires access to both databases.

There are two commands for conversion:

Because the conversion requires two databases, it's useful to set the terms used:

The destination database credentials must be set in the config.php file, while the source database credentials will be asked for in while using the convert commands.


The convert:base command should be run first. This command will do two things:

  1. Create the needed database schema for HelpSpot version 4 in the new database
  2. Copy all database data, except for that related to Requests, into the new database

Running this command will ask you for the necessary input.

php hs convert:base

You can also provide it the needed information head of time:

This script takes about 10 minutes to run on a 2GB database. See the "Speed Tips" section within the Overview chapter for more information.

Custom Database Schema

Some HelpSpot customers add new tables or adjust the schema of the standard HelpSpot database. For those customers, the convert:base command needs to be handled in a way that allows you to add custom tables, columns or schema adjustments before database data is copied to the new database.

To accomplish this, the convert:base command can be run in two parts via the --schema-only and --data-only options. The workflow will look like this:

  1. Run convert:base --schema-only, which will update the new database with the new schema, but won't copy and data
  2. Add any new tables, columns, or schema adjustments as needed
  3. Run convert:base --data-only, which will copy data from the old database to the new database. This should copy custom columns and handle data from adjusted existing columns. However, it will not copy new tables that are not part of HelpSpot standard database installation. Copying of any additional custom tables created will need to be done by the system administrator.


The convert:requests command is used to convert Requests and all related data. Requests have a lot of related data, so each request is converted and copied one by one from the source database to the destination database.

php hs convert:requests

This command will save requests starting with the newest first. This let's you quickly get up and running by converting the latest requests (for example, the last 90 days worth of requests). Then, if HelpSpot support is critical enough, your staff can continue working within HelpSpot while the command is run again to complete the remaining requests in the system.

Since many systems have been up and running for years, some systems will have hundreds of thousands of database rows of requests and request history. The use case above (copying the last 90 days of requests and then the remaining in the background while the system is in active use) is for such cases.

On a database of about 2GB of size with about 30,000 requests and 285,000 items of request history, the conversion process took about 20-30 minutes.

The options for this command are similar to the convert:base:

This command tracks requests that have been successfully copied to the new database. This means you can run the command multiple times safely. Note that the --days-back option is relative to "now", the time when you run the command. If you run the command "now", going back 90 days, it will copy the last 90 days of requests. Running the identical request immediately a second time will result in no requests being copied, as the last 90 days worth of requests have already been copied. To go back further than 90 days, increase the number of days set, or use "all": --days-back=all

php hs convert:requests --days-back=all

Recover Requests

The recover:requests command is only used on a v3 to v4 upgrade when the database is being converted. If the conversion of requests fail silently and there are missing requests, this command can be used to recover them. This command is limited to 2100 requests on SQLServer because of SQLServer's bind limit.

Database Exists

The db:exist command determines if a populated HelpSpot database already exists based on the credentials used in the config.php file. This is a utility function, used by the Windows installer primarily, but available to all customers. This command may be useful to those automating an install or update of HelpSpot.

php hs db:exists

Search Configuration

The search:config command will generate a configuration file for SphinxSearch to use. It takes the database credentials and information such as custom fields from the database (using the database credentials set in config.php) and generates the configuration file. This configuration file contains the needed information to index Customer data, Requests, Knowledge Books and Forums into the Sphinx Search engine index.

This command will save the sphinx.conf file to the server-writable "data" directory found within the HelpSpot installation.

php hs search:config

There is a single option for this command that allows you to specify the location where the sphinx index files reside.

For details on how to use this generated sphinx.conf file, see our extended documentation on installing Sphinx Search on Debian/Ubuntu servers or installing Sphinx Search on RedHat/CentOS servers.

Request: Delete

The request:delete command deletes a request by ID. You pass it the --id= option with your request ID.

php hs request:delete --id=12400

Request: Delete Spam

The request:delete-spam command deletes all requests in HelpSpot's spam queue. It will not train the spam filter. By default it asks for confirmation, you can bypass this with the --force flag.

php hs request:delete-spam

Report: Logs

The report:logs command will export a CSV file of your helpspot request event logs to your data/documents/ directory.


php hs report:logs

Spam: Clean

The spam:clean command optimize the Bayesian filter database to improve spam filtering performance. Running this every 7 days is recommended for larger installations.


php hs spam:clean

hs config:convert

Converts the config.php file to a .env file. The default action will overwrite any existing .env. --dump Displays the result of processing the config.php file instead of overwriting the .env.

php hs config:convert

This page was: Helpful | Not Helpful