Building and Publishing Targets Using the Command Line

Commands and Arguments

To build output from the command line, you need to write commands containing various arguments. The commands always start with the word “madbuild,” followed by the necessary arguments and values.

Here are the available arguments associated with madbuild.

How to Build All Targets

1. Open Notepad (to create and save a batch file) or open your command prompt (to run a command immediately).

2. Type the path to the Flare.app folder where you installed Flare, and press ENTER.

   cd\Program Files\MadCap Software\MadCap Flare 17\Flare.app

   Note Alternatively, you can use cd c:\Program Files\[rest of the path] instead of cd\Program Files\[rest of the path].

3. Type the following and press ENTER on your keyboard (entering the path to your project in place of the section in angle brackets):

   madbuild -project [project]

   A log file is generated and saved automatically at the root level of the output folder for that target, whether or not there are errors or warnings. See Opening Build Logs.

   Note If there are spaces anywhere in your path or project name, you need to use quotation marks around it.

   Example If you have a Flare project called "FictionSoftPro" that you have stored in a folder of the same name at the root level of the C: drive, you can type this:

   Copy

   madbuild -project c:\fictionsoftpro\fictionsoftpro.flprj

   Example If you have a project called "FictionSoftPro" that you have stored in a folder named "My Projects" (with a space) at the root level of the C: drive, you would type this:

   Copy

   madbuild -project "c:\my projects\fictionsoftpro.flprj"

   If you are using the command prompt window, the targets in that project generate immediately, and the output files are copied to the Output subfolder in your main project folder.

   If you are creating a batch file in Notepad, it might look something like this:

   

How to Build a Specific Target

1. Open Notepad (to create and save a batch file) or open your command prompt (to run a command immediately).

2. Type the path to the Flare.app folder where you installed Flare, and press ENTER.

   cd\Program Files\MadCap Software\MadCap Flare 17\Flare.app

   Note Alternatively, you can use cd c:\Program Files\[rest of the path] instead of cd\Program Files\[rest of the path].

3. Type the following and press ENTER on your keyboard (entering the path to your project and the name of the target in place of the sections in square brackets):

   Copy

   madbuild -project [project] -target [target name]

   A log file is generated and saved automatically at the root level of the output folder for that target, whether or not there are errors or warnings. See Opening Build Logs.

   Note The default location for targets is in the root Targets folder in the Project Organizer. However, you can create subfolders and place different targets in different folders (see Creating Subfolders). If you do this, make sure you include the subfolder name in your command. You can do this by typing the name of the subfolder, followed by a slash, and then the name of the target (i.e., madbuild -project [project] -target [mysubfoldername/mytargetname]).

   Note If there are spaces anywhere in your path or project name, you need to use quotation marks around it.

   Example You have a project called "FictionSoftPro" that you have stored in a folder of the same name at the root level of the C: drive. If you want to build only the target named "Beginner" in that project, you can type this:

   Copy

   madbuild -project c:\fictionsoftpro\fictionsoftpro.flprj -target Beginner

   Example If the project is located in a folder called "my projects" (with a space), you would type this:

   Copy

   madbuild -project "c:\my projects\fictionsoftpro.flprj" -target Beginner

   Example If the target is named "Beginner Online Help" (with spaces between words), you would type this:

   Copy

   madbuild -project "c:\my projects\fictionsoftpro.flprj" -target "Beginner Online Help"

   If you are using the command prompt window, the targets in that project generate immediately, and the output files are copied to the Output subfolder in your main project folder.

   If you are creating a batch file in Notepad, it might look something like this:

   

How to Build a Batch Target

1. Open Notepad (to create and save a batch file) or open your command prompt (to run a command immediately).

2. Type the path to the Flare.app folder where you installed Flare, and press ENTER.

   cd\Program Files\MadCap Software\MadCap Flare 17\Flare.app

   Note Alternatively, you can use cd c:\Program Files\[rest of the path] instead of cd\Program Files\[rest of the path].

