cmdln

README

codeberg.org/prelift/cmdln

A library for writing CLI programs with flags and subcommands.

---

© 2025-2026 codeberg.org/prelift/cmdln authors.

Licensed under the EUPL

Documentation

Overview

Package cmdln is a library for writing command-line tools.

Index

• func Run(ctx context.Context, exeName string, args []string, cmd Command) error
• type ArgumentSet
  • func (argset *ArgumentSet) AcceptMany(name, desc string, set func([]string) error)
  • func (argset *ArgumentSet) AcceptOne(name, desc string, set func(string) error)
  • func (argset *ArgumentSet) Bool(name string, dst *bool, desc string)
  • func (argset *ArgumentSet) Duration(name string, dst *time.Duration, desc string)
  • func (argset *ArgumentSet) Flag(name string, dst FlagValue, desc string)
  • func (argset *ArgumentSet) Float64(name string, dst *float64, desc string)
  • func (argset *ArgumentSet) Int(name string, dst *int, desc string)
  • func (argset *ArgumentSet) Int64(name string, dst *int64, desc string)
  • func (argset *ArgumentSet) Require(name, desc string, set func(string) error)
  • func (argset *ArgumentSet) RequireOneOrMore(name, desc string, set func([]string) error)
  • func (argset *ArgumentSet) Short(alias, dst string)
  • func (argset *ArgumentSet) String(name string, dst *string, desc string)
  • func (argset *ArgumentSet) Summary(desc string)
  • func (argset *ArgumentSet) Text(name string, dst TextValue, desc string)
  • func (argset *ArgumentSet) Uint(name string, dst *uint, desc string)
  • func (argset *ArgumentSet) Uint64(name string, dst *uint64, desc string)
  • func (argset *ArgumentSet) Usage(desc string)
• type Command
• type FlagValue
• type Mux
  • func (cmds *Mux) Alias(prefix, alias, aliasFor string)
  • func (cmds *Mux) Cmd(name string, cmd Command)
  • func (cmds *Mux) Run(ctx context.Context, exeName string, args []string) (err error)
• type TextValue

Functions

func Run

func Run(ctx context.Context, exeName string, args []string, cmd Command) error

Run runs the Command cmd with the given context, executable name, and arguments.

Types

type ArgumentSet

type ArgumentSet struct {
	// contains filtered or unexported fields
}

An ArgumentSet is a set of flags and positional arguments for a CLI program or subcommand.

func (*ArgumentSet) AcceptMany

func (argset *ArgumentSet) AcceptMany(name, desc string, set func([]string) error)

AcceptMany registers an optional command-line argument with the given name and description that accepts more than one value. The value of the argument is set by calling the callback.

func (*ArgumentSet) AcceptOne

func (argset *ArgumentSet) AcceptOne(name, desc string, set func(string) error)

AcceptOne registers an optional positional command-line argument with the given name and description. The value of the argument is set by calling the callback.

func (*ArgumentSet) Bool

func (argset *ArgumentSet) Bool(name string, dst *bool, desc string)

Bool registers a boolean command-line flag with the given name and description. The argument dst is the location of the value of the flag in memory.

func (*ArgumentSet) Duration

func (argset *ArgumentSet) Duration(name string, dst *time.Duration, desc string)

Duration registers a duration command-line flag with the given name and description. The flag accepts values accepted by time.ParseDuration. The argument dst is the location of the value of the flag in memory.

func (*ArgumentSet) Flag

func (argset *ArgumentSet) Flag(name string, dst FlagValue, desc string)

Flag registers a command-line flag with customized parsing logic, the given name, and description. The argument dst is used to set the value of the flag. This is done by calling dst.Set.

func (*ArgumentSet) Float64

func (argset *ArgumentSet) Float64(name string, dst *float64, desc string)

Float64 registers a float64 command-line flag with the given name and description. The argument dst is the location of the value of the flag in memory.

