Lesson 7

Using the Command-Line Tool

Back to S100: System Installation and Maintenance

Lesson 7: Using the Command-Line Tool

In this lesson, you will learn about creating an Acumatica ERP instance and performing maintenance tasks on the instance by using the command-line tool.

Acumatica ERP Command-Line Tool: General Information

In Acumatica ERP, you can deploy a new application instance and perform database and application maintenance tasks by using the command-line tool. This topic provides an overview of how you can use the Acumatica ERP command-line tool instead of the Acumatica ERP Configuration wizard.

Learning Objectives

  • Become familiar with the Acumatica ERP command-line tool and its syntax
  • Review some examples of using command-line commands to deploy instances and perform maintenance tasks by using the Acumatica ERP command-line tool
  • Deploy an out-of-the-box Acumatica ERP instance from a configuration file by using the Acumatica ERP command-line tool

Applicable Scenario

You may need to learn how to use the Acumatica ERP command-line tool if you are a system administrator who prefers to use command-line commands to deploy a new instance and to perform some maintenance tasks without using the Acumatica ERP Configuration wizard.

The Acumatica ERP Command-Line Tool The Acumatica ERP command-line tool is an executable file with the ac.exe name. By default, ac.exe is located in the folder on the computer that has Acumatica ERP installed, which is C:\Program Files (x86)\Acumatica ERP\Data. When you run ac.exe, you supply a set of command-line parameters, where each parameter must be presented in the following format.

  • parameter:"parameter value"
    When you pass a command-line command to the Acumatica ERP command-line tool, you should use the following syntax.
    ac.exe -f|-file:"path to configuration file" -cm|-configmode:"main scenario"-s|-dbsrvname:"server name" -sw|-dbsrvwinauth:"True|False"-u|-dbsrvuser:"username" -p|-dbsrvpass:"user password"-d|-dbname:"database name" -n|-dbnew:"True|False"-b|-dbupdate:"True|False" -dm|-dbmode:"Regular|Template|Demo"-dz|-dbsize:"database size in GB" -ds|-dbskip:"True|False"-dc|-dbshrink:"True|False" -i|-iname:"instance name"-io|-ioldname:"old instance name" -h|-ipath:"instance directory"-is|-vmsize:"Small|Medium|Large|ExtraLarge" [-it|-trumbprint:"X.509 thumbprint"]-w|-swebsite:"Web site name" Lesson 7: Using the Command-Line Tool | 78
    -v|-svirtdir:"virtual directory" -po|-spool:"application pool"-a|-sactions:"AnonymousUser|SelectedUser"-k|-suser:"username" -m|-spass:"user password"-dw|-dbwinauth:"True or False" -dn|-dbnewuser:"True|False"-du|-dbuser:"username" -dp|-dbpass:"user password"-cs|-securemode:"True|False" -c|-company:"ci|CompanyID=company ID; cp|ParentID=parent company IDcv|Visible=True;ct|CompanyType=True; cn|LoginName:username; cd|Delete:True" -op|-output:"Normal|Quiet|Forced"
    All parameter values in the command-line commands are case-sensitive and must be enclosed in quotation marks. Each parameter for the command line also has a short form that you can use instead of the full parameter name. If you have specified a parameter more than once in a command line, the last parameter value will be used. You can run ac.exe in one of three modes:
  • Command-line: Parameters are passed to ac.exe from the command line.
  • Batch: The path to the configuration file with parameters is passed to ac.exe from the command line.
  • Mixed: Some parameters are passed to ac.exe through the configuration file, while other parameters are passed from the command line. In this mode, command-line parameters have priority over those specified in the configuration file. For details about possible parameters and their values, see Acumatica ERP Command-Line Tool: Possible Parameters and Values.

Deployment of an Instance by Using the Acumatica ERP Command-Line Tool You can use a configuration file to deploy an Acumatica ERP instance with the Acumatica ERP command-line tool. You can create the configuration file with the command-line commands automatically by running the Acumatica ERP Configuration wizard. For details, see Acumatica ERP Command-Line Tool: To Deploy an Instance by Using the Configuration File.

You can also deploy an instance manually by using the command-line commands that you pass to ac.exe, as shown in the following examples:

  • ac.exe -configmode:"NewInstance" -dbsrvname:"GP" -dbname:"JPMorgan"
  • company:"CompanyID=1;CompanyType=;LoginName=;"
  • company:"CompanyID=2;CompanyType=;ParentID=1;Visible=Yes; LoginName=JPMorgan;"
  • iname:"JP Morgan" -ipath:"C:\Program Files\Program Folder\JP Morgan\"
  • swebsite:"Default Web Site" -svirtdir:"JPMorgan" -spool:"JPMorgan"
  • sactions:"SelectedUser" -suser:"GP\Administrator"
  • ac.exe -cm:"NewInstance" -s:"SM" -d:"InstanceDB" -c:"ci=1;"
  • c:"ci=2;cp=1;ct=Demo;cv=True;cn=Company;" -i:"Instance"
  • h:"C:\Program Files (x86)\Program Folder\Instance" -w:"Default Web Site"
  • v:"Instance" -po:"Classic .NET AppPool" -a:"AnonymousUser"
         The command in this example also creates an application instance and uses the short forms of the
     command-line parameters.

