{"id":20979024,"url":"https://github.com/1pkg/gofire","last_synced_at":"2025-05-14T14:32:57.829Z","repository":{"id":144325967,"uuid":"410954647","full_name":"1pkg/gofire","owner":"1pkg","description":"Gofire 🔥 Command Line Interface Generator tool for Go","archived":false,"fork":false,"pushed_at":"2021-10-25T18:10:23.000Z","size":1222,"stargazers_count":111,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-02T19:41:28.718Z","etag":null,"topics":["cli","code-generation","go","golnag","tui"],"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/1pkg.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}},"created_at":"2021-09-27T16:09:51.000Z","updated_at":"2024-12-20T17:04:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"e42c7559-c642-4fab-acb8-e1c9856e0c4c","html_url":"https://github.com/1pkg/gofire","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1pkg%2Fgofire","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1pkg%2Fgofire/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1pkg%2Fgofire/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1pkg%2Fgofire/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/1pkg","download_url":"https://codeload.github.com/1pkg/gofire/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254160648,"owners_count":22024574,"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":["cli","code-generation","go","golnag","tui"],"created_at":"2024-11-19T05:10:34.436Z","updated_at":"2025-05-14T14:32:57.822Z","avatar_url":"https://github.com/1pkg.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/1pkg/gofire/master/gopher.png?cache=0\" alt=\"gofire\"/\u003e\n\u003c/p\u003e\n\n# Gofire 🔥: Command Line Interface Generator tool for Go\n\n[![lint](https://github.com/1pkg/gofire/workflows/lint/badge.svg)](https://github.com/1pkg/gofire/actions?query=workflow%3Alint+branch%3Amaster+)\n[![build](https://github.com/1pkg/gofire/workflows/build/badge.svg)](https://github.com/1pkg/gofire/actions?query=workflow%3Abuild+branch%3Amaster+)\n[![test](https://github.com/1pkg/gofire/workflows/test/badge.svg)](https://github.com/1pkg/gofire/actions?query=workflow%3Atest+branch%3Amaster+)\n[![report](https://goreportcard.com/badge/github.com/1pkg/gofire?cache=0)](https://goreportcard.com/report/github.com/1pkg/gofire)\n[![version](https://img.shields.io/github/go-mod/go-version/1pkg/gofire?cache=0)](https://github.com/1pkg/gofire/blob/master/go.mod)\n[![license](https://img.shields.io/github/license/1pkg/gofire?cache=0)](LICENSE)\n\n## Introduction\n\nGofire is the tool for Go that automatically generates a command line interface (CLI) for your functions and does all required plumbing in between, inspired by [python-fire](https://github.com/google/python-fire).\n\n## Features\n\n- Gofire uses code generation to generate simple and predictable CLI tailored to your code. It takes care about all required plumbing around parameters parsing, types casting, setting the entrypoint, documentation, etc.\n- Gofire provides multiple CLI backends with different capabilities and features, including: [flag](https://pkg.go.dev/flag), [cobra](https://github.com/spf13/cobra), [bubbletea](https://github.com/charmbracelet/bubbletea), [and more](#drivers-and-backends).\n- Gofire is opinionated about the defaults and always tries to provide simple and safe CLI. Yet, if needed, it supports optional go structs tag literals to flexibly configure CLI parameters [see more](#flags-groups-and-tags).\n\n## Requirements Installation and Usage\n\nGofire uses go1.17, but it's most likely gonna work with other versions too. Note that Gofire is heavily relying on [ast](https://golang.org/pkg/go/ast/) packages, and the package might be slightly different among major go releases.\n\nTo install Gofire generator CLI tool, use:\n\n```bash\ngo install github.com/1pkg/gofire/cmd/gofire@latest\n```\n\nTo call Gofire generator CLI tool help, use:\n\n```bash\ngofire --help\nGofire 🔥 is command line interface generator tool.\nThe first required argument dir represents directory path of source package.\nThe second required argument fun represents source function name.\nOptional flag driver represents driver backend name, one of [gofire, flag, pflag, cobra, bubbletea], flag by default.\nOptional flag pckg represents source package name, useful if package name and directory is different, last element of dir by default.\nGofire --driver=\"\" --pckg=\"\" arg0 arg1 [--help]\nfunc Gofire(ctx context.Context, driver, pckg *string, dir, fun string), --driver string (default \"\") --pckg string (default \"\") arg 0 string arg 1 string\nhelp requested\n```\n\nTo run Gofire generator CLI tool with `pflag` driver on function `Gofire` in package `main` in path `cmd/gofire`, use:\n\n```bash\ngofire --driver=pflag --pckg=main cmd/gofire Gofire\ncmd/gofire/pflag.gen.go successfully generated\n```\n\nNote that Gofire can be easily integrated into the build process on permanent basis by adding the comment to your Go code base and using `go generate` command.\n\n```go\n//go:generate gofire --driver=$DRIVER --pckg=$PACKAGE $DIRECTORY $FUNCTION\n```\n\nFor more details refer to [generating code in Go](https://go.dev/blog/generate).\n\n## Parsing and Generation Convention\n\nCurrently Gofire works only with standalone top level functions. Where the name of the function conveniently represents the CLI command name and parametrs of the function represent CLI flags and positional arguments. Gofire parser generally supports all built-in Go types for the functions parameters including strings, slices and maps. However different driver backends may not support all parsed types for the code generation, to find what is supported by what driver backend refer to [drivers and backends](#drivers-and-backends). Note also that some built-in Go types including channels and interfaces don't have an obvious CLI parameters mapping and currently are not supported by Gofire. Type aliases currently are not supported by Gofire as well.\n\nGofire uses next convention while parsing a function and genereting a bridge to CLI:\n\n- function name become command name.\n- function definition become a part of command documentation.\n- function doc string become a part of command documentation.\n- function non pointer parametrs become required command positional arguments.\n- function pointer parametrs become optional command auto flags with default empty values.\n- function ellipsis parametr `...` is a special case that become ellipsis positional argument.\n- function placeholder parametrs `_` is a special case that become filled with empty value internally.\n- entrypoint for main is generated only if source function is located in `main` package.\n- entrypoint for command is always generated as exported function in case you need to use it outside.\n\nAs an concise example the definition below is converted to:\n\n```go\n//                          optional float64 cli flag 'c'\n//                                          │ default 0.0\n//                                          │\n//                                          │\n//                                          │\n//            2 required int positional argu│ents\n//                              │           │\n//                              │           │\n//                              │           │optional []float64 cli flag 'in'\n//         command name         │           │          │  default []float64{}\n//               │              │           │          │\n//               │              │           │          │\n//               │              │           │          │\n//               │              │           │          │\nfunc addThenMultiplyAndGuess(a, b int, c *float64, in *[]float64, _ string) bool {\n  sum := float64(a + b)\n  guess := sum * (*c)\n  for _, f := range *in {\n    if guess == f {\n      fmt.Println(\"inside\")\n      return true\n    }\n  }\n  fmt.Println(\"outside\")\n  return false\n}\n```\n\n```bash\n# help\ngofire --driver=pflag --pckg=main . addThenMultiplyAndGuess\naddThenMultiplyAndGuess --c=0.000000 --in=[]float64{} arg0 arg1 [--help -h]\nfunc addThenMultiplyAndGuess(a, b int, c *float64, in *[]float64) bool, --c float64 (default 0.000000) --in []float64 (default []float64{}) arg 0 int arg 1 int\npflag: help requested\nexit status 2\n# exec\ngo run ./... 10 1 --c=2.0 --in=10.0\noutside\ngo run ./... 10 1 --c=2.0 --in=10.0 --in=22.0\ninside\n```\n\n## Flags Groups and Tags\n\nGofire provides a way to bypass some rules defined in [parsing and generation convention](#parsing-and-generation-convention). Mainly grouping; adding defaults, short names, docs to CLI flags; and marking them as deprecated or hidden. This can be achieved by using a struct type as a function parameter together with special structure tag literals which acts as a flags group.\n\nGofire uses next schema for tag literals `gofire:\"short=name,default=value,deprecated,hidden\"`. Where `short` represents optional flag short name, `default` represents optional flag default value accordingly the type, `deprecated` represents optional flag deprecation status, `hidden` represents optional flag hidden status. Note that the structure has to be defined in the same package with the source function and that type aliases currently are not supported by Gofire.\n\nAs an concise example the definition below is converted to:\n\n```go\npackage main\n\nimport \"fmt\"\n\ntype person struct {\n\tfullName string `gofire:\"short=n\"`\n\t// bornY is deprecated use bornYear isntead.\n\tbornY    int `gofire:\"deprecated\"`\n\tbornYear int\n\t// please use full occupation.\n\toccupation string `gofire:\"default='professional wrestler'\"`\n}\n\n// wasBorn answers the question if person was born in the provided year and prints the person.\nfunc wasBorn(p person, bornY *int) {\n\tif p.bornYear \u003c= *bornY {\n\t\tfmt.Println(\"yes\")\n\t} else {\n\t\tfmt.Println(\"no\")\n\t}\n\tfmt.Println(p)\n}\n```\n\n```bash\n# help\ngo run ./... --help\nwasBorn: wasBorn answers the question if person was born in the provided year and prints the person.\n\nUsage:\n  wasBorn --bornY=0 --p.bornY=0 --p.bornYear=0 --p.fullName=\"\" -n=\"\" --p.occupation=\"professional wrestler\"\n\nFlags:\n      --bornY int\n  -h, --help                  help for wasBorn\n      --p.bornYear int\n  -n, --p.fullName string\n      --p.occupation string   please use full occupation. (default \"professional wrestler\")\n# exec\ngo run ./... -n=\"the Rock\" --p.bornYear=1972 --bornY=1975\nyes\n{the Rock 0 1972 professional wrestler}\n```\n\nYou can specify default values for comlex data types using simplified Go syntax for slice and map literals e.g. `{1,2,3}`; `{10:aaa, 20:bbb}`; `{'foo bar':{1:test, 2:'not test'}}`. Currently, there are few known minor limitations in complex value parsing in Gofire [see more](parsers/doc.go).\n\n## Drivers and Backends\n\n#### Flag Backend\n\nFlag Backend is used as the backend by default in Gofire. This backend strives for simplicity and doesn't support any complex types. It also doesn't support short flag names and flags deprecation and hidding. However it still supports flags default values and ellipsis positional argument. Flag Backend is based on https://pkg.go.dev/flag package.\n\n#### PFlag Backend\n\nPFlag Backend is similar to Flag Backend, but it also adds extra support for slice type flags and fully supports Gofire tag literals including grouping, short flag names and flags deprecation and hidding. PFlag Backend is based on https://github.com/spf13/pflag package.\n\n#### Cobra Backend\n\nCobra Backend mirrors PFlag Backend support for data types and tag literals. Cobra Backend is based on https://github.com/spf13/cobra package.\n\n#### RefType Backend\n\nRefType Backend aims to support complex nested data types including slice and maps for both flags and positional arguments. It doesn't support any tag literals features other then default values. Note that ellipsis parameters are not supported as they generally makes no sense for this driver. Also note that it uses github.com/mitchellh/mapstructure and reflection underneath. This driver expects all CLI values be prodived in their raw form not preprocessed by a shell, meaning you should always escape comlex data types values with `\"` when using this driver e.g. `--stringMapOfIntSlices=\"{first:{1,2,3}, second:{0}, third:{3,2,1}}\"`.\n\n#### Bubbletea Backend\n\nBubbletea Backend generates a simple interactive TUI bridge. This backend only supports positional arguments and naturally doesn't support any flags groups tag literals or ellipsis parameters. Bubbletea Backend is based on https://github.com/charmbracelet/bubbletea.\n\n## Licence\n\nGofire is licensed under the MIT License.  \nSee [LICENSE](LICENSE) for the full license text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1pkg%2Fgofire","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F1pkg%2Fgofire","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1pkg%2Fgofire/lists"}