3. Type the following and press ENTER on your keyboard (entering the path to your project and the name of the target in place of the sections in angle brackets):

   Copy

   madbuild -project [project] -batch [batch target name]

   A log file is generated and saved automatically at the root level of the output folder for that target, whether or not there are errors or warnings. See Opening Build Logs.

   Note The default location for batch targets is in the root Targets folder in the Project Organizer. However, you can create subfolders and place different batch targets in different folders (see Creating Subfolders). If you do this, make sure you include the subfolder name in your command. You can do this by typing the name of the subfolder, followed by a slash, and then the name of the batch target (i.e., madbuild -project [project] -batch [mysubfoldername/mybatchtargetname]).

   Note If there are spaces anywhere in your path or project name, you need to use quotation marks around it.

   Example You have a project called "FictionsoftPro" that you have stored in a folder of the same name at the root level of the C: drive. If you want to build the batch target named "MyBatchTarget" in that project, you can type this:

   Copy

   madbuild -project c:\fictionsoftpro\fictionsoftpro.flprj -batch MyBatchTarget

   Example If the project is located in a folder called "my projects" (with a space), you would type this:

   Copy

   madbuild -project "c:\my projects\fictionsoftpro.flprj" -batch MyBatchTarget

   Example If the batch target is named "My Batch Target" (with spaces between words), you would type this:

   Copy

   madbuild -project "c:\my projects\fictionsoftpro.flprj" -batch "My Batch Target"

   If you are using the command prompt window, the targets in that project generate immediately, and the output files are copied to the Output subfolder in your main project folder.

   If you are creating a batch file in Notepad, it might look something like this:

   

How to Publish Directly to MadCap Central

As an alternative to building a target on MadCap Central, you can publish output directly to Central from the local Flare project. By “publish,” we mean copying your output files to Central, not making that output “live,” which would make it visible to the general public. You would still need to use Central to make that output accessible to end users. Also, you must be associated with the project on Central and have the “Run/Schedule Builds” permission. See MadCap Central and Flare.

1. Open Notepad (to create and save a batch file) or open your command prompt (to run a command immediately).

2. Type the path to the Flare.app folder where you installed Flare, and press ENTER.

   cd\Program Files\MadCap Software\MadCap Flare 17\Flare.app

   Note Alternatively, you can use cd c:\Program Files\[rest of the path] instead of cd\Program Files\[rest of the path].

3. Type the following and press ENTER on your keyboard (entering the correct information in place of the sections in square brackets):

   Copy

   madbuild -project [project] -centralUsername [email address] -centralPassword [password] -target [target]

   Note If there are spaces anywhere in your path or project name, you need to use quotation marks around it.

   Example Your email address is bsmith@fictionsoft.com, and your Central password is R!ffraff22. You have a project called "FictionSoftPro" that you have stored in a folder of the same name at the root level of the C: drive. If you want to publish the target named "Beginner" to Central, you can type this:

   Copy

   madbuild -project c:\fictionsoftpro\fictionsoftpro.flprj -centralUsername bsmith@fictionsoft.com -centralPassword R!ffraff22 -target Beginner

   Example If the project is located in a folder called "my projects,” and the target is named "Beginner Online Help" (with spaces between words), you would type this:

   Copy

   madbuild -project "c:\my projects\fictionsoftpro.flprj" -centralUsername bsmith@fictionsoft.com -centralPassword R!ffraff22 -target "Beginner Online Help"

Passing Credentials in Madbuild

If you are using the command line to publish output from Flare to another location, you can include credentials (i.e., user names, passwords) in your madbuild commands. You can put credential fields directly in a madbuild command, or you can put them in a separate JSON file, which is easier to read.

Passing credentials in madbuild can be done for:

• FTP

• MadCap Central

• Salesforce®

• ServiceNow®

• SFTP

• Zendesk

https://[hosturl]/[directory]

https://portal.madcapcentral.com/

https://login.salesforce.com/services/oauth2/authorize

https://test.salesforce.com/services/oauth2/authorize

https://[instance].service-now.com/oauth_token.do

https://[subdomain].zendesk.com/oauth/authorizations/new

madbuild -project "C:\MyProjectFolder\MyProject.flprj" -target "MyTargetName" 
-credentials  "{\"https://url.com/dir\": {\"username\":\"myusername\", \"password\": 
\"mypassword\"}, \"https://anotherurl.com/dir\": {\"username\":\"myusername\", 
\"password\":\"mypassword\"} }"

