{"id":32044439,"url":"https://github.com/agilira/orpheus","last_synced_at":"2026-05-03T00:04:28.449Z","repository":{"id":314275275,"uuid":"1054490462","full_name":"agilira/orpheus","owner":"agilira","description":"Orpheus is a high-performance CLI framework designed to be super simple and ~30× faster than popular alternatives with zero external dependencies. Built on FlashFlags, Orpheus provides a simple interface to create modern, fast CLI apps similar to git.","archived":false,"fork":false,"pushed_at":"2026-01-13T19:08:44.000Z","size":2279,"stargazers_count":27,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-17T22:55:03.379Z","etag":null,"topics":["agilira","cli","cli-app","commandline","flash-flags","go","performance","pluggable-storage","plugin-system","secure","sub-command"],"latest_commit_sha":null,"homepage":"https://github.com/agilira/orpheus","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":"SECURITY.md","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-09-10T23:22:21.000Z","updated_at":"2026-02-16T15:46:21.000Z","dependencies_parsed_at":"2025-09-11T15:46:02.068Z","dependency_job_id":"cc04ca3c-f2aa-4a65-bf03-f3752c40004b","html_url":"https://github.com/agilira/orpheus","commit_stats":null,"previous_names":["agilira/orpheus"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/agilira/orpheus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Forpheus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Forpheus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Forpheus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Forpheus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agilira","download_url":"https://codeload.github.com/agilira/orpheus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agilira%2Forpheus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32553693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T22:28:24.418Z","status":"ssl_error","status_checked_at":"2026-05-02T22:28:14.225Z","response_time":132,"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":["agilira","cli","cli-app","commandline","flash-flags","go","performance","pluggable-storage","plugin-system","secure","sub-command"],"created_at":"2025-10-17T19:00:54.895Z","updated_at":"2026-05-03T00:04:28.443Z","avatar_url":"https://github.com/agilira.png","language":"Go","funding_links":[],"categories":["Command Line","命令行","Build Automation"],"sub_categories":["Standard CLI","标准CLI"],"readme":"# Orpheus: High-Performance CLI framework for Go\n\n![Orpheus Banner](assets/banner.png)\n\n[![CI/CD Pipeline](https://github.com/agilira/orpheus/actions/workflows/ci.yml/badge.svg)](https://github.com/agilira/orpheus/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/agilira/orpheus/actions/workflows/codeql.yml/badge.svg)](https://github.com/agilira/orpheus/actions/workflows/codeql.yml)\n[![Security](https://img.shields.io/badge/security-gosec-brightgreen.svg)](https://github.com/agilira/orpheus/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/agilira/orpheus?v=2)](https://goreportcard.com/report/github.com/agilira/orpheus)\n[![Coverage](https://img.shields.io/badge/coverage-87.2%25-brightgreen.svg)](https://github.com/agilira/orpheus/actions/workflows/ci.yml)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/11276/badge)](https://www.bestpractices.dev/projects/11276)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)\n\nOrpheus is a high-performance CLI framework designed to be super simple and **~30x faster** than popular alternatives with zero third-party dependencies. Built on [FlashFlags](https://github.com/agilira/flash-flags) \u0026 [go-errors](https://github.com/agilira/go-errors), Orpheus provides a simple interface to create modern, secure, fast CLI apps similar to git.\n\n## Live Demo\n\n\u003cdiv align=\"center\"\u003e\n\nSee Orpheus in action - building a Git-like CLI with subcommands in minutes:\n\n\u003cpicture\u003e\n  \u003csource media=\"(max-width: 768px)\" srcset=\"https://asciinema.org/a/ohd8JUmxPPyCcKBH.svg\" width=\"100%\"\u003e\n  \u003csource media=\"(max-width: 1024px)\" srcset=\"https://asciinema.org/a/ohd8JUmxPPyCcKBH.svg\" width=\"90%\"\u003e\n  \u003cimg src=\"https://asciinema.org/a/ohd8JUmxPPyCcKBH.svg\" alt=\"Orpheus 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/ohd8JUmxPPyCcKBH)*\n\n\u003c/div\u003e\n\n**[Features](#features) • [Performance](#performance) • [Security](#security) • [Quick Start](#quick-start) • [Storage System](#storage-system) • [Observability](#production-observability) • [Examples](#examples) • [API Reference](#api-reference) • [Philosophy](#the-philosophy-behind-orpheus)**\n\n## Features\n\n- **Zero Third-Party Dependencies**: Built exclusively on AGILira libraries and Go extended standard library (`golang.org/x`)\n- **Native Subcommands**: Git-style nested commands with automatic help generation\n- **Pluggable Storage System**: Dynamic .so plugin loading for persistent storage (SQLite, Redis, File, custom providers)\n- **Clean API**: Fluent interface for rapid development\n- **Auto-completion**: Built-in bash/zsh/fish completion generation\n- **Type-safe Errors**: Structured error handling with exit codes\n- **Hot-swappable Commands**: Dynamic command registration and modification\n- **Production Observability**: Zero-overhead logging, audit trails, tracing, and metrics interfaces\n- **Interactive Prompts**: Built-in `Prompter` interface for user input (text, secrets, menus, confirmations) with terminal-safe masking\n- **Secure by Design**: [Red-team tested](./pkg/orpheus/security_test.go) and [fuzz tested](./pkg/orpheus/orpheus_fuzz_test.go)\n- **Security Validation**: Including input sanitization, path traversal protection, and various security controls\n\n## Compatibility and Support\n\nOrpheus is designed for Go 1.23+ environments and follows Long-Term Support guidelines to ensure consistent performance across production deployments.\n\n## Performance\n\nBenchmark results comparing CLI framework performance:\n\n```\nAMD Ryzen 5 7520U with Radeon Graphics\nBenchmarkOrpheus-8       1908495           634.5 ns/op          96 B/op       3 allocs/op\nBenchmarkCobra-8              66        18439562 ns/op        3145 B/op      33 allocs/op\nBenchmarkUrfaveCli-8       40767           30097 ns/op        8549 B/op     318 allocs/op\nBenchmarkKingpin-8        293697           4294 ns/op         1988 B/op      40 allocs/op\nBenchmarkStdFlag-8       1027216           1039 ns/op          945 B/op      13 allocs/op\n```\n\n**Scenario**: Command parsing with 3 flags (string, bool, string) and handler execution.\n\n**Reproduce benchmarks**:\n```bash\ncd benchmarks/\ngo test -bench=. -benchmem\n```\n\n**[Complete Performance Benchmarks →](./benchmarks/benchmark_test.go)**\n\n## Security\n\nOrpheus implements defense-in-depth security with comprehensive validation against CLI attack vectors.\n\n**Protected Vectors:**\n- Path traversal (case-insensitive, URL encoding, Windows device names)\n- Command/SQL/Script injection prevention\n- Control character and null byte filtering\n- Cross-platform consistency (Windows, Linux, macOS)\n\n**Run Security Tests:**\n```bash\nmake security      # Run security test suite\nmake fuzz          # Quick fuzz testing (30s)\nmake fuzz-long     # Extended fuzzing (5min)\n```\n\n## Quick Start\n\n### Installation\n\n```bash\ngo get github.com/agilira/orpheus@v1.0.10  # Latest stable release\n# or simply\ngo get github.com/agilira/orpheus          # Always latest\n```\n\n### Basic Usage\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"log\"\n    \"os\"\n    \n    \"github.com/agilira/orpheus\"\n)\n\nfunc main() {\n    app := orpheus.New(\"myapp\").\n        SetDescription(\"My awesome CLI application\").\n        SetVersion(\"1.0.0\")\n\n    // Add commands with fluent interface\n    app.Command(\"start\", \"Start the service\", func(ctx *orpheus.Context) error {\n        fmt.Println(\"Service starting...\")\n        return nil\n    })\n\n    app.Command(\"stop\", \"Stop the service\", func(ctx *orpheus.Context) error {\n        fmt.Println(\"Service stopping...\")\n        return nil\n    })\n\n    // Run the application\n    if err := app.Run(os.Args[1:]); err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\n### Auto-completion\n\nGenerate shell completion scripts for your CLI:\n\n```bash\n# Bash completion (add to ~/.bashrc)\n./myapp completion bash \u003e /etc/bash_completion.d/myapp\n\n# Zsh completion (add to ~/.zshrc)\n./myapp completion zsh \u003e /usr/local/share/zsh/site-functions/_myapp\n\n# Fish completion\n./myapp completion fish \u003e ~/.config/fish/completions/myapp.fish\n```\n\n### Subcommands\n\n```go\n// Create a command with subcommands\nremoteCmd := orpheus.NewCommand(\"remote\", \"Manage remote repositories\")\n\n// Add subcommands using fluent API (v1.0.7+ - now works correctly)\nremoteCmd.Subcommand(\"add\", \"Add a remote\", func(ctx *orpheus.Context) error {\n    name, url := ctx.GetArg(0), ctx.GetArg(1)\n    fmt.Printf(\"Added remote: %s -\u003e %s\\n\", name, url)\n    return nil\n}).AddFlag(\"--force\", \"Force add remote\")\n\nremoteCmd.Subcommand(\"list\", \"List remotes\", func(ctx *orpheus.Context) error {\n    fmt.Println(\"origin\\thttps://github.com/user/repo.git\")\n    return nil\n}).AddFlag(\"--verbose\", \"Show detailed information\")\n\napp.AddCommand(remoteCmd)\n\n// Usage: ./myapp remote add --force origin https://github.com/user/repo.git\n//        ./myapp remote list --verbose\n```\n\n\u003e **Note on subcommands vs positional arguments:** if a parent command accepts\n\u003e both subcommands and free positional arguments (like `git stash [save]` vs\n\u003e `git stash pop`), the first non-flag argument is always matched as a\n\u003e subcommand. Design commands so that subcommand names do not collide with\n\u003e expected positional values. If a command needs both, use explicit subcommands\n\u003e for all variants (e.g., `stash save`, `stash pop`, `stash show`).\n\n## Storage System\n\nOrpheus provides a pluggable storage system that allows CLI applications to persist state using various backends through a unified interface:\n\n```go\nimport \"github.com/agilira/orpheus/pkg/orpheus\"\n\nfunc main() {\n    app := orpheus.New(\"myapp\").\n        SetDescription(\"CLI app with persistent storage\").\n        SetVersion(\"1.0.0\")\n    \n    // Configure storage (supports SQLite, Redis, File, and custom providers)\n    config := \u0026orpheus.StorageConfig{\n        Provider: \"sqlite\",\n        Config: map[string]interface{}{\n            \"path\": \"./myapp.db\",\n        },\n        EnableMetrics: true,\n    }\n    app.ConfigureStorage(config)\n    \n    // Commands can now use persistent storage\n    app.Command(\"set\", \"Store a key-value pair\", setCommand)\n    app.Command(\"get\", \"Retrieve a value\", getCommand)\n    \n    app.Run()\n}\n\nfunc setCommand(ctx *orpheus.Context) error {\n    storage := ctx.Storage()\n    if storage == nil {\n        return orpheus.ErrStorageNotConfigured\n    }\n    \n    key := ctx.GetArg(0)\n    value := ctx.GetArg(1)\n    \n    return storage.Set(ctx, key, []byte(value))\n}\n\nfunc getCommand(ctx *orpheus.Context) error {\n    storage, err := ctx.RequireStorage()\n    if err != nil {\n        return err\n    }\n    \n    key := ctx.GetArg(0)\n    value, err := storage.Get(ctx, key)\n    if err != nil {\n        return err\n    }\n    \n    fmt.Printf(\"Value: %s\\n\", string(value))\n    return nil\n}\n```\n\n**Key Features:**\n- **Plugin Architecture**: Dynamic .so loading for storage providers\n- **Zero Dependencies**: No external storage libraries required  \n- **Security Hardened**: Input validation and plugin security checks\n- **Production Ready**: Metrics, tracing, and audit logging integration\n- **Provider Agnostic**: Unified interface for SQLite, Redis, File, and custom backends\n\n**[Complete Storage Documentation →](./docs/STORAGE.md)**\n\n### Interactive Prompts\n\nOrpheus includes a built-in `Prompter` interface for interactive CLI workflows -- setup wizards, first-run configuration, guided input. Secrets are masked at the terminal level via `golang.org/x/term`.\n\n```go\napp := orpheus.New(\"myapp\").\n    SetDescription(\"Interactive CLI\").\n    SetVersion(\"1.0.0\").\n    SetPrompter(orpheus.NewTerminalPrompter())\n\napp.Command(\"setup\", \"Run first-time setup\", func(ctx *orpheus.Context) error {\n    p, err := ctx.RequirePrompter()\n    if err != nil {\n        return err\n    }\n\n    name, err := p.Ask(\"Your name:\", \"\")\n    if err != nil {\n        return err\n    }\n\n    apiKey, err := p.AskSecret(\"API key:\")\n    if err != nil {\n        return err\n    }\n\n    provider, err := p.Choose(\"LLM provider:\", []string{\"OpenAI\", \"Anthropic\", \"Ollama\"})\n    if err != nil {\n        return err\n    }\n\n    confirm, err := p.Confirm(\"Save configuration?\", true)\n    if err != nil {\n        return err\n    }\n\n    fmt.Printf(\"Name: %s, Provider: %d, Confirmed: %v\\n\", name, provider, confirm)\n    _ = apiKey // use securely\n    return nil\n})\n```\n\n**Prompter methods:**\n\n| Method | Purpose | Return |\n|--------|---------|--------|\n| `Ask(prompt, default)` | Free-text input with optional default | `(string, error)` |\n| `AskSecret(prompt)` | Masked password/key entry | `(string, error)` |\n| `Choose(prompt, options)` | Numbered menu selection | `(int, error)` (0-based) |\n| `Confirm(prompt, defaultYes)` | Yes/no question | `(bool, error)` |\n\nThe `Prompter` interface is testable by design: inject a custom implementation for unit tests without touching a real terminal.\n\n### Observability\n\nZero-overhead observability interfaces for production CLI applications:\n\n```go\nimport \"context\"\n\n// Configure observability (all interfaces are optional)\napp := orpheus.New(\"myapp\").\n    SetLogger(myLogger).           // Structured logging\n    SetAuditLogger(myAuditLogger). // Compliance and security\n    SetTracer(myTracer).           // Distributed tracing\n    SetMetricsCollector(myMetrics) // Performance metrics\n\napp.Command(\"deploy\", \"Deploy application\", func(ctx *orpheus.Context) error {\n    // Structured logging\n    if logger := ctx.Logger(); logger != nil {\n        logger.Info(context.Background(), \"Deployment started\",\n            orpheus.StringField(\"environment\", \"production\"),\n            orpheus.StringField(\"version\", \"v1.2.3\"),\n        )\n    }\n\n    // Audit trail\n    if audit := ctx.AuditLogger(); audit != nil {\n        audit.LogCommand(context.Background(), \"deploy\", ctx.Args(), \"demo-user\")\n        audit.LogAccess(context.Background(), \"production\", \"deploy\", true)\n    }\n\n    // Distributed tracing\n    if tracer := ctx.Tracer(); tracer != nil {\n        spanCtx, span := tracer.StartSpan(context.Background(), \"deploy_operation\")\n        defer span.End()\n        // ... use spanCtx for downstream operations\n    }\n\n    // Performance metrics\n    if metrics := ctx.MetricsCollector(); metrics != nil {\n        counter := metrics.Counter(\"deployments_total\", \"Total deployments\", \"env\")\n        counter.Inc(context.Background(), \"production\")\n    }\n\n    fmt.Println(\"Deployment completed\")\n    return nil\n})\n```\n\n**Performance**: Zero overhead when not configured (0.24 ns/op), minimal overhead when enabled (~24 ns/op)\n\n**[Complete Observability Guide →](./docs/OBSERVABILITY.md)**\n\n**[Complete Examples →](./docs/EXAMPLES.md)**\n\n## The Philosophy Behind Orpheus\n\nOrpheus's lyre was no ordinary instrument. It could make rivers pause mid-flow, convince stones to dance, and move even Hades and Persephone to tears. When the great musician played, the impossible became inevitable—not through force, but through the pure beauty of perfect harmony.\n\nYet Orpheus understood something profound: true power lay not in complexity, but in elegant simplicity. Each note served a purpose, each silence held meaning. His melodies moved the world through perfect clarity of intent, never through force or intricacy.\n\nLike the mythological master whose music could open the gates of Hades itself, Orpheus, transforms the cacophony of human commands into pure, executable harmony, making the complex dance between intention and fulfillment beautifully simple.\n\n### Core Components\n\n- **App**: Main application container with command routing\n- **Command**: Individual command with handler and flags\n- **Context**: Execution context with arguments and flags\n- **Prompter**: Interactive input interface (text, secrets, menus, confirmations)\n- **Errors**: Type-safe error system with exit codes\n- **Completion**: Auto-completion system for multiple shells\n- **Observability**: Optional interfaces for logging, audit trails, tracing, and metrics\n\n## Testing\n\n```bash\n# Run all tests\ngo test ./pkg/orpheus -v\n\n# Run with coverage\ngo test ./pkg/orpheus -v -cover\n```\n\n## Examples\n\n**[Complete Examples →](./docs/EXAMPLES.md)**\n\n**Practical implementations:**\n- **[GitLike Demo](./examples/gitlike/)** - Git-style CLI with subcommands and JSON persistence\n- **[File Manager](./examples/filemanager/)** - Advanced file operations with completion\n- **[Enhanced Errors](./examples/enhanced-errors/)** - Advanced errors handling\n- **[Observability](./examples/observability/)** - Production-ready logging, audit trails, and metrics\n- **[Storage System](./examples/storage/)** - Persistent storage\n- **[Basic Example](./examples/basic/)** - Simple usage patterns and command structures\n\n## API Reference\n\n**[Complete API Reference →](./docs/API.md)**\n\n## License\n\nOrpheus is licensed under the [Mozilla Public License 2.0](./LICENSE.md).\n\n---\n\nOrpheus • an AGILira library\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagilira%2Forpheus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagilira%2Forpheus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagilira%2Forpheus/lists"}