Home → Installation and Upgrade Manual → HelpSpot 4 - Installation & Setup → HelpSpot 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.

General

Linux:

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

Windows:

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:

• install - A command to install/configure HelpSpot
• update - A command to run updates for HelpSpot from 4.0.0+
• attachments:tofile - A command to convert attachments from the database to the filesystem
• convert:base - A command to start the update HelpSpot from version 3 to 4
• convert:request - A command to complete the update from HelpSpot version 3 to 4
• recover:requests - If the conversion of requests fail silently and there are missing requests, this command can be used to recover them
• db:exists - Check if a HelpSpot database exists
• search:config - Generate a Sphinx Search configuration file
• request:delete - Delete a single request by ID
• request:delete-spam - Delete all requests marked as spam ithout training the spam filter.
• report:logs - Export a CSV file of your Helpspot request event logs to your data/documents/ directory.
• spam:clean - optimize the Bayesian filter database to improve spam filtering performance.

Install

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.

• --agree=yes - "Yes" to say you agree to the terms and conditions
• --name='Your Full Name' - The administrator user's full name (first and last)
• --admin-email=admin@email.com - The administrator user's email address
• --password=your_password - The administrator user's passwor
• --company='Your Company' - The company as displayed publicly
• --timezone='America/New_York' - The timezone to use within HelpSpot
• --customer-id=123456 - Your customer ID
• --license-file=/path/to/license-file.txt - The path to the license file, which should be saved to the server before running the server
• --notification-email=notification@email.com - The email used for sending notifications
• --ask-smtp=yes - Add in your outgoing email settings, using the following "smtp" options. Use "no" to configure this later, the smtp configuration is optional
• --smtp-host=somehostname - (Conditional on "--ask-smtp") The outgoing email server
• --smtp-port=1234 - (Conditional on "--ask-smtp") The outgoing email port
• --smtp-user=some@user.com - (Conditional on "--ask-smtp") The outgoing email user name
• --smtp-password=some_password - (Conditional on "--ask-smtp") The outgoing email password
• --smtp-protocol=none - (Conditional on "--ask-smtp") The connection protocol. One of "none" (no security), "ssl" or "tls"

Update

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.

• --language=english.us - Defaults to the "english.us" language

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

Attachments

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.

• --path=data/documents - The path (relative to the "hs" command location or absolute) where the files should be saved to. This location must be writable by the user running the 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.

Convert

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:

• convert:base - Creates the database tables in the new database, and converts the "base" (not Request-related) data into the new database from the old database.
• convert:requests - Converts Requests and all related data from the old database to the new database. This can go back in time a specific amount of days, or do all requests. This command can be run more than once without fear of duplicating data.

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

• source database - the old database from which data will be converted and copied into the new, UTF8-Capable database
• destination database - the new, UTF8-Capable database which data will be converted and copied into.

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.

convert:base

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:

• --db-type=mysql - The source database type you are using. Note that this is the old database, not the new UTF-8 capable database. The default is "mysql". Valid types are: mysql, mssql, or postgres_helpspot
• --db-host=localhost - The hostname to use to access the source database. The default is "localhost".
• --db-user=some_username - The username used to access the source database
• --db-pass=some_password - The password used to access the source database
• --db-name=some_db_name - The name of the source database
• --from-encoding=iso-8859-1 - Optional parameter, the character encoding used to convert data from. Character set encoders need to know what character set they are encoding from in order to properly encode to other character sets such as UTF-8. The default for HelpSpot prior to version 4 was "iso-8859-1", which is also commonly referred to as "latin1"
  • This script will guess the character set if it's not explicitly set via the --from-encoding parameter. It gets the character set from the cHD_CHARSET variable in the HS_Settings table in the source database.
• --schema-only=yes - Set the database schema only, don't copy and data
• --data-only=yes - Copy data only, assuming the schema is already in place (via --schema-only=yes complete previously)

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.

convert:requests

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:

• --db-type=mysql - The source database type you are using. Note that this is the old database, not the new UTF-8 capable database. The default is "mysql". Valid types are: mysql, mssql, or postgres_helpspot
• --db-host=localhost - The hostname to use to access the source database. The default is "localhost".
• --db-user=some_username - The username used to access the source database
• --db-pass=some_password - The password used to access the source database
• --db-name=some_db_name - The name of the source database
• --from-encoding=iso-8859-1 - Optional parameter, the character encoding used to convert data from. Character set encoders need to know what character set they are encoding from in order to properly encode to other character sets such as UTF-8. The default for HelpSpot prior to version 4 was "iso-8859-1", which is also commonly referred to as "latin1"
  • This script will guess the character set if it's not explicitly set via the --from-encoding parameter. It gets the character set from the cHD_CHARSET variable in the HS_Settings table in the source database.
• --days-back=90 - The number of days of requests to go back in time. The default is 90 days. Use "all" to copy all requests. Note that HelpSpot will not be usable until this command completes running at least once, upon which it updates HelpSpot's internal setting to the correct version, making HelpSpot able to reach the admin login page.

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.

• --data-path — The path where the sphinx index files will be generated.

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