---
title: "Gateway Command-line Utility - gwcmd"
---

# Gateway Command-line Utility - gwcmd

> The Gateway Command-line Utility provides a list of commands you can use to perform specific functions in the Gateway. The Gateway Command-line Utility or **gwcmd** provides basic commands, such as resetting the main password, changing the Gateway's port, or restarting the Gateway.

Invoking **gwcmd** can only be done from command line, so you'll need to utilize a command line interface of some sort (Power Shell, Terminal, etc). Because gwcmd is a file sitting in the Gateway's installation directory, these commands can only ever be invoked from where the Gateway is installed. Furthermore, interacting with gwcmd requires administrative privilege. 

The gwcmd file sits at the root of the Gateway's installation directory. See the [Installing and Upgrading Ignition](getting-started\installing-and-upgrading\installing-and-upgrading.md) page for more details on default installation directories.

![gwcmd Command Prompt Window](gwcmd-command-prompt-window.png)

:::caution A note to our legacy users...
Older versions of Ignition featured a visual Gateway Control Utility or GCU that could start and stop the Ignition service. This visual element of the GCU, as well as the ability to start and stop the service have since been removed in Ignition 8.0. For more information on starting or stopping the service, please see [Use the Command-line Utility to Start or Stop the Gateway](#use-the-command-line-utility-to-start-or-stop-the-gateway) below.

More information on the older version of the GCU can be found in [Deprecated Features](versioned_docs\version-deprecated\intro.md) of the user manual.
:::

## Command-line Utility Options
The Gateway command-line utility supports Windows, Linux, and Mac OS platforms. The '**gwcmd**' only runs on the same machine as the Ignition Gateway and requires administrative privileges.

To run the Gateway Command-line Utility, open a command shell and type: `gwcmd <option>`. This example uses the Windows platform:
1. Open the **Command Prompt** with admin privileges. In the search bar, enter **cmd** then right click next to the **Command Prompt** to select **Run as administrator**.

    ![Command-line Utility Options Step 1](command-line-utility-options-step-1.png)

2. Any time you run any of the Gateway command utility options, you need to run them from the directory that Ignition is installed in. The default install directory is: **C:/Program Files/Inductive Automation/Ignition**.
3. From here, you can enter any of the command options listed in the table below. This example is of a Gateway backup using the following command: **gwcmd -b "C:/Gateway Backups/Backup_190108.gwbk"**.

    :::caution Using spaces in a file path
    When using spaces in a file path name, use quotation marks around the full path name, as shown in the example above. Forward or backward slashes can be used to separate folders. The file path includes the disk name, folder path, and file name.
    :::

4. The above command created a Gateway Backup on the C drive, in the Gateway Backups folder with a file name of Backup_190108.gwbk. The image below shows all the commands used in Steps 2 and 3. 

    ![Command-line Utility Options Step 4](command-line-utility-options-step-4.png)

### Use the Command-line Utility to Start or Stop the Gateway
One of the common uses for the Command-Line Utility is to start or stop the Gateway.

#### Windows
Ignition's installation directory contains `start-ignition.bat` and `stop-ignition.bat`, which can start or stop the service. Example:
```
C:\Program Files\Inductive Automation\Ignition> start-ignition.bat
```

However, you can also use Windows native service commands to control the running state of the Gateway:
```
net start ignition
```
```
net stop ignition
```

#### Linux
You can control the service using the `ignition.sh` script. It can be called with the `start` and `stop` parameters to perform the relevant operations.

For example:
```
/usr/local/bin/ignition/ignition.sh start
```

Additionally, you can use native terminal commands to start or stop the service:
```
service Ignition-Gateway start
```
```
service Ignition-Gateway stop
```

#### Mac OS X
You can access the service from the install directory using the `ignition.sh` script. On a typical Mac install using the dmg installer, the full command (without a custom location specified) is the following: 
```
/usr/local/ignition/ignition.sh start
```

## Command-line Utility 'gwcmd' Options
The following table lists all available '**gwcmd**' options.

| Options | Description |
|---|---|
| `-a,-–activate <license-key>` | Creates an `activation_request.txt` file that can be used to request a `license.ipl` file from the Inductive Automation website. You must specify the license key to use for activation. The `activation_request.txt` file is saved in the current directory. Note that eight-character license keys cannot be activated through gwcmd. |
| `-b,--backup <new filepath>` | Downloads a Gateway backup `.gwbk` file and saves the file to the specified path. The path can be either an absolute path or a relative path.  If another `.gwbk` file with the same name already exists, you will be prompted whether it is OK to overwrite the file. You can override with the `-y` option to force the file to always be overwritten. |
| `-c,--clearks` | Clears the gateway's SSL/TLS setup. The gateway's SSL/TLS connector will be immediately shut down. |
| `-d, --disabled` | Use with the `--restore flag` to disable all items after gateway restoration and restart. |
| `-e, --exportks <new filepath>` | Exports the gateway's SSL KeyStore in PKCS #12 format and saves to the specified path. |
| `-f, --exportpk <new filepath>` | Exports the private key from the gateway's SSL KeyStore in PEM format and saves to the specified path. |
| `-g,--reloadks` | Reloads the Gateway's SSL KeyStore from disk. Any update to the KeyStore will be automatically applied to any new connections. |
| `-h,--help` | Shows the usage for this command. |
| `-i,--info` | Retrieves server status and port information from the Gateway if it is running. |
| `-k,--port <new port>` | Changes the Gateway http port. |
| `-l,--sslport <new port>` | Changes the Gateway https port. |
| `-m, --skip-gateway-contact` |  Use with the `--restore` flag to skip contacting a running gateway and stage the restore file directly. |
| `-n, --nocrypt` | Add to the export private key command to not encrypt the private key. |
| `-o,--name <new gateway name>` | Specifies a Gateway name while restoring a backup. Additionally, the `-y` command now skips prompts asking for a Gateway name override. |
| `-p,--passwd` | Enables a password reset command, which will allow you to create a temporary user that can access the gateway again. Requires a gateway restart to take effect. See [Gateway Password Reset](#gateway-password-reset) below. |
| `-r,--restart` | Restarts the Gateway. |
| `-s,--restore <backup file path>` | Restores from a Gateway backup, using the file specified at the path. |
| `-t,--tdump` | Performs a thread dump in the Gateway and prints the dump to the command-line. |
| `-u,--unactivate` | Creates an `unactivation_message.txt` file that you can use to unactivate a license via the Inductive Automation website. The `unactivation_message.txt` file is saved in the current directory. |
| `-w,--uselicense <license.ipl path>` | Applies a `license.ipl` file that was downloaded from the Inductive Automation website. You must supply the location of the `license.ipl` file. If it is in the current directory, use `license.ipl` for the location. |
| `-y,--promptyes` | Automatically answers `yes` to any prompt that may appear in the above commands, such as permission to overwrite an existing file. |
| `-z, --timeout <seconds>` |  Number of seconds to wait for a backup to be generated. Starting in 8.1.17, the default timeout value is 60 seconds. In older versions, the default timeout value is 30 seconds. |

## Gateway Password Reset

If you can no longer access the Gateway (due to, say, a forgotten password), you can use the **-p** command to cause a password reset. During a password reset, instead of just changing the initial user's password, a partial commissioning process will trigger upon the next Gateway restart (which can be accomplished with the **-r** command), allowing you to create a new user that can access the Gateway. From there you'll be able to address any issues that prevented you from using your normal credentials.

![Gateway Password Reset](gateway-password-reset.png)

However when performing this process, several things will happen to the Gateway:
* During commissioning, you'll be asked to provide a user name and password for a new user. 
* A "temp" [user source](platform\security\classic-authentication-strategy\classic-authentication-strategy.md) is created.
* The user you provided credentials for will be added to the "temp" user source. 
* The new user will be assigned the role "Administrator".
* A "temp" Ignition Identity Provider will be created. The "temp" user source will be assigned as the provider backing the Identity Provider. 
* On the [General Gateway Security Settings](platform\security\gateway-general-security-settings\gateway-general-security-settings.md), the following properties will be changed:
    * **System Identity Provider** will be set to the "temp" user source.
    * **Designer Authentication Strategy** will be set to the "Classic" strategy.
    * **System User Source** will be set to the "temp" user source.
    * **Designer Role(s)** will be set to the "Administrator" Security Level.
    * **Gateway Config Permissions** will be set to the "Administrator" Security Level.

Thus, if you trigger a password reset and are able to use your normal credentials again, you'll want to make sure you change the values on the modified Gateway Security Settings to their property value. Also, you'll likely want to remove the "temp" user source and Identity Providers.