Maintenance of an Instance by Using the Command-Line Commands You can use the following examples of command-line commands, which you pass to ac.exe to perform some maintenance tasks in Acumatica ERP. The following command updates an existing database.

ac.exe -configmode:"DBMaint" -dbsrvname:"SM" -dbnew:"False" -dbname:"DotNet4"

Lesson 7: Using the Command-Line Tool | 79

  • dbupdate:"True"
    The following command updates an existing application instance.
    ac.exe -cm:"UpgradeSite" -i:"Instance"
    The following commands can be used to switch on full logging mode and save full logs of instance updates in the Logs folder of the Acumatica ERP installation folder:
  • Short parameter name: ac.exe -fl:"Yes"
  • Full parameter name: ac.exe -fulllog:"Yes" For details about full logging mode, see Instance Deployment: Creation of an Instance.

Acumatica ERP Command-Line Tool: To Deploy an Instance by Using the

Configuration File

The following activity will walk you through the process of preparing a configuration file by using the Acumatica ERP Configuration wizard. You will then deploy an Acumatica ERP instance from this configuration file by using the Acumatica ERP command-line tool.

Story

Suppose that you are the system administrator of your company and you need to deploy an out-of-the-box Acumatica ERP instance from a configuration file by using the command-line tool.

Process Overview

In this activity, you will create a configuration file by using the Acumatica ERP Configuration wizard. Then you will deploy an out-of-the-box Acumatica ERP instance from this configuration file by using the command-line tool.

System Preparation

Before you begin performing the step of this activity, you should do the following:

  • Make sure that you have completed the Acumatica ERP Installation On-Premises: To Install the Acumatica ERP Configuration Wizard prerequisite activity.
  • Make sure that a command-line utility has been installed on your computer.
                    You can use Command Prompt, the built-in command-line utility for Microso Windows.

Step 1: Creating the Configuration File by Using the Acumatica ERP Configuration Wizard To create a configuration file with the settings of an Acumatica ERP instance, do the following:

  1. On the Start menu, click Acumatica ERP Configuration to open the Acumatica ERP Configuration wizard.
  2. On the wizard pages, specify the settings to deploy an out-of-the-box instance, as described in Instance Deployment: To Deploy an Out-of-the-Box Instance. In the Instance Name box on the Instance Configuration page, specify the name of the instance: AcumaticaCLT.
  3. On the Confirmation of Configuration page, click Save Configuration to save the configuration data. Lesson 7: Using the Command-Line Tool | 80
       By default, the name of the configuration file is InstallConfig.xml.
  4. Save the InstallConfig.xml on your computer.

Step 2: Deploying an Instance by Using the Command-Line Tool To deploy an out-of-the-box Acumatica ERP instance with the settings specified in the prepared configuration file, do the following:

  1. On the Start menu, run as administrator a command-line utility installed on your computer.
  2. In the command line, enter a command to navigate to the folder where the Acumatica ERP Configuration wizard is installed and ac.exe is stored. You can use the cd path to ac.exe command, where path to ac.exe is the path to the executed file, which is specified in the following format.
        cd C:\Program Files (x86)\Acumatica ERP\Data\
  3. In the command line, enter ac.exe -f:"path to the configuration file" to start the execution of the configuration file and the deployment of the instance. path to the configuration file is the path to the configuration file, which is specified in the following format.
        ac.exe -f:"C:\Program Folder\InstallConfig.xml"
  4. Press Enter. Wait until the deployment of the AcumaticaCLT instance has been completed.
  5. Open the Acumatica ERP Configuration wizard.
  6. On the Welcome page of the Acumatica ERP Configuration wizard, click Perform Application Maintenance. The Application Maintenance page opens.
  7. In the Installed Sites table, make sure that the AcumaticaCLT instance is in the list.
  8. Select the AcumaticaCLT instance, and click Launch. You can access the instance and enable the features for the first time to make sure that it is an out-of-the- box instance, as you have specified in the settings of the configuration file. (For more information about these tasks, see Instance Deployment: To Deploy an Out-of-the-Box Instance and Instance Deployment: To Enable Features and Activate the License.) Lesson 8: Uninstalling of Acumatica ERP | 81