clif

README

go-clif

go-clif is a Go library for parsing command-line arguments into Go structs using generics. It provides type-safe CLI argument parsing with automatic help generation.

The library exposes a single generic function:

func Parse[T any](v *T, args []string, opts ...Option) ([]string, error)

Parameters:

• v: A pointer to a struct that will be populated with parsed flag values
• args: Command-line arguments to parse (typically os.Args[1:])

Returns:

• Positional arguments (those not consumed as flags)
• Error if parsing fails

Struct Field Mapping

Each field in the target struct corresponds to a command-line flag:

Struct Field	Flag Name	Behavior
StringArg string	-StringArg value	String flag requiring a value
Count int	-Count value	Integer flag requiring a value
Ratio float64	-Ratio value	Float flag requiring a value
Verbose bool	-Verbose	Boolean flag (no value required)
Target []string	-Target value (repeatable)	Slice of strings, flag can be repeated
Timeouts []int	-Timeouts value (repeatable)	Slice of ints, flag can be repeated

Supported Types

Scalar Types

• string
• int, int8, int16, int32, int64
• uint, uint8, uint16, uint32, uint64
• float32, float64
• bool

Slice Types

• []string
• []int, []int8, []int16, []int32, []int64
• []uint, []uint8, []uint16, []uint32, []uint64
• []float32, []float64
• []bool

Shortcuts

Flags automatically receive shortcuts based on their first letter:

• If only one field starts with a given lowercase letter, it gets a shortcut flag
• The shortcut is the lower-case version of the first letter
• Example: Only Workspace field exists → shortcut is -w
• Example: Both Workspace and Write exist → no shortcut for either (ambiguous)

Help Functionality

Automatic Help Flag

The library provides a built-in -Help flag that prints usage information and exits. This flag cannot be overridden or disabled.

Help Annotation

Fields can include help descriptions using the clif tag:

type Flags struct {
    Workspace string `clif:"Specify the workspace directory. The directory must exist."`
}

Options

The following options are supported:

• WithArgMin: Set minimum required positional arguments.
• WithArgMax: Set maximum required positional arguments.
• WithArgName: Set positional argument name.
• WithProg(name: Set program name.
• WithHelp: Set extra help.

Usage Examples

Basic Usage

package main

import (
    "fmt"
    "os"
    
    "github.com/yuce/go-clif"
)

type Flags struct {
    File []string
    TimeoutSeconds int
    Workspace string `clif:"Specify the workspace directory. The directory must exist."`
    Verbose bool
}

func main() {
    var flags Flags
    
    // Parse command-line arguments
    remainingArgs, err := clif.Parse(&flags, os.Args[1:])
    if err != nil {
        panic(err)
    }
    
    // Use parsed values
    fmt.Printf("Files: %v\n", flags.File)
    fmt.Printf("Timeout: %d seconds\n", flags.TimeoutSeconds)
    fmt.Printf("Workspace: %s\n", flags.Workspace)
    fmt.Printf("Verbose: %v\n", flags.Verbose)
    fmt.Printf("Remaining args: %v\n", remainingArgs)
}

Running with Arguments

# With all options
$ mycommand --File file1.txt --File file2.md --Workspace /home/sam/ws --TimeoutSeconds 10 --Verbose arg1 arg2

# Flags populate:
# flags.File = []string{"file1.txt", "file2.md"}
# flags.TimeoutSeconds = 10
# flags.Workspace = "/home/sam/ws"
# flags.Verbose = true
# remainingArgs = []string{"arg1", "arg2"}

# Using shortcuts
$ mycommand -w /home/sam/ws -t 10 -V arg1

# Shortcuts used:
# -w for -Workspace
# -t for -TimeoutSeconds  
# -V for -Verbose

# Help output
$ mycommand -Help

License

Apache 2

Documentation

Index

• Variables
• func Parse[T any](v *T, args []string, opts ...Option) ([]string, error)
• type Option
  • func WithArgMax(value int) Option
  • func WithArgMin(value int) Option
  • func WithArgName(name string) Option
  • func WithHelp(help string) Option
  • func WithProg(name string) Option

Variables

var ErrHelp = errors.New("help requested")

ErrHelp is returned when the -Help flag is specified.

Functions

func Parse

func Parse[T any](v *T, args []string, opts ...Option) ([]string, error)

Parse parses command-line arguments into a struct pointer v using generics. It returns the remaining positional arguments (those not consumed as flags) and an error if parsing fails.

Types

type Option

type Option func(opt *options) error

func WithArgMax

func WithArgMax(value int) Option

func WithArgMin

func WithArgMin(value int) Option

func WithArgName

func WithArgName(name string) Option

func WithHelp

func WithHelp(help string) Option

func WithProg

func WithProg(name string) Option