func (*ArgumentSet) Int

func (argset *ArgumentSet) Int(name string, dst *int, desc string)

Int registers an architecture-specific integer-type command-line flag with the given name and description. The argument dst is the location of the value of the flag in memory.

func (*ArgumentSet) Int64

func (argset *ArgumentSet) Int64(name string, dst *int64, desc string)

Int64 registers a 64-bit integer command-line flag with the given name and description. The argument dst is the location of the value of the flag in memory.

func (*ArgumentSet) Require

func (argset *ArgumentSet) Require(name, desc string, set func(string) error)

Require registers a required positional command-line argument with the given name and description. The value of the argument is set by calling the callback.

func (*ArgumentSet) RequireOneOrMore

func (argset *ArgumentSet) RequireOneOrMore(name, desc string, set func([]string) error)

RequireOneOrMore registers an required command-line argument with the given name and description that accepts more than one value. The value of the argument is set by calling the callback.

func (*ArgumentSet) Short

func (argset *ArgumentSet) Short(alias, dst string)

Short registers a short flag alias for the long flag named dst.

func (*ArgumentSet) String

func (argset *ArgumentSet) String(name string, dst *string, desc string)

func (*ArgumentSet) Summary

func (argset *ArgumentSet) Summary(desc string)

Summary sets the short-form description of the command.

func (*ArgumentSet) Text

func (argset *ArgumentSet) Text(name string, dst TextValue, desc string)

Text registers a command-line flag with the given name and description. The argument dst stores the value of the flag. The flag value is set by calling dst.UnmarshalText.

func (*ArgumentSet) Uint

func (argset *ArgumentSet) Uint(name string, dst *uint, desc string)

Uint registers an architecture-specific unsigned-integer-type command-line flag with the given name and description. The argument dst is the location of the value of the flag in memory.

func (*ArgumentSet) Uint64

func (argset *ArgumentSet) Uint64(name string, dst *uint64, desc string)

Int64 registers a 64-bit unsigned integer command-line flag with the given name and description. The argument dst is the location of the value of the flag in memory.

func (*ArgumentSet) Usage

func (argset *ArgumentSet) Usage(desc string)

Usage sets the expanded, long-form description of the command.

type Command

type Command interface {

	// Describe the command-line interface of the command.
	Describe(*ArgumentSet)

	// Run the command.
	//
	// [Mux.Run] and [Run] only ever call [Command.Run] after parsing the arguments.
	Run(context.Context) error
}

A Command that can be added to a Mux or run with Run.

type FlagValue

type FlagValue interface {
	// Set the value of the underlying type to one reflecting s.
	// When the returned error is non-nil, Set should not change the value of the underlying type.
	Set(s string) error
}

A FlagValue stored the value for a command-line flag registered with ArgumentSet.Flag.

type Mux

type Mux struct {
	// contains filtered or unexported fields
}

A Mux is a multiplexer for a set of subcommands.

func (*Mux) Alias

func (cmds *Mux) Alias(prefix, alias, aliasFor string)

Alias registers an alias for an already-registered Command.

A prefix is accepted to simplify registering aliases deep in the subcommand tree. The following call

cmds.Alias("notes", "", "list")

is shorthand for

cmds.Alias("", "notes", "notes list")

func (*Mux) Cmd

func (cmds *Mux) Cmd(name string, cmd Command)

Cmd registers a new subcommand with the given name.

Command names can contain multiple parts separated by whitespace:

cmds.Cmd("notes list", notesList)

func (*Mux) Run

func (cmds *Mux) Run(ctx context.Context, exeName string, args []string) (err error)

Run runs the appropriate subcommand from the command set.

type TextValue

type TextValue interface {
	encoding.TextMarshaler
	encoding.TextUnmarshaler
}

A TextValue stores the value for a command-line flag registered with ArgumentSet.Text.

Many types in the standard library implement the interface.