{"id":13509978,"url":"https://github.com/ravern/kubo","last_synced_at":"2025-10-10T15:18:50.609Z","repository":{"id":135443580,"uuid":"134400342","full_name":"ravern/kubo","owner":"ravern","description":"Lightweight command-line framework for Go","archived":false,"fork":false,"pushed_at":"2018-07-30T04:41:30.000Z","size":42,"stargazers_count":96,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-30T15:36:06.657Z","etag":null,"topics":["cli","go","parser"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ravern.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}},"created_at":"2018-05-22T10:40:27.000Z","updated_at":"2025-02-11T21:34:03.000Z","dependencies_parsed_at":"2023-03-27T16:02:00.210Z","dependency_job_id":null,"html_url":"https://github.com/ravern/kubo","commit_stats":null,"previous_names":["ravernkoh/kubo"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ravern/kubo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravern%2Fkubo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravern%2Fkubo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravern%2Fkubo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravern%2Fkubo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ravern","download_url":"https://codeload.github.com/ravern/kubo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravern%2Fkubo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004580,"owners_count":26083735,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["cli","go","parser"],"created_at":"2024-08-01T02:01:19.579Z","updated_at":"2025-10-10T15:18:50.593Z","avatar_url":"https://github.com/ravern.png","language":"Go","funding_links":[],"categories":["Go","cli"],"sub_categories":[],"readme":"# Kubo\n\n[![GoDoc](https://godoc.org/github.com/ravernkoh/kubo?status.svg)](https://godoc.org/github.com/ravernkoh/kubo)\n[![GoReportCard](https://goreportcard.com/badge/ravernkoh/kubo)](https://goreportcard.com/report/ravernkoh/kubo)\n[![TravisCI](https://travis-ci.org/ravernkoh/kubo.svg?branch=master)](https://travis-ci.org/ravernkoh/kubo)\n\nLightweight package to write command line apps in Go.\n\n## Aims\n\nTo be (and remain) as _lightweight_ as possible, while still providing\nsufficient features to build rich command line applications. Also to be easy to\n_understand_ and _use_.\n\n## Installation\n\nUse `vgo get` to download the package.\n\n```bash\n$ vgo get github.com/ravernkoh/kubo\n```\n\n## Usage\n\n### Basic\n\nThe most basic app has just one command, with no arguments and no flags.\n\n```go\napp := kubo.NewApp(\u0026kubo.Command{\n    Name: \"basic\",\n    Description: \"a basic hello world app\",\n    Run: func(ctx *kubo.Context) error {\n        // Prints 'hello, world!'\n        fmt.Fprintln(ctx.Stdout(), \"hello, world!\")\n    },\n})\n```\n\n`Run` then runs the app and returns an error which should be handled (usually\nby simply printing it out).\n\n```go\n// Blocks until the command is completed\nif err := app.Run(); err != nil {\n    fmt.Printf(\"error: %v\\n\", err)\n}\n```\n\nIn this case, the app simply prints `\"hello, world!\"` (more will be explained on\nthe context later).\n\n```bash\n$ basic\nhello, world!\n```\n\n### Commands\n\nThe building block of a command line app is a command. Flags, arguments and child\ncommands can all be defined on a command.\n\n```go\nkubo.Command{\n    Name: \"commands\",\n    Description: \"a random command\",\n    Run: func(ctx *kubo.Context) error {\n        // Prints 'random'\n        fmt.Fprintln(ctx.Stdout(), \"random\")\n    },\n}\n```\n\nThe `Run` function is the function that will be called if the raw arguments are\nsuccessfully parsed by the app. Usually, code will be written in this function.\n\n### Flags\n\nDefining flags on a command is easy.\n\n```go\nkubo.Command{\n    Name: \"flags\",\n    Description: \"a command with flags\",\n    // Defines the flags for this command\n    Flags: []kubo.Flag{\n        {\n            Name: \"one\",\n            Description: \"the first flag\",\n        },\n        {\n            Name: \"two\",\n            Description: \"the second flag\",\n        },\n    },\n}\n```\n\nThe code above defines two flags, called `one` and `two`, which will be available\nfor use with the command.\n\n```bash\n$ flags --one value1 --two value2\n```\n\nFlags can have aliases, which defines alternate names for them.\n\n```go\nkubo.Flag{\n    Name: \"one\",\n    Description: \"the first flag\",\n    Aliases: []string{\"o\"},\n}\n```\n\nFor single letter flags, only a single dash needs to be used.\n\n```bash\n$ flags -o value1 --two value2\n```\n\nFlags also have a field called `Bool`. If this is set to true, then no value\nneeds to be passed to them.\n\n```go\nkubo.Flag{\n    Name: \"two\",\n    Description: \"the second flag\",\n    Bool: true,\n}\n```\n\nThe resulting value would be `\"true\"` if the flag is set and `\"false\"` if the\nflag is not set.\n\n_Note that once `Bool` is set, no value_ should _be passed to the flag, as the\nparser will not try to parse for the flag value._\n\n```bash\n$ flags -o value1 --two\n```\n\n### Arguments\n\nDefining arguments on a command is also easy.\n\n```go\nkubo.Command{\n    Name: \"arguments\",\n    Description: \"a command with arguments\",\n    // Defines the arguments for this command\n    Arguments: []kubo.Argument{\n        {\n            Name: \"one\",\n        },\n        {\n            Name: \"two\",\n        },\n    },\n}\n```\n\nThe code above defines two arguments, `one` and `two`. The order in which you\ndefine the arguments matters. This is because arguments are parsed by their\npositions and not by their names.\n\n```bash\n$ arguments value1 value2\n```\n\nThis will result in `one` having the value `\"value1\"` and `two` having the value\n`\"value2\"`.\n\nArguments can also have a field of `Multiple`, which causes the argument to\ncollect multiple values.\n\n```go\nkubo.Argument{\n    Name: \"two\",\n    Multiple: true,\n}\n```\n\n_Note that only the last argument can have `Multiple` set._\n\n```bash\n$ arguments value1 value2 value3 value4\n```\n\nThis will result in `two` having the value `[\"value2\", \"value3\", \"value4\"]`.\n\n### Contexts\n\nThe context passed in the run function is used to get the arguments and flags\nthat were parsed from the raw arguments.\n\n```go\nkubo.Command{\n    Name: \"contexts\",\n    Description: \"a command with arguments and flags\",\n    Arguments: []kubo.Argument{\n        {Name: \"argument\"},\n    },\n    Flags: []kubo.Flag{\n        {Name: \"flag\"},\n    },\n    Run: func(ctx *kubo.Context) error {\n        // Gets the argument called 'argument'\n        argument, err := ctx.Argument(\"argument\")\n        if err != nil {\n            return err\n        }\n\n        // Gets the flag called 'flag'\n        flag, err := ctx.Flag(\"flag\")\n        if err != nil {\n            return err\n        }\n\n        fmt.Fprintf(ctx.Stdout(), \"argument: %s, flag: %s\\n\", argument, flag)\n    },\n}\n```\n\nThe context also contains the methods for `Stdin` and `Stdout`, which _should_ be\nused to read from and write to the console. They can be configured in the app\nitself (which will pass these values to the context).\n\n```go\n// Default values\napp.Stdin = os.Stdin\napp.Stdout = os.Stdout\n```\n\nWhen getting arguments and flags from the context, sometimes their values need\nto be converted to other types. For that purpose, the `kuboutil` package can be\nused.\n\n```go\n// Gets the argument called 'argument' and converts it to an int\nargument, err := kuboutil.Int(ctx.Argument(\"argument\"))\nif err != nil {\n    return err\n}\n```\n\nThese conversion utilities automatically propogate the error from the `Argument`\nmethod.\n\n### Child commands\n\nCommands can have child commands.\n\n```go\nparent := \u0026kubo.Command{\n    Name: \"parent\",\n}\n\nchild := \u0026kubo.Command{\n    Name: \"child\",\n}\n\n// Makes 'child' a child of the 'parent' command\nparent.Add(child)\n```\n\nThese child commands can be called by passing in their name.\n\n```bash\n$ parent child\n```\n\nChild commands can have flags, arguments, and even child commands of their own!\n\n```go\nparent := \u0026kubo.Command{\n    Name: \"parent\",\n}\n\nchild := \u0026kubo.Command{\n    Name: \"child\",\n}\n\ngrandchild := \u0026kubo.Command{\n    Name: \"grandchild\",\n}\n\n// Makes 'grandchild' a child of the 'child' command\nchild.Add(grandchild)\n\n// Makes 'child' a child of the 'parent' command\nparent.Add(child)\n```\n\nThey can then be called by passing in their names.\n\n```bash\n$ parent child grandchild\n```\n\n### Help command\n\nA help command can be generated for each command.\n\n```go\ncomplex := \u0026kubo.Command{\n    Name: \"complex\",\n    Description: \"some complex command\",\n}\n\n// Makes 'help' a child command of the 'complex' command\ncomplex.Add(complex.Help())\n```\n\nThe help command can be called using `help`.\n\n```bash\n$ complex help\n```\n\n## Examples\n\nMore examples can be found in the `_examples` folder.\n\n## Alternatives\n\nOf course, there are other more notable packages for building command line apps\n(Forgive me if I missed yours out).\n\n- [github.com/spf13/cobra](https://github.com/spf13/cobra)\n- [github.com/urfave/cli](https://github.com/urfave/cli)\n\nKubo was built as some practice for me and also to contribute to open source\nsoftware!\n\n## License\n\nThis project is licensed under the GNU Public License 3.0.\n\n## Author\n\n- Ravern Koh ([ravernkoh@gmail.com](mailto://ravernkoh@gmail.com))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fravern%2Fkubo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fravern%2Fkubo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fravern%2Fkubo/lists"}