tinyflags

package module
v0.0.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 23, 2025 License: Apache-2.0 Imports: 10 Imported by: 1

README

tinyflags

Go Reference

A minimal, fast, and extensible CLI flag-parsing library for Go. Zero dependencies, full generics support, advanced features.

Features

  • Short & long flags (-d, --debug)
  • Boolean strict mode (--flag=true/false, --no-flag)
  • Environment overrides (per-flag or EnvPrefix)
  • Required & deprecated flags
  • Slice flags ([]T) with custom delimiters
  • Choices & validation
  • Mutual-exclusion groups
  • Custom Placeholders and rich help formatting
  • Dynamic flags (--group.id.field=value)
  • TCP-addr, URL, IP, File, Duration, and more built-in types

Install

go get github.com/containeroo/tinyflags

Quickstart

package main

import (
  "fmt"
  "os"
  "github.com/containeroo/tinyflags"
)

func main() {
  fs := tinyflags.NewFlagSet("app", tinyflags.ExitOnError)
  fs.EnvPrefix("MYAPP")   // use MYAPP_… env vars
  fs.Version("v1.0.0")    // enable -v/--version

  // builder returns the flag – call .Value() to get corresponding value
  host := fs.String("host", "localhost", "server host").
              Required().
              Value()
  port := fs.Int("port", 8080, "server port").
              Short("p").
              Value()
  debug := fs.Bool("debug", false, "enable debug").
               Short("d").
               Value()
  tags  := fs.StringSlice("tag", nil, "tags list").
               Value()

  if err := fs.Parse(os.Args[1:]); err != nil {
    fmt.Fprintln(os.Stderr, err)
    os.Exit(1)
  }

  fmt.Println("Host:", *host)
  fmt.Println("Port:", *port)
  fmt.Println("Debug:", *debug)
  fmt.Println("Tags:", *tags)
}

Environment Variables

MYAPP_HOST=example.com MYAPP_PORT=9090 ./app --debug

Disable per-flag with:

fs.Bool("internal", false, "").DisableEnv()

Dynamic Flags

package main

import (
  "fmt"
  "os"
  "github.com/containeroo/tinyflags"
)

func main() {
  fs := tinyflags.NewFlagSet("app", tinyflags.ExitOnError)
  dg := fs.DynamicGroup("http")

  // define per-instance flags; builder returned until you call Get()/MustGet()
  portFlag    := dg.Int("port", "backend port")
  timeoutFlag := dg.Duration("timeout", "request timeout")

  if err := fs.Parse(os.Args[1:]); err != nil {
    fmt.Fprintln(os.Stderr, err)
    os.Exit(1)
  }

  // iterate over all IDs seen
  for _, id := range dg.Instances() {
    port, _    := portFlag.Get(id)
    timeout, _ := timeoutFlag.Get(id)
    fmt.Printf("%s → port=%d, timeout=%s\n", id, port, timeout)
  }
}

Call it like:

