A comprehensive Go library for building robust command-line applications. This toolkit provides utilities for environment variable management, command-line flag handling, priority-based configuration resolution, input validation, and testing support.
- Environment Variable Management - Safe and flexible environment variable operations with type conversion
- Flag Utilities - Enhanced command-line flag handling with type-safe getters
- Configuration Resolution - Priority-based configuration resolution (CLI flags > environment variables > defaults)
- Validators - Comprehensive validation for URLs, paths, ports, host:port, and enums with SSRF protection
- Test Utilities - Helper functions for testing CLI applications and configuration resolution
go get github.com/soulteary/cli-kitimport "github.com/soulteary/cli-kit/env"
// Check if environment variable exists
if env.Has("PORT") {
// Variable is set
}
// Get with default value
port := env.Get("PORT", "8080")
// Get typed values
portInt := env.GetInt("PORT", 8080)
timeout := env.GetDuration("TIMEOUT", 5*time.Second)
enabled := env.GetBool("ENABLED", false)
ratio := env.GetFloat64("RATIO", 0.5)
// Get trimmed string (removes leading/trailing whitespace)
value := env.GetTrimmed("CONFIG_PATH", "")
// Get string slice from comma-separated value
hosts := env.GetStringSlice("HOSTS", []string{"localhost"}, ",")
// Lookup (distinguish between not set and empty)
value, ok := env.Lookup("API_KEY")
// More typed getters: GetInt64, GetUint, GetUint64import "github.com/soulteary/cli-kit/flagutil"
fs := flag.NewFlagSet("app", flag.ContinueOnError)
port := fs.Int("port", 8080, "Server port")
// Check if flag was set
if flagutil.HasFlag(fs, "port") {
// Flag was provided
}
// Get flag value with type conversion
portValue := flagutil.GetInt(fs, "port", 8080)
timeout := flagutil.GetDuration(fs, "timeout", 5*time.Second)
enabled := flagutil.GetBool(fs, "enabled", false)
// Check if flag exists in command-line arguments
if flagutil.HasFlagInOSArgs("verbose") {
// -verbose or --verbose was provided
}
// Read password from file (with security checks)
password, err := flagutil.ReadPasswordFromFile("/path/to/password.txt")
// More: HasFlagInArgs(args, name), GetFlagValue, GetString, GetInt64, GetUint, GetUint64, GetFloat64pflag support: When using spf13/pflag (short flags, deprecated marks, etc.), use the *Pflag helpers with the same semantics:
import "github.com/soulteary/cli-kit/flagutil"
"github.com/spf13/pflag"
fs := pflag.NewFlagSet("app", pflag.ContinueOnError)
fs.IntP("port", "p", 8080, "Server port")
fs.Parse(os.Args)
if flagutil.HasFlagPflag(fs, "port") {
port := flagutil.GetIntPflag(fs, "port", 8080)
}
// Also: GetStringPflag, GetBoolPflag, GetDurationPflag, GetFlagValuePflagThe configutil package resolves configuration values with a clear priority order: CLI flags > Environment variables > Default values.
import "github.com/soulteary/cli-kit/configutil"
fs := flag.NewFlagSet("app", flag.ContinueOnError)
portFlag := fs.Int("port", 0, "Server port")
fs.Parse(os.Args[1:])
// Resolve with priority: CLI flag > ENV > default
port := configutil.ResolveInt(fs, "port", "PORT", 8080, false)
host := configutil.ResolveString(fs, "host", "HOST", "localhost", true)
debug := configutil.ResolveBool(fs, "debug", "DEBUG", false)
timeout := configutil.ResolveDuration(fs, "timeout", "TIMEOUT", 30*time.Second)
// Resolve with validation
url, err := configutil.ResolveStringWithValidation(
fs, "url", "API_URL", "https://api.example.com",
true, // trimmed
func(s string) error {
return validator.ValidateURL(s, nil)
},
)
// Resolve enum value
mode, err := configutil.ResolveEnum(
fs, "mode", "APP_MODE", "production",
[]string{"development", "production", "staging"},
false, // case-insensitive
)
// Resolve host:port with validation
host, port, err := configutil.ResolveHostPort(
fs, "addr", "SERVER_ADDR", "localhost:8080",
)
// Resolve port with automatic range validation
port, err := configutil.ResolvePort(fs, "port", "PORT", 8080)pflag: With *pflag.FlagSet, use Resolve*Pflag with the same semantics. Pass an empty envKey to use only CLI and default (no environment lookup):
fs := pflag.NewFlagSet("app", pflag.ContinueOnError)
// ... define and Parse ...
port, err := configutil.ResolvePortPflag(fs, "port", "PORT", 8080)
base := configutil.ResolveBoolPflag(fs, "debug", "", false) // empty envKey: CLI or default onlyAdditional configutil APIs (same priority: CLI > ENV > default):
- ResolveInt64 / ResolveInt64WithValidation - int64 and with custom validator
- ResolveIntAsString - resolve as int but return string
- ResolveStringWithValidator - validator
func(string) bool, returns string (invalid falls back to next source) - ResolveStringWithValidation - validator
func(string) error, returns(string, error)(documented above) - ResolveStringNonEmpty - use CLI/ENV only when value is non-empty, else default
- ResolveIntWithValidation - int with custom validation
- ResolveStringSlice / ResolveStringSliceMulti - slice from comma-separated (or multi-source merge)
import "github.com/soulteary/cli-kit/validator"
// Validate URL (with SSRF protection by default)
err := validator.ValidateURL("https://api.example.com", nil)
// With custom options
opts := &validator.URLOptions{
AllowedSchemes: []string{"http", "https", "ws", "wss"},
AllowLocalhost: true,
AllowPrivateIP: false,
}
err := validator.ValidateURL("http://localhost:8080", opts)
// Validate port (range: 1-65535)
err := validator.ValidatePort(8080)
err := validator.ValidatePortString("8080")
// Validate host:port
host, port, err := validator.ValidateHostPort("localhost:8080")
// Validate host:port with defaults
host, port, err := validator.ValidateHostPortWithDefaults("myhost", "localhost", 8080)
// Validate path (with security checks)
absPath, err := validator.ValidatePath("/var/log/app.log", nil)
// With custom options
pathOpts := &validator.PathOptions{
AllowRelative: false,
AllowedDirs: []string{"/var/log", "/tmp"},
CheckTraversal: true,
}
absPath, err := validator.ValidatePath("../etc/passwd", pathOpts) // Error: path traversal
// Validate enum
err := validator.ValidateEnum("production",
[]string{"development", "production", "staging"},
false, // case-insensitive
)
// Validate numbers (positive, non-negative, range)
err := validator.ValidatePositive(42) // > 0
err = validator.ValidatePositiveInt64(100)
err = validator.ValidateNonNegative(0) // >= 0
err = validator.ValidateNonNegativeInt64(0)
err = validator.ValidateInRange(port, 1, 65535) // [min, max] inclusive
err = validator.ValidateInRangeInt64(n, 0, 100)
// Errors: validator.ErrNotPositive, validator.ErrNegative
// Validate phone number (supports multiple regions)
err := validator.ValidatePhone("13800138000", nil) // Any format
err := validator.ValidatePhoneCN("13800138000") // Chinese mainland
err := validator.ValidatePhoneUS("+12025551234") // US format
err := validator.ValidatePhoneUK("+447911123456") // UK format
// With custom options
phoneOpts := &validator.PhoneOptions{
AllowEmpty: true,
Region: validator.PhoneRegionCN,
}
err := validator.ValidatePhone("13800138000", phoneOpts)
// Validate email
err := validator.ValidateEmailSimple("user@example.com")
// With domain restrictions
err := validator.ValidateEmailWithDomains("user@company.com", []string{"company.com"})
// With full options
emailOpts := &validator.EmailOptions{
AllowEmpty: false,
AllowedDomains: []string{"company.com", "corp.com"},
BlockedDomains: []string{"spam.com"},
}
err := validator.ValidateEmail("user@company.com", emailOpts)
// Validate username
err := validator.ValidateUsername("john_doe", nil) // Default style (3-32 chars)
err := validator.ValidateUsernameSimple("johndoe") // Alphanumeric only
err := validator.ValidateUsernameRelaxed("john.doe") // Allows dots (3-64 chars)
// With reserved names
err := validator.ValidateUsernameWithReserved("admin", []string{"admin", "root", "system"})import (
"github.com/soulteary/cli-kit/testutil"
"testing"
)
// Environment variable management in tests
func TestMyFunction(t *testing.T) {
envMgr := testutil.NewEnvManager()
defer envMgr.Cleanup() // Automatically restores original values
envMgr.Set("PORT", "8080")
envMgr.SetMultiple(map[string]string{
"HOST": "localhost",
"DEBUG": "true",
})
// Your test code here
}
// Flag parsing helper
func TestFlags(t *testing.T) {
fs := testutil.NewTestFlagSet("test")
port := fs.Int("port", 8080, "port")
err := testutil.ParseFlags(fs, []string{"-port", "9090"})
if err != nil {
t.Fatal(err)
}
// Or use MustParseFlags to panic on error
testutil.MustParseFlags(fs, []string{"-port", "9090"})
}
// Table-driven configuration tests (ENV and default only).
// RunConfigTests injects EnvVars for each case; it does NOT pass CLIArgs to the resolver.
// To test "CLI flag takes priority", use a separate test that parses flags and asserts.
func TestConfigResolution(t *testing.T) {
cases := []testutil.ConfigTestCase{
{
Name: "ENV used when set",
EnvVars: map[string]string{"PORT": "8080"},
Expected: 8080,
},
{
Name: "Default used when neither set",
EnvVars: map[string]string{},
Expected: 3000,
},
}
resolver := func(fs *flag.FlagSet, envVars map[string]string) (interface{}, error) {
fs.Int("port", 0, "Port")
if err := fs.Parse([]string{}); err != nil {
return nil, err
}
return configutil.ResolveInt(fs, "port", "PORT", 3000, false), nil
}
testutil.RunConfigTests(t, cases, resolver)
}cli-kit/
├── env/ # Environment variable utilities
│ └── env.go # Get, GetInt, GetBool, GetDuration, etc.
├── flagutil/ # Command-line flag utilities
│ └── flagutil.go # HasFlag, GetInt, ReadPasswordFromFile, etc.
├── configutil/ # Configuration resolution with priority
│ └── priority.go # ResolveString, ResolveInt, ResolveEnum, etc.
├── validator/ # Input validation
│ ├── url.go # URL validation with SSRF protection
│ ├── path.go # Path validation with traversal protection
│ ├── port.go # Port range validation
│ ├── hostport.go # Host:port format validation
│ ├── enum.go # Enum value validation
│ ├── number.go # Numeric validation (positive, non-negative, range)
│ ├── phone.go # Phone number validation (CN/US/UK/International)
│ ├── email.go # Email address validation with domain control
│ └── username.go # Username format validation with styles
└── testutil/ # Testing utilities
├── env.go # Environment variable test helpers
├── flag.go # Flag parsing test helpers
└── config.go # Configuration test helpers
| Feature | Description |
|---|---|
| SSRF Protection | URL validator blocks private IPs and localhost by default |
| Path Traversal Prevention | Path validator detects and blocks .. sequences |
| Directory Restrictions | Optional allowlist for permitted directories |
| Safe File Reading | Password file reading with path validation |
This project maintains high test coverage:
| Package | Coverage |
|---|---|
| configutil | 100% |
| env | 100% |
| flagutil | 100% |
| validator | 91.9% |
| testutil | 86.7% |
| Total | 94.6% |
Run tests with coverage:
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out- Go 1.26 or later
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.