CommandTree 0.8.0

CommandTree

Define CLI commands as F# discriminated unions, and let type-safe parsing, help generation, and fish completions fall out of your types.

// From examples/ExampleCli/Program.fs

// my-cli task add "Buy groceries"
// my-cli task add "Buy groceries" high
// my-cli task                             ← runs list (CmdDefault)
// my-cli task complete 5
type TaskCommand =
    | [<Cmd("Add a new task")>] Add of title: string * priority: Priority option
    | [<Cmd("List all tasks"); CmdDefault>] List
    | [<Cmd("Complete a task")>] Complete of id: int
    | [<Cmd("Remove a task")>] Remove of id: int

// my-cli --verbose task add "Buy groceries"   ← global flag before command
// my-cli task add "Buy groceries" --verbose   ← global flag after command
type GlobalFlag =
    | [<Cmd("Enable verbose output")>] Verbose
    | [<Cmd("Set log level"); CmdEnv("LVL")>] LogLevel of string

type Command =
    | [<Cmd("Task management")>] Task of TaskCommand
    | [<Cmd("Run the test suite")>] Test
    | [<Cmd("Show full help")>] Help

let spec =
    CommandReflection.fromUnionWithGlobalsAndEnv<Command, GlobalFlag> "My CLI" "MYAPP"

match spec.Parse argv with
| Ok(globals, Task(Add(title, _))) -> printfn "Adding %s" title
| Ok(_, Help) -> printfn "%s" (CommandTree.helpWithGlobals spec.Tree spec.GlobalFlags "my-cli")
| Error(HelpRequested path) -> printfn "%s" (CommandTree.helpForPath spec.Tree path "my-cli")
| Error(UnknownCommand(input, _rest, _)) -> UI.fail $"Unknown command: %s{input}"
| _ -> ()

Status: early alpha, and substantially AI-written. It runs the author's own F# CLIs, but behavior and APIs shift between versions and rough edges are expected — your mileage may vary. Issues and PRs very welcome.

The problem

Hand-written CLI parsing tends to drift: strings get parsed into the wrong types, a --help branch goes missing, and the help text stops matching the real flags. The idea here is to describe the command surface once as a discriminated union and derive the parser, help text, and shell completions from that single definition by reflection — so they aim to stay in sync because there's nothing to keep in sync by hand.

Install

dotnet add package CommandTree

How it works

Case names become kebab-case commands. Nested unions become subcommand groups. Fields become positional arguments. Every snippet below is sourced verbatim from the compiled examples/ExampleCli/Program.fs, so it can't drift from code that builds.

A simple subcommand group with a default subcommand:

// example-cli db migrate
// example-cli db                               ← runs status (CmdDefault)
// example-cli db reset
type DbCommand =
    | [<Cmd("Run database migrations")>] Migrate
    | [<Cmd("Reset the database")>] Reset
    | [<Cmd("Show connection status"); CmdDefault>] Status

Value completions and an optional positional field:

// example-cli deploy push staging
// example-cli deploy status prod
// example-cli deploy                           ← runs status with no env (CmdDefault)
type DeployCommand =
    | [<Cmd("Deploy to environment"); CmdCompletion("dev", "staging", "prod")>] Push of env: string
    | [<Cmd("Show deploy status"); CmdCompletion("dev", "staging", "prod"); CmdDefault>] Status of env: string option

A trailing list field collects remaining args; file completions per field:

// example-cli tag v1.0 src/App.fs src/Lib.fs   ← list field collects 1+ remaining args
// example-cli diff old.dll new.dll             ← multiple CmdFileCompletion with FieldIndex
type FilesCommand =
    | [<Cmd("Tag files with a label"); CmdFileCompletion>] Tag of label: string * files: string list
    | [<Cmd("Compare two DLLs"); CmdFileCompletion(FieldIndex = 0); CmdFileCompletion(FieldIndex = 1)>] Diff of
        oldDll: string *
        newDll: string

A flag DU becomes named --flags:

// example-cli check --conf custom.json --strict --no-cache --wait=30
// example-cli check --wait          ← bare optional-value flag binds `Wait None` (never swallows a value)
type CheckFlag =
    | [<CmdFlag(Name = "conf", Short = "k")>] Config of string
    | [<Cmd("Enable strict checking")>] Strict
    | [<CmdEnvRaw("NO_CACHE")>] NoCache
    | [<Cmd("Wait N seconds; bare for the default")>] Wait of int option

Basic usage

Build a tree from your command DU, then parse argv against it. The full runnable example lives in examples/ExampleCli/Program.fs.

open CommandTree

let tree = CommandReflection.fromUnion<Command> "My CLI"

[<EntryPoint>]
let main argv =
    match CommandTree.parse tree argv with
    | Ok cmd ->
        run cmd
        0
    | Error(HelpRequested path) ->
        printfn "%s" (CommandTree.helpForPath tree path "my-cli")
        0
    | Error e ->
        // UnknownCommand, InvalidArguments, AmbiguousArgument, UnknownFlag, DuplicateFlag
        UI.fail $"%A{e}"
        1

For global flags and env-var binding, use fromUnionWithGlobalsAndEnv, which returns a GlobalSpec whose Parse yields (globals, command). Global flags can appear anywhere in the arg list — before, after, or interleaved with command args. See the example for a full match over every ParseError case.

Attributes

Decorate union cases to customize parsing, help, and completions:

Flags and env vars

Define flags as their own DU and attach them as a list field (e.g. Check of CheckFlag list). A no-field case is a boolean flag; a single 'T option field is an optional-value flag; any other single field is a required-value flag. Short flags are auto-derived from the first letter (collisions are dropped); override with [<CmdFlag>].

Required-value flags take their value space-separated (--conf custom.json) or inline (--conf=custom.json). Optional-value flags are inline-only: bare --wait binds None, --wait=5 binds Some 5, and they never consume the following token — so --wait --detach is Wait None plus Detach, and --wait 5 leaves 5 as a positional. A bare-but-= form with no value (--wait=) or a value that does not parse (--wait=abc) is a parse error.

A case can mix positional fields with a trailing flag DU list (e.g. Remove of name: string * flags: RemoveFlag list). Flags may appear anywhere relative to the positionals, and everything after a standalone -- binds as positional values — so a value that looks like a flag (remove -- --force) stays a value.

// example-cli check --conf custom.json --strict --no-cache --wait=30
// example-cli check --wait          ← bare optional-value flag binds `Wait None` (never swallows a value)
type CheckFlag =
    | [<CmdFlag(Name = "conf", Short = "k")>] Config of string
    | [<Cmd("Enable strict checking")>] Strict
    | [<CmdEnvRaw("NO_CACHE")>] NoCache
    | [<Cmd("Wait N seconds; bare for the default")>] Wait of int option

When an env prefix is configured (fromUnionWithEnv / fromUnionWithGlobalsAndEnv), each flag case also reads PREFIX_SCREAMING_SNAKE_CASE. Resolution order is CLI flag > env var > absent. For booleans, "true"/"1" mean present and "false"/"0"/unset mean absent.

Supported field types

A field whose type isn't supported is a spec error — a malformed command shape, distinct from a runtime parse error. See Advanced usage for the full API reference (parsing, help rendering, version stamping, spec errors, fish completions) and the optional build-time analyzer.

More

• Advanced usage — full CommandTree/CommandReflection reference, structured errors, version stamping, fish completions, and the build-time analyzer.
• API docs — generated reference for every public member, including the Process and UI helper modules.

License

MIT

</content> </invoke>