Merge pull request #472 from bentayloruk/cli-doc

Improve CLI documentation and prompt messages.

help/commandline.md

@@ -1,3 +1,71 @@
+# FAKE Command Line
+
+**Note:  This documentation is for FAKE.exe version 2.18 or later.**
+
+The FAKE.exe command line interface (CLI) is defined as follows:
+
+`fake.exe [<buildScriptPath>] [<targetName>] [options]`
+
+## Basic Examples
+
+**No arguments:** `fake.exe` (FAKE will try and locate your build script).
+
+**Specify build script only:** `fake.exe mybuildscript.fsx`
+
+**Specify target name only:** `fake.exe clean` (runs the `clean` target).
+
+**Specify build script and target:** `fake.exe mybuildscript.fsx clean`
+
+## `buildScriptPath`
+
+Optional.  The path to your `.fsx` build file.  If not specified, FAKE will pick the first `.fsx` it finds in your working directory (and fail if none exist).
+
+## `targetName`
+
+Optional.  The name of the build script target you wish to run.  This will any target you specified to run in the build script.  
+
+## Options
+
+Options begin with -- (long name) or - (short name).
+
+### `--envvar [-ev] <name:string> <value:string>`
+
+Set environment variable name value pair. Supports multiple. 
+
+### `--envflag [-ef] <name:string>`
+
+Set environment variable flag name to 'true'. Supports multiple.               
+
+### `--logfile [-lf] <path:string>`
+
+Set the build output log file path.                                                   
+
+### `--printdetails [-pd]`
+
+Print details of FAKE's activity.                                                 
+
+### `--version [-v]`
+
+Print FAKE version information.                                                         
+
+### `--fsiargs [-fa] <string>`
+
+Pass args after this switch to FSI when running the build script.  This consumes all arguments after it.  See [F# Interactive Options](http://msdn.microsoft.com/en-us/library/dd233172.aspx) for the fsi CLI details.
+
+Important:  If you use this option, you must include your build script path as one of the fsi args.  For example:
+
+`--fsiargs --debug+ buildscript.fsx someArg1 anotherArg2`
+
+### `--boot [-b] <string>`
+
+Boostrapp your FAKE script.  A bootstrapping `build.fsx` script executes twice (in two stages), allowing you to download dependencies with NuGet and do other preparatory work in the first stage, and have these dependencies available in the second stage.
+
+### `--help [-h|/h|/help|/?]`
+
+Display CLI help.
+
+
+
 # Running FAKE targets from the command line
 
 For this short sample we assume you have the latest version of FAKE in *./tools/*. Now consider the following small FAKE script:

src/app/FAKE/Cli.fs

@@ -13,8 +13,8 @@ type FakeArg =
     | [<AltCommandLine("-lf")>] LogFile of string
     | [<AltCommandLine("-pd")>] PrintDetails
     | [<AltCommandLine("-v")>] Version
-    | [<Rest>] FsiArgs of string
-    | [<Rest>] Boot of string
+    | [<Rest>] [<AltCommandLine("-fa")>] FsiArgs of string
+    | [<AltCommandLine("-b")>] [<Rest>] Boot of string
     interface IArgParserTemplate with
         member x.Usage = 
             match x with
@@ -24,7 +24,7 @@ type FakeArg =
             | PrintDetails _ -> "Print details of FAKE's activity."
             | FsiArgs _ -> "Pass args after this switch to FSI when running the build script."
             | Version _ -> "Print FAKE version information."
-            | Boot _ -> "TBC"
+            | Boot _ -> "Boostrapp your FAKE script."
 
 /// Return the parsed FAKE args or the parse exception.
 let parsedArgsOrEx args = 
@@ -37,9 +37,13 @@ let parsedArgsOrEx args =
 /// Prints the FAKE argument usage.
 let printUsage () =
     printfn @"
-    fake.exe [<scriptPath>] [<targetName>] [switches]
+    fake.exe [<scriptPath>] [<targetName>] [options]
 
-    Switches:
+    scriptPath: Optional.  Path to your FAKE build script.  If not specified, FAKE will use the first .fsx file in the working directory and fail if none exists.
+    
+    targetName: Optional.  Name of the target you wish to run.  This will override the target you specifed to run in the build script.
+
+    Options:
     %s" (UnionArgParser<FakeArg>().Usage())
 
 type Args = { Script: string option; Target: string option; Rest: string [] }