Building a CLI Tool in Haskell

Analogy categoryAnalogies

Anatomy of a Haskell CLI Application

A Haskell command-line tool typically has a thin main :: IO () entry point in app/Main.hs that parses arguments, reads input, and calls into a pure library exposed from src/, keeping the bulk of the logic as pure, independently testable functions. This separation, sometimes called 'functional core, imperative shell', means the parts of your program that decide what to do are ordinary pure Haskell you can test with plain equality checks, while only a thin outer layer touches the filesystem, environment variables, or stdin/stdout.

🏏

Cricket analogy: The functional core, imperative shell pattern is like a cricket team where the analyst back-room staff, the pure core, crunches match data and produces a recommended team and field plan, while only the captain, the IO shell, actually walks onto the field and executes decisions, the thinking and the acting are cleanly separated roles.

Parsing Arguments

For anything beyond a couple of positional arguments, use a dedicated library such as optparse-applicative rather than hand-rolling parsing with getArgs and pattern matching. It lets you declare each flag and argument with its type, default, and help text using an applicative Parser combinator style, and it generates --help output and validation errors automatically, which hand-written argument parsing rarely bothers to do well.

🏏

Cricket analogy: Using optparse-applicative instead of hand-parsing getArgs is like a franchise using the BCCI's official auction software to register bids with structured fields, player, base price, team, instead of a team official scribbling numbers on paper, the structured tool auto-validates and won't accept a malformed entry.

Structuring IO and Keeping Logic Pure

Write the core transformation as a pure function, for example processLines :: [String] -> [String], and keep main responsible only for wiring: reading stdin with getContents, calling the pure function, and writing the result with putStr. This lets you test processLines directly with plain input/output pairs in a unit test, with no mocking of the filesystem or stdin required, and it makes the pure function reusable if you later expose the same logic as a library function or an HTTP handler instead of a CLI.

🏏

Cricket analogy: Keeping the transformation pure like processLines is like a cricket analyst's Duckworth-Lewis-style calculation being a pure formula you can test on paper with sample scores, completely separate from the actual live broadcast system that fetches real-time scores and displays the result to viewers.

haskell

{-# LANGUAGE ApplicativeDo #-}
module Main where

import Options.Applicative
import Data.List (sortOn)
import System.IO

data Options = Options
  { optInput   :: FilePath
  , optReverse :: Bool
  }

optionsParser :: Parser Options
optionsParser = Options
  <$> strOption (long "input" <> short 'i' <> metavar "FILE"
                 <> help "Input file to sort, one entry per line")
  <*> switch (long "reverse" <> short 'r'
              <> help "Sort in descending order")

-- Pure core: no IO here, easily unit-tested.
sortLines :: Bool -> [String] -> [String]
sortLines descending xs =
  let sorted = sortOn id xs
  in if descending then reverse sorted else sorted

main :: IO ()
main = do
  opts <- execParser (info (optionsParser <**> helper)
            (fullDesc <> progDesc "Sort lines from a file"))
  contents <- readFile (optInput opts)
  mapM_ putStrLn (sortLines (optReverse opts) (lines contents))

Packaging and Distribution

Package a Haskell CLI tool with either Cabal or Stack: define the project in a .cabal file, or package.yaml with Stack, which generates the .cabal file, listing an executable stanza that depends on a library stanza containing your pure logic, so the same code is reusable and independently testable via a test-suite stanza. Once built with cabal build or stack build, distribute the resulting binary directly, or publish the package to Hackage with cabal upload if it's meant to be reusable as a library by others; for end users who just want the tool, a statically-linked binary avoids requiring them to install GHC at all.

🏏

Cricket analogy: Splitting a project into library and executable stanzas is like a cricket board separating the national academy's coaching curriculum, the reusable library, applicable to every age-group team, from the senior team's specific matchday squad, the executable, that consumes and applies that curriculum for actual matches.

A common mistake when building your first Haskell CLI tool is putting business logic directly inside main's do-block, mixed with readFile and putStrLn calls. Extract the transformation into a separate pure function as soon as it grows past a couple of lines, it's the single highest-leverage refactor for testability in a CLI project.

Structure Haskell CLIs as a thin IO shell (Main.hs) wrapping a pure, independently testable core exposed from a library.
Use optparse-applicative for argument parsing instead of hand-rolling getArgs matching; it gives typed flags, defaults, and auto-generated --help output.
Keep stdin/stdout and file IO isolated to a small number of functions, and pass plain data (String, Text, [a]) into pure logic.
Testing a CLI tool's core logic should not require mocking the filesystem, pure functions can be tested with plain input/output equality checks.
Cabal or Stack manage building and dependency resolution; a .cabal file declares the executable, its dependencies, and the module it exposes as a library.
Package the same pure logic as both a library (src/) and an executable (app/Main.hs) so it can be reused outside the CLI context.
Provide clear --help text and sensible defaults so the tool is usable without reading source code.