{"id":28504273,"url":"https://github.com/eugener/clix","last_synced_at":"2025-07-06T04:32:24.284Z","repository":{"id":297638077,"uuid":"997427579","full_name":"eugener/clix","owner":"eugener","description":"Modern Go CLI framework with fluent API, type safety \u0026 zero-config magic. Features automatic   configuration, interactive prompting, intelligent errors \u0026 POSIX compliance. Build production   CLIs with 60% less code using Go generics.","archived":false,"fork":false,"pushed_at":"2025-06-06T14:48:01.000Z","size":6586,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-06T15:28:51.342Z","etag":null,"topics":["autocomplete","cli","cli-frameowrk","command-line","configuration","developer-experience","error-handling","fluent-api","frameowrk","generics","go","go-framework","golang","interactive","json","middleware","posix","type-safe","yaml","zero-config"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eugener.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-06T14:04:45.000Z","updated_at":"2025-06-06T14:48:04.000Z","dependencies_parsed_at":"2025-06-06T15:40:39.927Z","dependency_job_id":null,"html_url":"https://github.com/eugener/clix","commit_stats":null,"previous_names":["eugener/clix"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eugener%2Fclix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eugener%2Fclix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eugener%2Fclix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eugener%2Fclix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eugener","download_url":"https://codeload.github.com/eugener/clix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eugener%2Fclix/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":258642495,"owners_count":22734669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["autocomplete","cli","cli-frameowrk","command-line","configuration","developer-experience","error-handling","fluent-api","frameowrk","generics","go","go-framework","golang","interactive","json","middleware","posix","type-safe","yaml","zero-config"],"created_at":"2025-06-08T18:04:48.871Z","updated_at":"2025-07-06T04:32:24.278Z","avatar_url":"https://github.com/eugener.png","language":"Go","readme":"# Modern Go CLI Framework\n\nA powerful, type-safe, and developer-friendly CLI framework for Go with fluent API, automatic configuration management, and comprehensive developer experience features.\n\n## 🚀 Features\n\n### Developer Experience\n- **Fluent API**: Method chaining for intuitive application building\n- **Smart Defaults**: Convention over configuration with sensible presets\n- **Interactive Mode**: Automatic prompting for missing required fields\n- **Intelligent Errors**: Context-aware error messages with suggestions\n- **Auto-completion**: Shell completion for bash, zsh, and fish\n\n### Framework Capabilities\n- **Type-Safe Commands**: Generic `Command[T]` interface with compile-time type checking\n- **POSIX Compliance**: Full POSIX argument parsing with advanced flag handling\n- **Configuration Management**: YAML/JSON config files with CLI override precedence\n- **Environment Integration**: Automatic environment variable binding\n- **Middleware Pipeline**: Composable execution with recovery, logging, and timeout\n- **Modern Go**: Uses generics, slog, context, and Go 1.21+ features\n\n## 📦 Installation\n\n```bash\ngo get github.com/yourorg/go-cli-framework\n```\n\n## 🏃 Quick Start\n\n### Ultra-Simple CLI (1 line)\n\n```go\npackage main\n\nimport \"github.com/yourorg/go-cli-framework/cli\"\n\nfunc main() {\n    cli.Quick(\"my-app\",\n        cli.Cmd(\"hello\", \"Say hello\", func() error {\n            fmt.Println(\"Hello, World!\")\n            return nil\n        }),\n    )\n}\n```\n\n### Fluent API (Recommended)\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"github.com/yourorg/go-cli-framework/cli\"\n)\n\nfunc main() {\n    cli.New(\"my-app\").\n        Version(\"1.0.0\").\n        Description(\"My awesome CLI\").\n        Interactive().        // Prompt for missing fields\n        AutoConfig().        // Load config files automatically\n        Recovery().          // Handle panics gracefully\n        WithCommands(\n            cli.Cmd(\"deploy\", \"Deploy application\", deployHandler),\n            cli.VersionCmd(\"1.0.0\"),\n        ).\n        RunWithArgs(context.Background())\n}\n```\n\n### Advanced Configuration\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"github.com/yourorg/go-cli-framework/cli\"\n    \"github.com/yourorg/go-cli-framework/core\"\n)\n\ntype DeployConfig struct {\n    Environment string   `posix:\"e,env,Environment,choices=dev;staging;prod;required\"`\n    Version     string   `posix:\"v,version,Version to deploy,required\"`\n    Replicas    int      `posix:\"r,replicas,Number of replicas,default=3\"`\n    DryRun      bool     `posix:\",dry-run,Perform a dry run\"`\n}\n\nfunc main() {\n    cli.New(\"deploy-tool\").\n        Version(\"2.0.0\").\n        Description(\"Application deployment tool\").\n        Interactive().\n        AutoConfig().\n        WithCommands(\n            core.NewCommand(\"deploy\", \"Deploy application\", \n                func(ctx context.Context, config DeployConfig) error {\n                    if config.DryRun {\n                        fmt.Printf(\"DRY RUN: Would deploy %s to %s\\n\", \n                            config.Version, config.Environment)\n                    } else {\n                        fmt.Printf(\"Deploying %s to %s with %d replicas\\n\", \n                            config.Version, config.Environment, config.Replicas)\n                    }\n                    return nil\n                }),\n        ).\n        RunWithArgs(context.Background())\n}\n```\n\n## 📋 Configuration Management\n\nThe framework supports multiple configuration sources with proper precedence:\n\n**CLI Arguments \u003e Config Files \u003e Environment Variables \u003e Defaults**\n\n### Config File (deploy-tool.yaml)\n```yaml\nenvironment: \"staging\"\nversion: \"1.0.0\"\nreplicas: 5\n```\n\n### Usage Examples\n```bash\n# Uses config file values\n./deploy-tool deploy\n\n# CLI args override config file\n./deploy-tool deploy --env prod --replicas 10\n\n# Interactive mode prompts for missing required fields\n./deploy-tool deploy  # Will prompt for missing env and version\n```\n\n## 🎯 Presets for Common Scenarios\n\n```go\n// Development: interactive, colors, recovery, logging\ncli.Dev(\"my-app\", commands...)\n\n// Production: logging, recovery, no colors, optimized\ncli.Prod(\"my-app\", commands...)\n\n// Minimal: just basic recovery\ncli.Quick(\"my-app\", commands...)\n```\n\n## 🔧 Advanced Features\n\n### Middleware and Hooks\n\n```go\napp := cli.New(\"my-app\").\n    Recovery().                    // Panic recovery\n    Logging().                     // Command execution logging\n    Timeout(30 * time.Second).     // Command timeout\n    BeforeAll(startupHook).        // Run before any command\n    AfterAll(cleanupHook).         // Run after any command\n    BeforeEach(commandSetup).      // Run before each command\n    AfterEach(commandTeardown)     // Run after each command\n```\n\n### Environment Variables\n\n```go\ntype Config struct {\n    APIKey    string `posix:\"k,key,API key,env=API_KEY,required\"`\n    LogLevel  string `posix:\"l,log,Log level,env=LOG_LEVEL,default=info\"`\n    Database  string `posix:\"d,db,Database URL,env=DATABASE_URL\"`\n}\n```\n\n### Validation and Choices\n\n```go\ntype Config struct {\n    Environment string `posix:\"e,env,Environment,choices=dev;staging;prod;required\"`\n    Port        int    `posix:\"p,port,Port number,default=8080\"`\n    Workers     int    `posix:\"w,workers,Worker count,default=4\"`\n}\n```\n\n## 📚 Examples\n\nThe `examples/` directory contains comprehensive demonstrations:\n\n- **simple/**: Traditional struct-based approach\n- **fluent-api/**: Modern fluent API showcase\n- **config/**: Configuration file management\n- **interactive/**: Interactive prompting features\n- **advanced/**: Complete feature demonstration\n\n```bash\ncd examples/fluent-api\ngo run main.go --help\n```\n\n## 🏗️ Architecture\n\n### Clean Package Structure\n\n**Public API (what you import):**\n- **`cli/`**: Fluent API with method chaining and smart defaults (recommended)\n- **`core/`**: Advanced struct-based command configuration\n- **`app/`**: Traditional application builder (backward compatible)  \n- **`config/`**: Configuration options and presets\n\n**Implementation Details:**\n- **`internal/`**: All implementation details (parsing, help, prompting, etc.)\n\n### Typical Import Patterns\n\n**Modern approach (recommended):**\n```go\nimport \"github.com/yourorg/go-cli-framework/cli\"          // 90% of use cases\nimport \"github.com/yourorg/go-cli-framework/core\"         // For struct-based commands\n```\n\n**Traditional approach (backward compatible):**\n```go\nimport \"github.com/yourorg/go-cli-framework/app\"          // Traditional builder\nimport \"github.com/yourorg/go-cli-framework/config\"       // Configuration options  \nimport \"github.com/yourorg/go-cli-framework/core\"         // Command registration\n```\n\n### Backward Compatibility\n\nThe framework maintains full backward compatibility:\n\n```go\n// Traditional approach (still supported)\napp := app.NewApplicationWithOptions(\n    config.WithName(\"my-app\"),\n    config.WithRecovery(),\n    config.WithLogging(),\n)\napp.Register(core.NewCommand(\"cmd\", \"description\", handler))\n\n// New fluent approach (recommended)\ncli.New(\"my-app\").Recovery().Logging().WithCommands(\n    cli.Cmd(\"cmd\", \"description\", handler),\n).Build()\n```\n\n## 🧪 Testing\n\nThe framework provides testing utilities for CLI applications:\n\n```go\nfunc TestMyCommand(t *testing.T) {\n    app := cli.New(\"test-app\").WithCommands(myCommand)\n    \n    // Test command execution\n    exitCode := app.Run(context.Background(), []string{\"my-command\", \"--flag\", \"value\"})\n    assert.Equal(t, 0, exitCode)\n}\n```\n\n## 📈 Performance\n\n- **Zero allocations** in hot paths\n- **Lazy evaluation** of help text and completions\n- **Efficient parsing** with minimal string operations\n- **Concurrent-safe** command registration and execution\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## 🙏 Acknowledgments\n\nInspired by modern CLI frameworks like Cobra, urfave/cli, and Kingpin, but designed specifically for Go's type system and modern language features.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feugener%2Fclix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feugener%2Fclix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feugener%2Fclix/lists"}