{"id":16830871,"url":"https://github.com/jpillora/opts","last_synced_at":"2025-04-04T17:09:50.455Z","repository":{"id":30420806,"uuid":"33973719","full_name":"jpillora/opts","owner":"jpillora","description":"A Go (golang) package for building frictionless command-line interfaces","archived":false,"fork":false,"pushed_at":"2023-07-25T18:49:35.000Z","size":238,"stargazers_count":164,"open_issues_count":11,"forks_count":18,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-06T13:04:15.535Z","etag":null,"topics":["cli","command-line","go","golang"],"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/jpillora.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":"2015-04-15T04:47:39.000Z","updated_at":"2025-02-27T18:08:12.000Z","dependencies_parsed_at":"2024-06-18T13:37:46.783Z","dependency_job_id":"23a306d2-28bb-4f62-aa8f-eb4b20e030b9","html_url":"https://github.com/jpillora/opts","commit_stats":null,"previous_names":["jpillora/flag"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpillora%2Fopts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpillora%2Fopts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpillora%2Fopts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpillora%2Fopts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jpillora","download_url":"https://codeload.github.com/jpillora/opts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217222,"owners_count":20903009,"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","command-line","go","golang"],"created_at":"2024-10-13T11:41:23.980Z","updated_at":"2025-04-04T17:09:50.439Z","avatar_url":"https://github.com/jpillora.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg width=\"443\" alt=\"logo\" src=\"https://user-images.githubusercontent.com/633843/57529538-84a22780-7378-11e9-9235-312633dc125e.png\"\u003e\u003cbr\u003e\n\u003cb\u003eA Go (golang) package for building frictionless command-line interfaces\u003c/b\u003e\u003cbr\u003e\u003cbr\u003e\n\u003ca href=\"https://godoc.org/github.com/jpillora/opts#Opts\" rel=\"nofollow\"\u003e\n\t\u003cimg src=\"https://camo.githubusercontent.com/42566bdba17f1a0c86c1a1de859d6ab70bde1457/68747470733a2f2f676f646f632e6f72672f6769746875622e636f6d2f6a70696c6c6f72612f6f7074733f7374617475732e737667\" alt=\"GoDoc\" data-canonical-src=\"https://godoc.org/github.com/jpillora/opts?status.svg\" style=\"max-width:100%;\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/jpillora/opts/actions?workflow=CI\" rel=\"nofollow\"\u003e\n\t\u003cimg src=\"https://github.com/jpillora/opts/workflows/CI/badge.svg\" alt=\"CI\" data-canonical-src=\"https://github.com/jpillora/media-sort/workflows/CI/badge.svg\" style=\"max-width:100%;\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nCreating command-line interfaces should be simple:\n\n```go\npackage main\n\nimport (\n\t\"log\"\n\n\t\"github.com/jpillora/opts\"\n)\n\nfunc main() {\n\ttype config struct {\n\t\tFile  string `opts:\"help=file to load\"`\n\t\tLines int    `opts:\"help=number of lines to show\"`\n\t}\n\tc := config{}\n\topts.Parse(\u0026c)\n\tlog.Printf(\"%+v\", c)\n}\n```\n\n```sh\n$ go build -o my-prog\n$ ./my-prog --help\n\n  Usage: my-prog [options]\n\n  Options:\n  --file, -f   file to load\n  --lines, -l  number of lines to show\n  --help, -h   display help\n\n```\n\n```sh\n$ ./my-prog -f foo.txt -l 42\n{File:foo.txt Lines:42}\n```\n\n*Try it out https://play.golang.org/p/D0jWFwmxRgt*\n\n### Features (with examples)\n\n- Easy to use ([eg-helloworld](https://github.com/jpillora/opts-examples/tree/master/eg-helloworld/))\n- Promotes separation of CLI code and library code ([eg-app](https://github.com/jpillora/opts-examples/tree/master/eg-app/))\n- Automatically generated `--help` text via struct tags ([eg-help](https://github.com/jpillora/opts-examples/tree/master/eg-help/))\n- Default values by modifying the struct prior to `Parse()` ([eg-defaults](https://github.com/jpillora/opts-examples/tree/master/eg-defaults/))\n- Default values from a JSON config file, unmarshalled via your config struct ([eg-config](https://github.com/jpillora/opts-examples/tree/master/eg-config/))\n- Default values from environment, defined by your field names ([eg-env](https://github.com/jpillora/opts-examples/tree/master/eg-env/))\n- Repeated flags using slices ([eg-repeated-flag](https://github.com/jpillora/opts-examples/tree/master/eg-repeated-flag/))\n- Group your flags in the help output ([eg-groups](https://github.com/jpillora/opts-examples/tree/master/eg-groups/))\n- Sub-commands by nesting structs ([eg-commands-inline](https://github.com/jpillora/opts-examples/tree/master/eg-commands-inline/))\n- Sub-commands by providing child `Opts` ([eg-commands-main](https://github.com/jpillora/opts-examples/tree/master/eg-commands-main/))\n- Infers program name from executable name\n- Infers command names from struct or package name\n- Define custom flags types via `opts.Setter` or `flag.Value` ([eg-custom-flag](https://github.com/jpillora/opts-examples/tree/master/eg-custom-flag/))\n- Customizable help text by modifying the default templates ([eg-help](https://github.com/jpillora/opts-examples/tree/master/eg-help/))\n- Built-in shell auto-completion ([eg-complete](https://github.com/jpillora/opts-examples/tree/master/eg-complete))\n\nFind these examples and more in the [`opts-examples`](https://github.com/jpillora/opts-examples) repository.\n\n### Package API\n\nSee https://godoc.org/github.com/jpillora/opts#Opts\n\n[![GoDoc](https://godoc.org/github.com/jpillora/opts?status.svg)](https://godoc.org/github.com/jpillora/opts)\n\n### Struct Tag API\n\n**opts** tries to set sane defaults so, for the most part, you'll get the desired behaviour by simply providing a configuration struct.\n\nHowever, you can customise this behaviour by providing the `opts` struct\ntag with a series of settings in the form of **`key=value`**:\n\n```\n`opts:\"key=value,key=value,...\"`\n```\n\nWhere **`key`** must be one of:\n\n- `-` (dash) - Like `json:\"-\"`, the dash character will cause opts to ignore the struct field. Unexported fields are always ignored.\n\n- `name` - Name is used to display the field in the help text. By default, the flag name is infered by converting the struct field name to lowercase and adding dashes between words.\n\n- `help` - The help text used to summaryribe the field. It will be displayed next to the flag name in the help output.\n\n\t*Note:* `help` can also be set as a stand-alone struct tag (i.e. `help:\"my text goes here\"`). You must use the stand-alone tag if you wish to use a comma `,` in your help string.\n\n- `mode` - The **opts** mode assigned to the field. All fields will be given a `mode`. Where the `mode` **`value`** must be one of:\n\n\t* `flag` - The field will be treated as a flag: an optional, named, configurable field. Set using `./program --\u003cflag-name\u003e \u003cflag-value\u003e`. The struct field must be a [*flag-value*](#flag-values) type. `flag` is the default `mode` for any [*flag-value*](#flag-values).\n\n\t* `arg` - The field will be treated as an argument: a required, positional, unamed, configurable field. Set using `./program \u003cargument-value\u003e`. The struct field must be a [*flag-value*](#flag-values) type.\n\n\t* `embedded` - A special mode which causes the fields of struct to be used in the current struct. Useful if you want to split your command-line options across multiple files (default for `struct` fields). The struct field must be a `struct`. `embedded` is the default `mode` for a `struct`. *Tip* You can play group all fields together placing an `group` tag on the struct field.\n\n\t* `cmd` - A inline command, shorthand for `.AddCommmand(opts.New(\u0026field))`, which also implies the struct field must be a `struct`.\n\n\t* `cmdname` - A special mode which will assume the name of the selected command. The struct field must be a `string`.\n\n- `short` - One letter to be used a flag's \"short\" name. By default, the first letter of `name` will be used. It will remain unset if there is a duplicate short name or if `opts:\"short=-\"`. Only valid when `mode` is `flag`.\n\n- `group` - The name of the flag group to store the field. Defining this field will create a new group of flags in the help text (will appear as \"`\u003cgroup\u003e` options\"). The default flag group is the empty string (which will appear as \"Options\"). Only valid when `mode` is `flag` or `embedded`.\n\n- `env` - An environent variable to use as the field's **default** value. It can always be overridden by providing the appropriate flag. Only valid when `mode` is `flag`.\n\n\tFor example, `opts:\"env=FOO\"`. It can also be infered using the field name with simply `opts:\"env\"`. You can enable inference on all flags with the `opts.Opts` method `UseEnv()`.\n\n- `min` `max` - A minimum or maximum length of a slice. Only valid when `mode` is `arg`, *and* the struct field is a slice.\n\n#### flag-values:\n\nIn general an opts _flag-value_ type aims to be any type that can be get and set using a `string`. Currently, **opts** supports the following types:\n\n- `string`\n- `bool`\n- `int`, `int8`, `int16`, `int32`, `int64`\n- `uint`, `uint8`, `uint16`, `uint32`, `uint64`\n- `float32`, `float64`\n- [`opts.Setter`](https://godoc.org/github.com/jpillora/opts#Setter)\n\t- *The interface `func Set(string) error`*\n- [`flag.Value`](https://golang.org/pkg/flag/#Value)\n\t- *Is an `opts.Setter`*\n- `time.Duration`\n- `encoding.TextUnmarshaler`\n\t- *Includes `time.Time` and `net.IP`*\n- `encoding.BinaryUnmarshaler`\n\t- *Includes `url.URL`*\n\nIn addition, `flag`s and `arg`s can also be a slice of any _flag-value_ type. Slices allow multiple flags/args. For example, a struct field flag `Foo []int` could be set with `--foo 1 --foo 2`, and would result in `[]int{1,2}`.\n\n### Help text\n\nBy default, **opts** attempts to output well-formatted help text when the user provides the `--help` (`-h`) flag. The [examples](https://github.com/jpillora/opts-examples) repositories shows various combinations of this default help text, resulting from using various features above.\n\nModifications be made by customising the underlying [Go templates](https://golang.org/pkg/text/template/) found here [DefaultTemplates](https://godoc.org/github.com/jpillora/opts#pkg-variables).\n\n### Talk\n\nI gave a talk on **opts** at the Go Meetup Sydney (golang-syd) on the 23rd of May, 2019. You can find the slides here https://github.com/jpillora/opts-talk.\n\n### Other projects\n\nOther related projects which infer flags from struct tags but aren't as feature-complete:\n\n- https://github.com/alexflint/go-arg\n- https://github.com/jessevdk/go-flags\n\n#### MIT License\n\nCopyright © 2019 \u0026lt;dev@jpillora.com\u0026gt;\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n'Software'), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpillora%2Fopts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjpillora%2Fopts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpillora%2Fopts/lists"}