{"id":32044437,"url":"https://github.com/agilira/flash-flags","last_synced_at":"2026-04-11T12:21:36.171Z","repository":{"id":311952105,"uuid":"1045705513","full_name":"agilira/flash-flags","owner":"agilira","description":"FlashFlags is an ultra-fast, zero-dependency, lock-free command-line flag parsing library for Go. Originally built for Argus, it provides great performance while maintaining simplicity and ease of use.","archived":false,"fork":false,"pushed_at":"2025-10-17T14:07:54.000Z","size":181,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-25T22:47:53.824Z","etag":null,"topics":["command-line","configuration-files","evironmental-variables","fast","flags","go","help-system","lock-free","posix","stdlib-replacement","validation","zero-dependencies"],"latest_commit_sha":null,"homepage":"https://github.com/agilira/flash-flags","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agilira.png","metadata":{"files":{"readme":"README.md","changelog":"changelog/v1.0.0.txt","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY_POLICY.yml","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-27T15:35:10.000Z","updated_at":"2025-10-25T03:10:46.000Z","dependencies_parsed_at":"2025-08-28T01:46:23.762Z","dependency_job_id":"d7003a5f-a2f1-4d8a-94ef-2545034f1897","html_url":"https://github.com/agilira/flash-flags","commit_stats":null,"previous_names":["agilira/flash-flags"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/agilira/flash-flags","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fflash-flags","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fflash-flags/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fflash-flags/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fflash-flags/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agilira","download_url":"https://codeload.github.com/agilira/flash-flags/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Fflash-flags/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28440396,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:34:46.850Z","status":"ssl_error","status_checked_at":"2026-01-15T00:34:46.551Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","configuration-files","evironmental-variables","fast","flags","go","help-system","lock-free","posix","stdlib-replacement","validation","zero-dependencies"],"created_at":"2025-10-17T19:00:54.792Z","updated_at":"2026-04-11T12:21:36.152Z","avatar_url":"https://github.com/agilira.png","language":"Go","readme":"# FlashFlags: Ultra-fast command-line flag parsing for Go\n### an AGILira library\n\n[![CI/CD Pipeline](https://github.com/agilira/flash-flags/actions/workflows/ci.yml/badge.svg)](https://github.com/agilira/flash-flags/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/agilira/flash-flags/actions/workflows/codeql.yml/badge.svg)](https://github.com/agilira/flash-flags/actions/workflows/codeql.yml)\n[![Security](https://img.shields.io/badge/security-gosec-brightgreen.svg)](https://github.com/agilira/flash-flags/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/agilira/flash-flags?v=2)](https://goreportcard.com/report/github.com/agilira/flash-flags)\n[![Coverage](https://img.shields.io/badge/coverage-94.2%25-brightgreen.svg)](https://github.com/agilira/flash-flags)\n[![GoDoc](https://godoc.org/github.com/agilira/flash-flags?status.svg)](https://godoc.org/github.com/agilira/flash-flags)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)\n\nFlashFlags is an ultra-fast, zero-dependency, lock-free command-line flag parsing library for Go. Originally built for [Argus](https://github.com/agilira/argus), it provides great performance while maintaining simplicity and ease of use. FlashFlags serves as the core parsing engine for our CLI framework [Orpheus](https://github.com/agilira/orpheus).\n\n## Live Demo\n\n\u003cdiv align=\"center\"\u003e\n\nSee Flash-Flags in action - POSIX-compliant stdlib replacement with JSON config support:\n\n\u003cpicture\u003e\n  \u003csource media=\"(max-width: 768px)\" srcset=\"https://asciinema.org/a/m8RDmYkLaWEvxxN8Zd1Xj9SKR.svg\" width=\"100%\"\u003e\n  \u003csource media=\"(max-width: 1024px)\" srcset=\"https://asciinema.org/a/m8RDmYkLaWEvxxN8Zd1Xj9SKR.svg\" width=\"90%\"\u003e\n  \u003cimg src=\"https://asciinema.org/a/m8RDmYkLaWEvxxN8Zd1Xj9SKR.svg\" alt=\"Flash-Flags CLI Demo\" style=\"max-width: 100%; height: auto;\" width=\"800\"\u003e\n\u003c/picture\u003e\n\n*[Click to view interactive demo](https://asciinema.org/a/m8RDmYkLaWEvxxN8Zd1Xj9SKR)*\n\n\u003c/div\u003e\n\n**[Features](#features) • [Quick Start](#quick-start) • [Performance](#performance) • [Demo](#demo) • [Flag Types](#supported-flag-types) • [Configuration](#configuration-priority) • [Examples](#real-world-example)**\n\n## Features\n\n- **Security-Hardened**: Built-in protection against injection attacks, path traversal, and buffer overflows\n- **Ultra-Fast**: 85% of stdlib performance with comprehensive security validation\n- **Zero Dependencies**: Can be use as drop-in stdlib replacement with security\n- **Concurrent-Safe**: Safe for concurrent reads after Parse() -- no locks needed at runtime\n- **Configuration Files**: JSON config file support with auto-discovery\n- **Environment Variables**: Automatic environment variable integration\n- **Validation**: Built-in validation system with custom validators\n- **Help System**: Professional help output with grouping\n- **Dependencies**: Flag dependency management\n- **Type Safety**: Strong typing for all flag types\n- **POSIX/GNU Syntax**: Complete flag syntax support including combined short flags\n- **Flexible Parsing**: Support for `-f=value` and `-abc` combined syntax\n\n### Security Features\n\nFlash-flags provides comprehensive security hardening:\n\n- **Command Injection Protection**: Blocks `$(...)`, backticks, and shell metacharacters\n- **Path Traversal Prevention**: Prevents `../` and `..\\\\` directory traversal attacks  \n- **Buffer Overflow Safeguards**: 10KB input limits with fast-path optimization\n- **Format String Attack Blocking**: Detects and blocks `%n`, `%s` format string exploits\n- **Input Sanitization**: Removes null bytes and dangerous control characters\n- **Windows Device Protection**: Blocks Windows reserved names (CON, PRN, AUX, etc.)\n\n**Security overhead**: Only 132ns per operation (17%) for complete protection\n\n## Compatibility and Support\n\nFlashFlags is designed for Go 1.23+ environments and follows Long-Term Support guidelines to ensure consistent performance across production deployments.\n\n## Performance\n\nFlashFlags delivers exceptional performance with security-hardened parsing:\n\n```\nAMD Ryzen 5 7520U \nBenchmarkFlashFlags-8      1,294,699    924 ns/op     945 B/op    11 allocs/op\nBenchmarkStdFlag-8         1,527,176    792 ns/op     945 B/op    13 allocs/op  \nBenchmarkPflag-8             785,904   1322 ns/op    1569 B/op    21 allocs/op  \nBenchmarkGoFlags-8           147,394   7460 ns/op    5620 B/op    61 allocs/op  \nBenchmarkKingpin-8           150,154   7567 ns/op    6504 B/op    97 allocs/op  \n```\n\n**Only 132ns overhead for complete protection against injection attacks**\n\n**Reproduce benchmarks**:\n```bash\ncd benchmarks \u0026\u0026 go test -bench=. -benchmem\n```\n\n## Quick Start\n\n### Installation\n\n```bash\ngo get github.com/agilira/flash-flags\n```\n### Basic Usage\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"os\"\n    \n    \"github.com/agilira/flash-flags\"\n)\n\nfunc main() {\n    // Create flag set\n    fs := flashflags.New(\"myapp\")\n    \n    // Register flags\n    host := fs.StringVar(\"host\", \"h\", \"localhost\", \"Server host\")\n    port := fs.IntVar(\"port\", \"p\", 8080, \"Server port\")\n    verbose := fs.BoolVar(\"verbose\", \"v\", false, \"Enable verbose logging\")\n    \n    // Parse arguments\n    if err := fs.Parse(os.Args[1:]); err != nil {\n        if err.Error() == \"help requested\" {\n            os.Exit(0) // Help was shown\n        }\n        fmt.Printf(\"Error: %v\\n\", err)\n        os.Exit(1)\n    }\n    \n    // Use flags\n    fmt.Printf(\"Server starting on %s:%d (verbose: %t)\\n\", *host, *port, *verbose)\n}\n```\n\n### Usage Examples\n\n```bash\n# Basic usage\n./myapp --host 0.0.0.0 --port 3000 --verbose\n\n# Short flags with space\n./myapp -h 0.0.0.0 -p 3000 -v\n\n# Short flags with equals (NEW!)\n./myapp -h=192.168.1.1 -p=8080 -v=true\n\n# Combined short flags (NEW!)\n./myapp -hvp 3000              # -h -v -p 3000\n./myapp -abc                   # -a -b -c (all boolean)\n\n# Mixed formats\n./myapp --host=192.168.1.1 -vp 8080 --debug=false\n\n# Environment variables + CLI\nMYAPP_HOST=api.example.com ./myapp -p=3000 --verbose\n\n# Help\n./myapp --help\n```\n\n### Flag Syntax\n\nFlashFlags supports comprehensive POSIX/GNU-style flag syntax for maximum compatibility:\n\n### Long Flags\n```bash\n--flag value          # Space-separated value\n--flag=value          # Equals-separated value  \n--boolean-flag        # Boolean without value (true)\n--boolean-flag=false  # Explicit boolean value\n```\n\n### Short Flags\n```bash\n-f value              # Space-separated value\n-f=value              # Equals-separated value (NEW!)\n-b                    # Boolean short flag (true)\n-b=false              # Explicit boolean value\n```\n\n### Combined Short Flags\n```bash\n-abc                  # Equivalent to -a -b -c (all boolean)\n-abc value            # Last flag gets the value: -a -b -c value\n-vdp 8080             # Verbose + debug + port: -v -d -p 8080\n```\n\n**Rules for combined flags:**\n- All flags except the last must be boolean\n- The last flag can be any type and consumes the next argument\n- Example: `-vhp 3000` sets verbose=true, help=true, port=3000\n\n### Drop-in Stdlib Replacement\n\nFlash-flags includes a complete drop-in replacement for Go's standard `flag` package. Migrate with zero code changes:\n\n```go\n// Before - using stdlib\nimport \"flag\"\n\n// After - using flash-flags\nimport \"github.com/antonio-giordano/flash-flags/stdlib/flag\"\n\n// All your existing code works unchanged!\nvar name = flag.String(\"name\", \"default\", \"description\")\nvar count = flag.Int(\"count\", 42, \"number of items\")\n\nfunc main() {\n    flag.Parse()\n    fmt.Printf(\"Name: %s, Count: %d\\n\", *name, *count)\n    \n    // Full remaining arguments support\n    for i := 0; i \u003c flag.NArg(); i++ {\n        fmt.Printf(\"Arg[%d]: %s\\n\", i, flag.Arg(i))\n    }\n}\n```\n\nSee the [stdlib example](examples/stdlib-drop-in/) for a complete working demonstration.\n\n## Examples\n\n- **[Examples](examples/)** - Real-world examples and integrations\n\n## Supported Flag Types\n\n| Type | Go Type | Example | Description |\n|------|---------|---------|-------------|\n| `string` | `string` | `--name \"John\"` | Text values |\n| `int` | `int` | `--port 8080` | Integer numbers |\n| `bool` | `bool` | `--verbose` | Boolean flags |\n| `float64` | `float64` | `--rate 0.75` | Floating point numbers |\n| `duration` | `time.Duration` | `--timeout 30s` | Time durations |\n| `stringSlice` | `[]string` | `--tags web,api` | Comma-separated lists |\n\n## Configuration Priority\n\nFlashFlags applies configuration in this priority order (higher numbers override lower):\n\n1. **Default values** (lowest priority)\n2. **Configuration file** values\n3. **Environment variables**\n4. **Command-line arguments** (highest priority)\n\n### Configuration File Example\n\n```json\n{\n  \"host\": \"0.0.0.0\",\n  \"port\": 3000,\n  \"workers\": 8,\n  \"enable-tls\": true,\n  \"tags\": [\"web\", \"api\", \"production\"],\n  \"timeout\": \"60s\"\n}\n```\n\n### Environment Variables\n\n```bash\n# With prefix\nexport MYAPP_HOST=localhost\nexport MYAPP_PORT=8080\n\n# Custom names\nexport DATABASE_URL=postgres://...\n```\n\n## Validation \u0026 Constraints\n\n```go\n// Custom validation\nfs.SetValidator(\"port\", func(val interface{}) error {\n    port := val.(int)\n    if port \u003c 1024 || port \u003e 65535 {\n        return fmt.Errorf(\"port must be between 1024 and 65535\")\n    }\n    return nil\n})\n\n// Required flags\nfs.SetRequired(\"api-key\")\n\n// Flag dependencies\nfs.SetDependencies(\"tls-cert\", \"enable-tls\")\n```\n\n## Real-World Example\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"log\"\n    \"os\"\n    \"time\"\n    \n    \"github.com/agilira/flash-flags\"\n)\n\nfunc main() {\n    fs := flashflags.New(\"webserver\")\n    fs.SetDescription(\"High-performance web server\")\n    fs.SetVersion(\"v1.0.0\")\n    \n    // Server configuration\n    host := fs.StringVar(\"host\", \"h\", \"localhost\", \"Server host\")\n    port := fs.IntVar(\"port\", \"p\", 8080, \"Server port\")\n    workers := fs.Int(\"workers\", 4, \"Number of worker threads\")\n    \n    // TLS configuration  \n    enableTLS := fs.Bool(\"enable-tls\", false, \"Enable TLS\")\n    tlsCert := fs.String(\"tls-cert\", \"\", \"TLS certificate file\")\n    tlsKey := fs.String(\"tls-key\", \"\", \"TLS private key file\")\n    \n    // Performance tuning\n    timeout := fs.Duration(\"timeout\", 30*time.Second, \"Request timeout\")\n    maxConns := fs.Int(\"max-connections\", 1000, \"Maximum connections\")\n    \n    // Logging\n    logLevel := fs.String(\"log-level\", \"info\", \"Log level (debug, info, warn, error)\")\n    logFile := fs.String(\"log-file\", \"\", \"Log file path (empty for stdout)\")\n    \n    // Environment and config\n    fs.SetEnvPrefix(\"WEBSERVER\")\n    fs.AddConfigPath(\"./config\")\n    fs.AddConfigPath(\"/etc/webserver\")\n    \n    // Organize help output\n    fs.SetGroup(\"host\", \"Server Options\")\n    fs.SetGroup(\"port\", \"Server Options\")\n    fs.SetGroup(\"workers\", \"Server Options\")\n    fs.SetGroup(\"enable-tls\", \"TLS Options\")\n    fs.SetGroup(\"tls-cert\", \"TLS Options\")\n    fs.SetGroup(\"tls-key\", \"TLS Options\")\n    \n    // Validation\n    fs.SetValidator(\"port\", func(val interface{}) error {\n        port := val.(int)\n        if port \u003c 1 || port \u003e 65535 {\n            return fmt.Errorf(\"port must be between 1 and 65535\")\n        }\n        return nil\n    })\n    \n    fs.SetValidator(\"log-level\", func(val interface{}) error {\n        level := val.(string)\n        validLevels := []string{\"debug\", \"info\", \"warn\", \"error\"}\n        for _, valid := range validLevels {\n            if level == valid {\n                return nil\n            }\n        }\n        return fmt.Errorf(\"log-level must be one of: debug, info, warn, error\")\n    })\n    \n    // Dependencies\n    fs.SetDependencies(\"tls-cert\", \"enable-tls\")\n    fs.SetDependencies(\"tls-key\", \"enable-tls\")\n    \n    // Parse\n    if err := fs.Parse(os.Args[1:]); err != nil {\n        if err.Error() == \"help requested\" {\n            os.Exit(0)\n        }\n        log.Fatalf(\"Error: %v\", err)\n    }\n    \n    // Use configuration\n    fmt.Printf(\"Starting web server:\\n\")\n    fmt.Printf(\"  Host: %s\\n\", *host)\n    fmt.Printf(\"  Port: %d\\n\", *port)\n    fmt.Printf(\"  Workers: %d\\n\", *workers)\n    fmt.Printf(\"  TLS: %v\\n\", *enableTLS)\n    fmt.Printf(\"  Timeout: %v\\n\", *timeout)\n    fmt.Printf(\"  Max Connections: %d\\n\", *maxConns)\n    fmt.Printf(\"  Log Level: %s\\n\", *logLevel)\n    if *logFile != \"\" {\n        fmt.Printf(\"  Log File: %s\\n\", *logFile)\n    }\n    \n    // Start your server here...\n}\n```\n\n## License\n\nflash-flags is licensed under the [Mozilla Public License 2.0](./LICENSE.md).\n\n---\n\nflash-flags • an AGILira library\n","funding_links":[],"categories":["命令行","Command Line","Build Automation"],"sub_categories":["标准CLI","Standard CLI"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagilira%2Fflash-flags","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagilira%2Fflash-flags","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagilira%2Fflash-flags/lists"}