CmdArgs: Easy Command Line Processing

by Neil Mitchell

CmdArgs is a library for defining and parsing command lines. The focus of CmdArgs is allowing the concise definition of fully-featured command line argument processors, in a mainly declarative manner (i.e. little coding needed). CmdArgs also supports multiple mode programs, for example as used in darcs.

This document explains how to write the "hello world" of command line processors, then how to extend it with features into a complex command line processor. Finally this document gives three samples, which the cmdargs program can run. The three samples are:

  1. hlint - the HLint program.
  2. diffy - a program to compare the differences between directories.
  3. maker - a make style program.

For each example you are encouraged to look at it's source (see the darcs repo, or the bottom of this document) and run it (try cmdargs hlint --help). The HLint program is fairly standard in terms of it's argument processing, and previously used the System.Console.GetOpt library. Using GetOpt required 90 lines and a reasonable amount of duplication. Using CmdArgs the code requires 30 lines, and the logic is much simpler.

Hello World Example

The following code defines a complete command line argument processor:

{-# LANGUAGE DeriveDataTypeable #-}
module Sample where
import System.Console.CmdArgs

data Sample = Sample {hello :: String}
              deriving (Show, Data, Typeable)

sample = mode $ Sample{hello = def}

main = print =<< cmdArgs "Sample v1, (C) Neil Mitchell 2009" [sample]

To use the CmdArgs library there are three steps:

  1. Define a record data type (Sample) that contains a field for each argument. This type needs to have instances for Show, Data and Typeable.
  2. Give a value of that type (sample) with default values (def is the default value of any type). This value must be turned into a command line mode by calling the function mode.
  3. Call cmdArgs passing the mode, along with some text about the program.

Now we have a reasonably functional command line argument processor. Some sample interactions are:

$ runhaskell Sample.hs --hello=world
Sample {hello = "world"}

$ runhaskell Sample.hs --help
Sample v1, (C) Neil Mitchell 2009

sample [FLAG]

  -? --help[=FORMAT]  Show usage information (optional format)
  -V --version        Show version information
  -v --verbose        Higher verbosity
  -q --quiet          Lower verbosity
  -h --hello=VALUE

The CmdArgs library automatically provides support for:

Specifying Attributes

In order to control the behaviour we can add attributes. For example to add an attribute specifying the help text for the --hello argument we can write:

sample = mode $ Sample{hello = def &= text "Who to say hello to"}

We can add additional attributes, for example to specify the type of the value expected by hello:

sample = mode $ Sample {hello = def &= text "Who to say hello to" & typ "WORLD"}

Now when running --help the final line is:

  -h --hello=WORLD    Who to say hello to

There are many more attributes, detailed in the Haddock documentation.

Multiple Modes

To specify a program with multiple modes, similar to darcs, we can supply a data type with multiple constructors, for example:

data Sample = Hello {whom :: String}
            | Goodbye
              deriving (Show, Data, Typeable)

hello = mode $ Hello{whom = def}
goodbye = mode $ Goodbye

main = print =<< cmdArgs "Sample v2, (C) Neil Mitchell 2009" [hello,goodbye]

Compared to the first example, we now have multiple constructors, and a sample value for each constructor is passed to cmdArgs. Some sample interactions with this command line are:

$ runhaskell Sample.hs hello --whom=world
Hello {whom = "world"}

$ runhaskell Sample.hs goodbye

$ runhaskell Sample.hs --help
Sample v2, (C) Neil Mitchell 2009

sample hello [FLAG]

  -w --whom=VALUE

sample goodbye [FLAG]

Common flags:
  -? --help[=FORMAT]  Show usage information (optional format)
  -V --version        Show version information
  -v --verbose        Higher verbosity
  -q --quiet          Lower verbosity

As before, the behaviour can be customised using attributes.

Larger Examples

For each of the following examples we first explain the purpose of the program, then give the source code, and finally the output of --help=HTML. The programs are intended to show sample uses of CmdArgs, and are available to experiment with through cmdargs progname.


The HLint program analyses a list of files, using various options to control the analysis. The command line processing is simple, but a few interesting points are:

{-# LANGUAGE DeriveDataTypeable #-}
module HLint where
import System.Console.CmdArgs

data HLint = HLint
    {report :: [FilePath]
    ,hint :: [FilePath]
    ,color :: Bool
    ,ignore :: [String]
    ,show_ :: Bool
    ,test :: Bool
    ,cpp_define :: [String]
    ,cpp_include :: [String]
    ,files :: [String]
    deriving (Data,Typeable,Show,Eq)

hlint = mode $ HLint
    {report = def &= empty "report.html" & typFile & text "Generate a report in HTML"
    ,hint = def &= typFile & text "Hint/ignore file to use"
    ,color = def &= flag "c" & flag "colour" & text "Color the output (requires ANSI terminal)"
    ,ignore = def &= typ "MESSAGE" & text "Ignore a particular hint"
    ,show_ = def &= text "Show all ignored ideas"
    ,test = def &= text "Run in test mode"
    ,cpp_define = def &= typ "NAME[=VALUE]" & text "CPP #define"
    ,cpp_include = def &= typDir & text "CPP include path"
    ,files = def &= args & typ "FILE/DIR"
    } &=
    prog "hlint" &
    text "Suggest improvements to Haskell source code" &
    helpSuffix ["To check all Haskell files in 'src' and generate a report type:","  hlint src --report"]

modes = [hlint]

main = print =<< cmdArgs "HLint v1.6.5, (C) Neil Mitchell 2006-2009" modes
HLint v1.6.5, (C) Neil Mitchell 2006-2009
hlint [FLAG] [FILE/DIR]
Suggest improvements to Haskell source code
-?--help[=FORMAT]Show usage information (optional format)
-V--versionShow version information
-v--verboseHigher verbosity
-q--quietLower verbosity
-r--report[=FILE]Generate a report in HTML (default=report.html)
-h--hint=FILEHint/ignore file to use
-c--color --colourColor the output (requires ANSI terminal)
-i--ignore=MESSAGEIgnore a particular hint
-s--showShow all ignored ideas
-t--testRun in test mode
--cpp-define=NAME[=VALUE]CPP #define
--cpp-include=DIRCPP include path
To check all Haskell files in 'src' and generate a report type:
hlint src --report


The Diffy sample is a based on the idea of creating directory listings and comparing them. The tool can operate in two separate modes, create or diff. This sample is fictional, but the ideas are drawn from a real program. A few notable features:

{-# LANGUAGE DeriveDataTypeable #-}
module Diffy where
import System.Console.CmdArgs

data Diffy = Create {src :: FilePath, out :: FilePath}
           | Diff {old :: FilePath, new :: FilePath, out :: FilePath}
             deriving (Data,Typeable,Show,Eq)

outFlags = text "Output file" & typFile

create = mode $ Create
    {src = "." &= text "Source directory" & typDir
    ,out = "ls.txt" &= outFlags
    } &= prog "diffy" & text "Create a fingerprint"

diff = mode $ Diff
    {old = def &= typ "OLDFILE" & argPos 0
    ,new = def &= typ "NEWFILE" & argPos 1
    ,out = "diff.txt" &= outFlags
    } &= text "Perform a diff"

modes = [create,diff]

main = print =<< cmdArgs "Diffy v1.0" modes
Diffy v1.0
diffy create [FLAG]
Create a fingerprint
-s--src=DIRSource directory (default=.)
-o--out=FILEOutput file (default=ls.txt)
Perform a diff
-o--out=FILEOutput file (default=diff.txt)
Common flags:
-?--help[=FORMAT]Show usage information (optional format)
-V--versionShow version information
-v--verboseHigher verbosity
-q--quietLower verbosity


The Maker sample is based around a build system, where we can either build a project, clean the temporary files, or run a test. The test mode is designed to run another program, passing any unknown arguments onwards. Some interesting features are:

{-# LANGUAGE DeriveDataTypeable #-}
module Maker where
import System.Console.CmdArgs

data Method = Debug | Release | Profile
              deriving (Data,Typeable,Show,Eq)

data Maker
    = Wipe
    | Test {threads :: Int, extra :: [String]}
    | Build {threads :: Int, method :: Method, files :: [FilePath]}
      deriving (Data,Typeable,Show,Eq)

threadsMsg = text "Number of threads to use" & flag "j" & typ "NUM"

wipe = mode $ Wipe &= prog "maker" & text "Clean all build objects"

test = mode $ Test
    {threads = def &= threadsMsg
    ,extra = def &= typ "ANY" & args & unknownFlags
    } &= text "Run the test suite"

build = mode $ Build
    {threads = def &= threadsMsg
    ,method = enum Release
        [Debug &= text "Debug build"
        ,Release &= text "Release build"
        ,Profile &= text "Profile build"]
    ,files = def &= args
    } &= text "Build the project" & defMode

modes = [build,wipe,test]

main = print =<< cmdArgs "Maker v1.0" modes
Maker v1.0
maker [build] [FLAG] [FILE]
Build the project
-j--threads=NUMNumber of threads to use
-d--debugDebug build
-r--releaseRelease build
-p--profileProfile build
maker wipe [FLAG]
Clean all build objects
maker test [FLAG] [ANY]
Run the test suite
-j--threads=NUMNumber of threads to use
Common flags:
-?--help[=FORMAT]Show usage information (optional format)
-V--versionShow version information
-v--verboseHigher verbosity
-q--quietLower verbosity