madbuild -project "C:\CoolProject\CoolProject.flprj" -target "HelpSystem" 
-credentials  "{\"https://docs.fictionsoft.com/flareoutputs/helpsystem\": 
{\"username\":\"ldobler\", \"password\": \"sayanything\"} }"

madbuild -project "C:\CoolProject\CoolProject.flprj" -target "HelpSystem" 
-credentials  "{\"https://portal.madcapcentral.com/\": 
{\"username\":\"breynolds@fictionsoft.com\", \"password\": \"Bandit77!\"} }"

madbuild -project "C:\CoolProject\CoolProject.flprj" -target "HelpSystem" 
-credentials  "{\"https://login.salesforce.com/services/oauth2/authorize\": 
{\"username\":\"pete@fictionsoft.com\", \"password\": 
\"HeDoneRunnoft!Fj4bGioaIWS9OPakVCedIjk2\"} }"

madbuild -project "C:\CoolProject\CoolProject.flprj" -target "HelpSystem" 
-credentials  "{\"https://docs52164.service-now.com/oauth_token.do\": 
{\"username\":\"steve.zissou\", \"password\": \"CompanyBondStooge!\"} }"

madbuild -project "C:\CoolProject\CoolProject.flprj" -target "HelpSystem" 
-credentials  "{\"https://myappserver05:0101/flareoutputs/helpsystem\": 
{\"username\":\"jlebowski\", \"password\": \"thedudeabides\"} }"

madbuild -project "C:\CoolProject\CoolProject.flprj" -target "HelpSystem" 
-credentials  "{\"https://docs-fictionsoft.zendesk.com/oauth/authorizations/new\": 
{\"username\":\"westley@fictionsoft.com\", \"password\": \"AsYouWish!\"} }"

madbuild -project "C:\CoolProject\CoolProject.flprj" -target "HelpSystem" 
-credentials  "{\"https://docs.fictionsoft.com/flareoutputs/helpsystem\": 
{\"username\":\"ldobler\", \"password\": \"sayanything\"}, 
\"https://login.salesforce.com/services/oauth2/authorize\": 
{\"username\":\"pete@fictionsoft.com\", \"password\": 
\"HeDoneRunnoft!Fj4bGioaIWS9OPakVCedIjk2\"} }"

{
    "https://url.com/dir" : {
     "username": "myusername",
     "password": "mypassword"
    },
    
    "https://anotherurl/dir": {
     "username": "myusername",
     "password": "mypassword"
    }
}

madbuild -project "C:\MyProjectFolder\MyProject.flprj" -target "MyTargetName" 
-credentials-file "C:\MyCredentialsFolder\MyCredentialsFile.json"

{
  "https://docs.fictionsoft.com/flareoutputs/helpsystem" : {
  "username": "ldober",
  "password": "sayanything"
 },
 
 "https://portal.madcapcentral.com/" : {
 "username": "breynolds@fictionsoft.com",
 "password": "Bandit77!"
 },
  
  "https://login.salesforce.com/services/oauth2/authorize" : {
  "username": "pete@fictionsoft.com",
  "password": "HeDoneRunnoft!Fj4bGioaIWS9OPakVCedIjk2"
 },
  
  "https://docs52164.service-now.com/oauth_token.do" : {
  "username": "steve.zissou",
  "password": "CompanyBondStooge!"
 },
 
  "https://myappserver05:0101/flareoutputs/helpsystem" : {
  "username": "jlebowski",
  "password": "thedudeabides"
 },
 
  "https://docs-fictionsoft.zendesk.com/oauth/authorizations/new" : {
  "username": "westley@fictionsoft.com",
  "password": "AsYouWish!"
 }
}

madbuild -project "C:\CoolProject\CoolProject.flprj" -target "HelpSystem" 
-credentials-file "C:\My-JSON-Files\DestinationCredentials.json"

Batch Files and Task Scheduler

If you are creating a batch file, save the Notepad file to any location you like on your computer. When you do this, type .bat as the extension at the end of the file name (e.g., MyBatchFile.bat). At any time you like, you can generate the output simply by double-clicking the batch file. You can also use a tool to schedule the batch file to run.

For example, complete the following steps if using the Windows 10 Task Scheduler utility.

1. In the Windows search field, type Task Scheduler and press ENTER.
2. Click Action > Create Basic Task.
3. In the Create Basic Task Wizard, give the task a name and click Next.
4. Using the next couple of pages of the wizard, choose when you wan the batch to run (e.g., daily, starting at 2 a.m.). Click Next until you get to the Action page.
5. Click Start a program, and click Next.
6. Click Browse. Then find and double-click the batch file you created.
7. Click Next.
8. Click Finish.

ERRORLEVEL Global Variable

If you generate output using the command line, Flare sends a value to the command line's ERRORLEVEL global variable. This value indicates the success, or lack of success, of the compilation and/or publishing process. To see this value, type ECHO %ERRORLEVEL% at the command prompt after the compilation finishes. Only one value can be shown at a time.

Codes listed below in red indicate that the output did not compile at all. For the other codes, there may be issues (e.g., missing linked file), but the output is still able to finish compiling.

What’s Noteworthy?

What’s Next?

After you build targets using the command line, you can do the following:

• Viewing Output
• Testing Output