```bash
./app --http.alpha.port=8080 --http.alpha.timeout=30s \
      --http.beta.port=9090 --http.beta.timeout=1m

Outputs:

alpha → port=8080, timeout=30s
beta → port=9090, timeout=1m

Help Output

Usage: app [flags]

  --host HOST         server host (Default: localhost) (Env: MYAPP_HOST) (Required)
  -p, --port PORT     server port (Default: 8080) (Env: MYAPP_PORT)
  -d, --debug         enable debug (Env: MYAPP_DEBUG)
      --tag TAG...    tags list
  -v, --version       show version

Supported Types

Go Type Methods
bool Bool, BoolVar
counter* Counter, CounterVar
int Int, IntVar
string String, StringVar
[]string StringSlice, StringSliceVar
time.Duration Duration, DurationVar
net.IP / []net.IP IP, IPVar, IPSlice, IPSliceVar
*net.TCPAddr TCPAddr, TCPAddrVar
url.URL URL, URLVar
*os.File File, FileVar

* Counter flags are special: they increment on each occurrence, -vv → 2, -vvv → 3, etc.

All slice flags also support repeated usage and custom delimiters.

FlagSet Methods

Method Description
NewFlagSet(name, mode) create a new named FlagSet
Parse(args) parse flags and env vars
Version(s) set version string for --version
EnvPrefix(s) set global env-var prefix
Authors(s) add author info to help
Title(s) set help title
Description(s) add a description paragraph
Note(s) append a note paragraph
DisableHelp(), DisableVersion() disable built-in help/version flags
Sorted(bool) enable/disable sorted flag output
SetOutput(w), Output() set/get output writer
IgnoreInvalidEnv(bool) skip invalid env-var values
SetGetEnvFn(fn) customize env-var lookup
Globaldelimiter(s) set default slice-delimiter
RequirePositional(n) require at least n positional args
Args(), Arg(i) retrieve positional args
GetGroup(name) create/get a mutual-exclusion group
PrintDefaults() print all flags with defaults
PrintUsage(w, mode) print usage in specified mode
PrintTitle(w), PrintNotes(w, width), PrintDescription(w, width) various help sections
PrintAuthors(w) print author info
DynamicGroup(name) create/get a dynamic-flag group
DefaultDelimiter() get default delimiter for slice flags

Note Every static flag method returns the builder so you can chain calls (e.g. .Required(), .Choices(), .Short("x")). Only when you call .Value() do you actually get back the *T.

Dynamic flags work differently: you define them on a Group, but after parsing you must fetch values with Get(id), MustGet(id), or Values().

License

Apache 2.0 — see LICENSE

Documentation

Index

Constants

View Source 
const (
	ContinueOnError = engine.ContinueOnError
	ExitOnError     = engine.ExitOnError
	PanicOnError    = engine.PanicOnError
)
View Source 
const (
	PrintNone  = engine.PrintNone
	PrintFlags = engine.PrintFlags
	PrintShort = engine.PrintShort
	PrintLong  = engine.PrintLong
	PrintBoth  = engine.PrintBoth
)

Variables

View Source 
var (
	IsHelpRequested    = engine.IsHelpRequested
	IsVersionRequested = engine.IsVersionRequested
	RequestHelp        = engine.RequestHelp
	RequestVersion     = engine.RequestVersion
)

Functions

func GetDynamic added in v0.0.10 

func GetDynamic[T any](group *dynamic.Group, field, id string) (T, error)

GetDynamic retrieves a dynamic field value for a given ID with the correct type.

func MustGetDynamic added in v0.0.10 

func MustGetDynamic[T any](group *dynamic.Group, field, id string) T

MustGetDynamic panics if the field or id is missing.

Types

type ErrorHandling 

type ErrorHandling = engine.ErrorHandling

ErrorHandling is re-exported from internal engine

type FlagPrintMode 

type FlagPrintMode = engine.FlagPrintMode

type FlagSet 

type FlagSet struct {

	// Usage can be overridden by the user to customize help output.
	// It is executed when --help is triggered or from user code.
	Usage func()
	// contains filtered or unexported fields
}

FlagSet is the public wrapper around internal engine.FlagSet It provides the full user-facing API for defining and parsing CLI flags.

func NewFlagSet 

func NewFlagSet(name string, handling ErrorHandling) *FlagSet

NewFlagSet creates a new flag set.

func (*FlagSet) Arg 

func (f *FlagSet) Arg(i int) (string, bool)

Arg returns the nth positional argument, if present.

func (*FlagSet) Args 

func (f *FlagSet) Args() []string

Args returns leftover positional arguments.

func (*FlagSet) Authors added in v0.0.8 

func (f *FlagSet) Authors(s string)

Authors adds author information to the help text.

func (*FlagSet) Bool 

func (f *FlagSet) Bool(name string, def bool, usage string) *scalar.BoolFlag

Bool defines a boolean flag. If Strict() is true, the flag requires an explicit value (--flag=true/false).

func (*FlagSet) BoolVar 

func (f *FlagSet) BoolVar(ptr *bool, name, short string, def bool, usage string) *scalar.BoolFlag

BoolVar defines a boolean flag, binding the flag to a pointer (ptr). If Strict() is true, the flag requires an explicit value (--flag=true/false).

func (*FlagSet) Bytes added in v0.0.8 

func (f *FlagSet) Bytes(name string, def uint64, usage string) *scalar.ScalarFlag[uint64]

Bytes declares a uint64 “bytes” flag.

func (*FlagSet) BytesSlice added in v0.0.8 

func (f *FlagSet) BytesSlice(name string, def []uint64, usage string) *slice.SliceFlag[uint64]

BytesSlice declares a []uint64 “bytes” flag.

func (*FlagSet) BytesSliceVar added in v0.0.8 

func (f *FlagSet) BytesSliceVar(ptr *[]uint64, name string, def []uint64, usage string) *slice.SliceFlag[uint64]

BytesSliceVar declares a []uint64 “bytes” flag, binding the flag to a pointer (ptr).

func (*FlagSet) BytesVar added in v0.0.8 

func (f *FlagSet) BytesVar(ptr *uint64, name string, def uint64, usage string) *scalar.ScalarFlag[uint64]

BytesVar declares a uint64 “bytes” flag, binding the flag to a pointer (ptr).

func (*FlagSet) Counter added in v0.0.8 

func (f *FlagSet) Counter(name, usage string) *scalar.CounterFlag

Counter defines a counter flag. A counter is a flag that increments on each occurrence.

func (*FlagSet) CounterVar added in v0.0.8 

func (f *FlagSet) CounterVar(ptr *int, name, usage string) *scalar.CounterFlag

CounterVar defines a counter flag, binding the flag to a pointer (ptr). A counter is a flag that increments on each occurrence.

func (*FlagSet) DefaultDelimiter added in v0.0.8 

func (f *FlagSet) DefaultDelimiter() string

DefaultDelimiter returns the slice-value separator.

func (*FlagSet) Description 

func (f *FlagSet) Description(s string)

Description adds a description paragraph to the help.

func (*FlagSet) DescriptionIndent 

func (f *FlagSet) DescriptionIndent(n int)

DescriptionIndent sets the indent width for descriptions.

func (*FlagSet) DescriptionMaxLen 

func (f *FlagSet) DescriptionMaxLen(n int)

DescriptionMaxLen sets the max width for description text.

func (*FlagSet) DisableHelp 

func (f *FlagSet) DisableHelp()

DisableHelp turns off automatic help flag registration.

func (*FlagSet) DisableVersion 

func (f *FlagSet) DisableVersion()

DisableVersion turns off automatic version flag registration.

func (*FlagSet) Duration 

func (f *FlagSet) Duration(name string, def time.Duration, usage string) *scalar.ScalarFlag[time.Duration]

Duration declares a time.Duration flag.

func (*FlagSet) DurationSlice 

func (f *FlagSet) DurationSlice(name string, def []time.Duration, usage string) *slice.SliceFlag[time.Duration]

DurationSlice declares a []time.Duration flag.

func (*FlagSet) DurationSliceVar 

func (f *FlagSet) DurationSliceVar(ptr *[]time.Duration, name string, def []time.Duration, usage string) *slice.SliceFlag[time.Duration]

DurationSliceVar declares a []time.Duration flag, binding the flag to a pointer (ptr).

func (*FlagSet) DurationVar 

func (f *FlagSet) DurationVar(ptr *time.Duration, name string, def time.Duration, usage string) *scalar.ScalarFlag[time.Duration]

DurationVar declares a time.Duration flag, binding the flag to a pointer (ptr).

func (*FlagSet) DynamicGroup added in v0.0.8 

func (f *FlagSet) DynamicGroup(name string) *dynamic.Group

DynamicGroup returns or creates a dynamic flag group.

func (*FlagSet) DynamicGroups added in v0.0.9 

func (f *FlagSet) DynamicGroups() []*dynamic.Group

DynamicGroups returns all dynamic flag groups.

func (*FlagSet) EnvPrefix 

func (f *FlagSet) EnvPrefix(s string)

EnvPrefix sets a prefix for deriving environment-variable names.

func (*FlagSet) File 

func (f *FlagSet) File(name string, def *os.File, usage string) *scalar.ScalarFlag[*os.File]

File declares an *os.File flag.

func (*FlagSet) FileSlice 

func (f *FlagSet) FileSlice(name string, def []*os.File, usage string) *slice.SliceFlag[*os.File]

FileSlice declares a []*os.File flag.

func (*FlagSet) FileSliceVar 

func (f *FlagSet) FileSliceVar(ptr *[]*os.File, name string, def []*os.File, usage string) *slice.SliceFlag[*os.File]

FileSliceVar declares a []*os.File flag, binding the flag to a pointer (ptr).

func (*FlagSet) FileVar 

func (f *FlagSet) FileVar(ptr **os.File, name string, def *os.File, usage string) *scalar.ScalarFlag[*os.File]

FileVar declares an *os.File flag, binding the flag to a pointer (ptr).

func (*FlagSet) Float32 

func (f *FlagSet) Float32(name string, def float32, usage string) *scalar.ScalarFlag[float32]

Float32 declares a float32 flag.

func (*FlagSet) Float32Slice 

func (f *FlagSet) Float32Slice(name string, def []float32, usage string) *slice.SliceFlag[float32]

Float32Slice declares a []float32 flag.

func (*FlagSet) Float32SliceVar 

func (f *FlagSet) Float32SliceVar(ptr *[]float32, name string, def []float32, usage string) *slice.SliceFlag[float32]

Float32SliceVar declares a []float32 flag, binding the flag to a pointer (ptr).

func (*FlagSet) Float32Var 

func (f *FlagSet) Float32Var(ptr *float32, name string, def float32, usage string) *scalar.ScalarFlag[float32]

Float32Var declares a float32 flag, binding the flag to a pointer (ptr).

func (*FlagSet) Float64 

func (f *FlagSet) Float64(name string, def float64, usage string) *scalar.ScalarFlag[float64]

Float64 declares a float64 flag.

func (*FlagSet) Float64Slice 

func (f *FlagSet) Float64Slice(name string, def []float64, usage string) *slice.SliceFlag[float64]

Float64Slice declares a []float64 flag.

func (*FlagSet) Float64SliceVar 

func (f *FlagSet) Float64SliceVar(ptr *[]float64, name string, def []float64, usage string) *slice.SliceFlag[float64]

Float64SliceVar declares a []float64 flag, binding the flag to a pointer (ptr).

func (*FlagSet) Float64Var 

func (f *FlagSet) Float64Var(ptr *float64, name string, def float64, usage string) *scalar.ScalarFlag[float64]

Float64Var declares a float64 flag, binding the flag to a pointer (ptr).

func (*FlagSet) GetGroup added in v0.0.8 

func (f *FlagSet) GetGroup(name string) *core.MutualGroup

GetGroup returns the named mutual-exclusion group.

func (*FlagSet) Globaldelimiter 

func (f *FlagSet) Globaldelimiter(s string)

Globaldelimiter sets the default delimiter for slice flags.

func (*FlagSet) Groups added in v0.0.8 

func (f *FlagSet) Groups() []*core.MutualGroup

Groups returns all mutual-exclusion groups.

func (*FlagSet) IP 

func (f *FlagSet) IP(name string, def net.IP, usage string) *scalar.ScalarFlag[net.IP]

IP declares a net.IP flag.

func (*FlagSet) IPMask 

func (f *FlagSet) IPMask(name string, def net.IPMask, usage string) *scalar.ScalarFlag[net.IPMask]

IPMask declares a net.IPMask flag.

func (*FlagSet) IPMaskSlice 

func (f *FlagSet) IPMaskSlice(name string, def []net.IPMask, usage string) *slice.SliceFlag[net.IPMask]

IPMaskSlice declares a []net.IPMask flag.

func (*FlagSet) IPMaskSliceVar 

func (f *FlagSet) IPMaskSliceVar(ptr *[]net.IPMask, name string, def []net.IPMask, usage string) *slice.SliceFlag[net.IPMask]

IPMaskSliceVar declares a []net.IPMask flag, binding the flag to a pointer (ptr).

func (*FlagSet) IPSlice 

func (f *FlagSet) IPSlice(name string, def []net.IP, usage string) *slice.SliceFlag[net.IP]

IPSlice declares a []net.IP flag.

func (*FlagSet) IPSliceVar 

func (f *FlagSet) IPSliceVar(ptr *[]net.IP, name string, def []net.IP, usage string) *slice.SliceFlag[net.IP]

IPSliceVar declares a []net.IP flag, binding the flag to a pointer (ptr).

func (*FlagSet) IPVar 

func (f *FlagSet) IPVar(ptr *net.IP, name string, def net.IP, usage string) *scalar.ScalarFlag[net.IP]

IPVar declares a net.IP flag, binding the flag to a pointer (ptr).

func (*FlagSet) IPv4MaskVar added in v0.0.8 

func (f *FlagSet) IPv4MaskVar(ptr *net.IPMask, name string, def net.IPMask, usage string) *scalar.ScalarFlag[net.IPMask]

IPv4MaskVar declares a net.IPMask flag, binding the flag to a pointer (ptr).

func (*FlagSet) IgnoreInvalidEnv 

func (f *FlagSet) IgnoreInvalidEnv(b bool)

IgnoreInvalidEnv skips invalid environment-variable values.

func (*FlagSet) Int 

func (f *FlagSet) Int(name string, def int, usage string) *scalar.ScalarFlag[int]

Int declares an int flag.

func (*FlagSet) IntSlice 

func (f *FlagSet) IntSlice(name string, def []int, usage string) *slice.SliceFlag[int]

IntSlice declares a []int flag.

func (*FlagSet) IntSliceVar 

func (f *FlagSet) IntSliceVar(ptr *[]int, name string, def []int, usage string) *slice.SliceFlag[int]

IntSliceVar declares a []int flag, binding the flag to a pointer (ptr).

func (*FlagSet) IntVar 

func (f *FlagSet) IntVar(ptr *int, name string, def int, usage string) *scalar.ScalarFlag[int]

IntVar declares an int flag, binding the flag to a pointer (ptr).

func (*FlagSet) Name 

func (f *FlagSet) Name() string

Name returns the name of the application.

func (*FlagSet) Note 

func (f *FlagSet) Note(s string)

Note appends a note paragraph to the help footer.

func (*FlagSet) Output 

func (f *FlagSet) Output() io.Writer

Output returns the current output writer.

func (*FlagSet) Parse 

func (f *FlagSet) Parse(args []string) error

Parse processes args and environment variables.

func (*FlagSet) PrintAuthors added in v0.0.8 

func (f *FlagSet) PrintAuthors(w io.Writer)

PrintAuthors writes the authors heading.

func (*FlagSet) PrintDefaults 

func (f *FlagSet) PrintDefaults()

PrintDefaults prints all defined flags and their defaults.

func (*FlagSet) PrintDescription 

func (f *FlagSet) PrintDescription(w io.Writer, width int)

PrintDescription writes the description wrapped at width.

func (*FlagSet) PrintNotes 

func (f *FlagSet) PrintNotes(w io.Writer, width int)

PrintNotes writes help notes wrapped at width.

func (*FlagSet) PrintTitle 

func (f *FlagSet) PrintTitle(w io.Writer)

PrintTitle writes the help title.

func (*FlagSet) PrintUsage 

func (f *FlagSet) PrintUsage(w io.Writer, mode FlagPrintMode)

PrintUsage writes usage text in the specified mode.

func (*FlagSet) RequirePositional 

func (f *FlagSet) RequirePositional(n int)

RequirePositional enforces a minimum number of positional args.

func (*FlagSet) SetGetEnvFn 

func (f *FlagSet) SetGetEnvFn(fn func(string) string)

SetGetEnvFn replaces how environment variables are looked up.

func (*FlagSet) SetOutput 

func (f *FlagSet) SetOutput(w io.Writer)

SetOutput redirects all help and error output.

func (*FlagSet) Sorted 

func (f *FlagSet) Sorted(b bool)

Sorted enables or disables sorted flag output.

func (*FlagSet) String 

func (f *FlagSet) String(name string, def string, usage string) *scalar.ScalarFlag[string]

String declares a string flag.

func (*FlagSet) StringSlice 

func (f *FlagSet) StringSlice(name string, def []string, usage string) *slice.SliceFlag[string]

StringSlice declares a []string flag.

func (*FlagSet) StringSliceVar 

func (f *FlagSet) StringSliceVar(ptr *[]string, name string, def []string, usage string) *slice.SliceFlag[string]

StringSliceVar declares a []string flag, binding the flag to a pointer (ptr).

func (*FlagSet) StringVar 

func (f *FlagSet) StringVar(ptr *string, name string, def string, usage string) *scalar.ScalarFlag[string]

StringVar declares a string flag, binding the flag to a pointer (ptr).

func (*FlagSet) TCPAddr added in v0.0.8 

func (f *FlagSet) TCPAddr(name string, def *net.TCPAddr, usage string) *scalar.ScalarFlag[*net.TCPAddr]

TCPAddr declares a *net.TCPAddr flag.

func (*FlagSet) TCPAddrSlice added in v0.0.8 

func (f *FlagSet) TCPAddrSlice(name string, def []*net.TCPAddr, usage string) *slice.SliceFlag[*net.TCPAddr]

TCPAddrSlice declares a []*net.TCPAddr flag.

func (*FlagSet) TCPAddrSliceVar added in v0.0.8 

func (f *FlagSet) TCPAddrSliceVar(ptr *[]*net.TCPAddr, name string, def []*net.TCPAddr, usage string) *slice.SliceFlag[*net.TCPAddr]

TCPAddrSliceVar declares a []*net.TCPAddr flag, binding the flag to a pointer (ptr).

func (*FlagSet) TCPAddrVar added in v0.0.8 

func (f *FlagSet) TCPAddrVar(ptr **net.TCPAddr, name string, def *net.TCPAddr, usage string) *scalar.ScalarFlag[*net.TCPAddr]

TCPAddrVar declares a *net.TCPAddr flag, binding the flag to a pointer (ptr).

func (*FlagSet) Time added in v0.0.8 

func (f *FlagSet) Time(name string, def time.Time, usage string) *scalar.ScalarFlag[time.Time]

Time declares a time.Time flag.

func (*FlagSet) TimeSlice added in v0.0.8 

func (f *FlagSet) TimeSlice(name string, def []time.Time, usage string) *slice.SliceFlag[time.Time]

TimeSlice declares a []time.Time flag.

func (*FlagSet) TimeSliceVar added in v0.0.8 

func (f *FlagSet) TimeSliceVar(ptr *[]time.Time, name string, def []time.Time, usage string) *slice.SliceFlag[time.Time]

TimeSliceVar declares a []time.Time flag, binding the flag to a pointer (ptr).

func (*FlagSet) TimeVar added in v0.0.8 

func (f *FlagSet) TimeVar(ptr *time.Time, name string, def time.Time, usage string) *scalar.ScalarFlag[time.Time]

TimeVar declares a time.Time flag, binding the flag to a pointer (ptr).

func (*FlagSet) Title 

func (f *FlagSet) Title(s string)

Title sets the program title in the help header.

func (*FlagSet) URL 

func (f *FlagSet) URL(name string, def *url.URL, usage string) *scalar.ScalarFlag[*url.URL]

URL declares a url.URL flag.

func (*FlagSet) URLSlice 

func (f *FlagSet) URLSlice(name string, def []*url.URL, usage string) *slice.SliceFlag[*url.URL]

URLSlice declares a []url.URL flag.

func (*FlagSet) URLSliceVar 

func (f *FlagSet) URLSliceVar(ptr *[]*url.URL, name string, def []*url.URL, usage string) *slice.SliceFlag[*url.URL]

URLSliceVar declares a []url.URL flag, binding the flag to a pointer (ptr).

func (*FlagSet) URLVar 

func (f *FlagSet) URLVar(ptr **url.URL, name string, def *url.URL, usage string) *scalar.ScalarFlag[*url.URL]

URLVar declares a url.URL flag, binding the flag to a pointer (ptr).

func (*FlagSet) Version 

func (f *FlagSet) Version(s string)

Version sets the version string for --version output.

type HelpRequested 

type HelpRequested = engine.HelpRequested

HelpRequested, VersionRequested, and helpers

type VersionRequested 

type VersionRequested = engine.VersionRequested

HelpRequested, VersionRequested, and helpers

Source Files

View all Source files

Directories

Path Synopsis
examples
advanced command
dynamic command
simple command
internal
builder
core
dynamic
engine
scalar
internal/scalar/flag.go
 internal/scalar/flag.go
slice
utils

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.