Design goals
- This project provides a minimal, dependency-light helper to bind struct fields to pflag flags.
- It keeps public API compatibility in mind and favors clear, sentinel-style error handling.
Development
- The preferred local validation command is
task test. - CI validation is expected to cover
gofmt,go vet, andgo test. - Changes are intended to stay small and topic-focused, with one PR per change.
CI Workflows
- The repository uses two primary workflows under
.github/workflows/:ci.ymlandcodeql.yml. - README badges should be updated when workflow names change.
Usage
struct2pflag automatically registers struct fields as flags for your Go command-line programs.
The currently supported types are:
| Type | Bind |
BindEnv |
|---|---|---|
bool |
✓ | ✓ |
int |
✓ | ✓ |
int8 / int16 / int32 / int64 |
✓ | |
uint |
✓ | ✓ |
uint8 / uint16 / uint32 / uint64 |
✓ | |
float32 |
✓ | ✓ |
float64 |
✓ | ✓ |
string |
✓ | ✓ |
time.Duration |
✓ | ✓ |
This project is forked from hymkor/struct2flag, and the BindEnv feature is inspired by hymkor/struct2env.
example.go
package main
import (
"fmt"
"github.com/goark/struct2pflag"
"github.com/spf13/pflag"
)
type Env struct {
B bool `pflag:"boolean,b,This is a boolean flag"`
N int `pflag:"integer,n,This is an integer flag"`
S string `pflag:"string,s,this is a string flag"`
}
func (e Env) Run() {
fmt.Printf("B=%#v\n", e.B)
fmt.Printf("N=%#v\n", e.N)
fmt.Printf("S=%#v\n", e.S)
}
func main() {
var env Env
struct2pflag.BindDefault(&env)
pflag.Parse()
env.Run()
}go run examples/example.go -h
Usage of /home/username/.cache/go-build/da/da816f0e7f8408541782f4f492c77975deac083e65218c1b2bdcf93706b81aa7-d/example:
-b, --boolean This is a boolean flag
-n, --integer int This is an integer flag
-s, --string string this is a string flaggo run examples/example.go -b -n 1 -s foo
B=true
N=1
S="foo"go run examples/example.go --boolean --integer 1 --string foo
B=true
N=1
S="foo"struct2pflag.BindEnv applies environment variables to your config struct before CLI parsing.
type Env struct {
TopN int `env:"TOP_N" pflag:"top-n,n,number of top tags"`
Wait time.Duration `env:"WAIT" pflag:"wait,w,wait duration"`
}
func main() {
env := Env{TopN: 10, Wait: time.Second}
_ = struct2pflag.BindEnv(&env,
struct2pflag.WithEnvPrefix("APP_"), // prepend APP_ to all env names
struct2pflag.WithEnvTag("env"), // struct tag key (default: "env")
struct2pflag.WithStrict(true), // error on unsupported or unset-able fields
)
struct2pflag.BindDefault(&env)
pflag.Parse()
}All options are optional. WithEnvPrefix prepends a string to every env name derived from struct tags.
WithEnvTag changes the tag key used to look up env names (default: "env").
WithStrict makes BindEnv return an error for tagged fields with unsupported or non-settable types instead of silently skipping them.
The recommended precedence is:
- CLI flags
- Environment variables
- Struct default values
examples/example3.go
package main
import (
"fmt"
"os"
"encoding/json"
"github.com/goark/struct2pflag"
"github.com/spf13/pflag"
)
type Env struct {
B bool `pflag:"boolean,b,This is a boolean flag" json:"b"`
N int `pflag:"integer,n,This is an integer flag" json:"n"`
S string `pflag:"string,s,this is a string flag" json:"s"`
}
func (e Env) Run() {
fmt.Printf("B=%#v\n", e.B)
fmt.Printf("N=%#v\n", e.N)
fmt.Printf("S=%#v\n", e.S)
}
func main() {
var env Env
if data, err := os.ReadFile("example3.json"); err == nil {
_ = json.Unmarshal(data, &env)
}
struct2pflag.BindDefault(&env)
pflag.Parse()
env.Run()
}examples/example3.json
{
"b": true,
"n": 100,
"s": "hogehoge"
}go run -C examples example3.go -s changed
B=true
N=100
S="changed"