clibind

urfave-cli-bind

A tiny helper that maps urfave/cli/v3 flags to and from Go structs. Define your configuration once with struct tags, generate the corresponding cli.Flags, and bind parsed values back into the struct inside your command action.

This repository is an add-on for github.com/urfave/cli/v3. It layers reflection helpers on top of the original CLI runtime and is neither a fork nor a replacement for urfave/cli itself.

Features

• Reflect-based flag generation via FlagsFromStruct for primitives, durations, times, UUIDs, and slices
• Tag-driven defaults (cliDefault), usage strings (cliUsage), prefixes for nested structs (cliPrefix), and omitempty
• Works with concrete structs or pointers, including anonymous/embedded structs for flattening
• Binds directly from *cli.Command using the same metadata so there is no duplicate wiring

Installation

go get github.com/eosproject/urfave-cli-bind

Quick start

package main

import (
    "context"
    "log"
    "time"

    "github.com/urfave/cli/v3"
    clibind "github.com/eosproject/urfave-cli-bind"
)

type Config struct {
    Name  string        `cli:"name,n"  cliDefault:"guest" cliUsage:"User name"`
    Count int           `cli:"count"   cliDefault:"3"     cliUsage:"How many"`
    Delay time.Duration `cli:"delay"   cliDefault:"250ms" cliUsage:"Wait duration"`
}

func main() {
    app := &cli.App{
        Flags: clibind.FlagsFromStruct(Config{}),
        Action: func(ctx context.Context, cmd *cli.Command) error {
            var cfg Config
            if err := clibind.Bind(cmd, &cfg); err != nil {
                return err
            }
            log.Printf("config: %+v", cfg)
            return nil
        },
    }
    if err := app.Run(context.Background(), []string{"demo"}); err != nil {
        log.Fatal(err)
    }
}

Even quickier start

import (
    "context"
    "fmt"
    "os"

    "github.com/urfave/cli/v3"
    clibind "github.com/eosproject/urfave-cli-bind"
)

type ServerCfg struct {
    Addr string `cli:"addr"   cliDefault:"127.0.0.1:8080"`
    TLS  bool   `cli:"tls"`
}

func main() {
    app := clibind.CommandWithBinding(nil, "app", 
        func(ctx context.Context, cfg ServerCfg) error {
            fmt.Printf("serving %s tls=%v\n", cfg.Addr, cfg.TLS)
            return nil
        },
    )

    _ = app.Run(context.Background(), os.Args)
}

Tag reference

Nested structs and prefixes

• Anonymous embedded structs without cliPrefix are flattened so their fields become top-level flags.
• Named struct fields can opt-in to namespacing by providing cliPrefix. The prefix is prepended to all generated flag names and multi-character aliases, mirroring how Bind searches for values.

Binding rules

• Bind requires a non-nil pointer to a struct and mirrors the type handling used in flag generation.
• Required flags are inferred: if a field omits omitempty and lacks cliDefault, the generated flag is marked as required.
• Slices use comma-separated defaults (cliDefault:"a,b,c"), duration fields expect the Go duration syntax, and UUID fields are treated as strings and parsed inside Bind.