{"id":16193633,"url":"https://github.com/domblack/bubble-shell","last_synced_at":"2025-04-02T06:31:51.256Z","repository":{"id":181279023,"uuid":"666398954","full_name":"DomBlack/bubble-shell","owner":"DomBlack","description":"A Bubble Tea library for creating an interactive shell using Cobra commands","archived":false,"fork":false,"pushed_at":"2023-11-06T09:51:41.000Z","size":91,"stargazers_count":6,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-16T14:51:41.145Z","etag":null,"topics":["bubbletea","cli","cli-tool","cobra-cli","golang","interactive-shell","shell"],"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/DomBlack.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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}},"created_at":"2023-07-14T12:19:16.000Z","updated_at":"2024-12-02T03:31:58.000Z","dependencies_parsed_at":"2024-11-03T05:02:52.357Z","dependency_job_id":"e3abb6c8-ee49-4770-841d-dfb0eb6a8753","html_url":"https://github.com/DomBlack/bubble-shell","commit_stats":null,"previous_names":["domblack/bubble-shell"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DomBlack%2Fbubble-shell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DomBlack%2Fbubble-shell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DomBlack%2Fbubble-shell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DomBlack%2Fbubble-shell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DomBlack","download_url":"https://codeload.github.com/DomBlack/bubble-shell/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246768263,"owners_count":20830634,"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":["bubbletea","cli","cli-tool","cobra-cli","golang","interactive-shell","shell"],"created_at":"2024-10-10T08:15:52.955Z","updated_at":"2025-04-02T06:31:47.839Z","avatar_url":"https://github.com/DomBlack.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bubble Shell\n\nThis library provides you with a interactive shell powered by [bubbletea](https://github.com/charmbracelet/bubbletea) \nby executing [cobra](https://github.com/spf13/cobra), allowing you to build powerful interactive terminal based shell\napplications.\n\n## Usage\n\nCreate a root command as you would normally with cobra, attaching your various commands to it.\nThen pass it to the `shell.New` function to create a new shell.\n\n```go\npackage main\n\nimport (\n\ttea \"github.com/charmbracelet/bubbletea\"\n    \"github.com/DomBlack/bubble-shell\"\n    \"github.com/spf13/cobra\"\n)\n\nfunc main() {\n\t// Create the root command which we can attach everything to\n    rootCmd := \u0026cobra.Command{}\n\t\n\t// Create a command to add to the root command\n\tmyCmd := \u0026cobra.Command{\n\t\tUse: \"hi\",\n        RunE: func(cmd *cobra.Command, args []string) error {\n\t\t\tcmd.OutOrStdout().Write([]byte(\"Hello World\\n\"))\n\t\t\treturn nil\n        },\n\t}\n\trootCmd.AddCommand(myCmd)\n    \n\t// Create the shell\n\tshell := shell.New(rootCmd)\n\t\n\t// Run the shell\n\tp := tea.NewProgram(shell)\n\tif _, err := p.Run(); err != nil {\n\t\tpanic(err)\n\t}\n}\n```\n                                               \nIn this example, a user will be given an interactive shell with a single command `hi` which will print `Hello World` when\nrun.\n\n### Options\n\nThe `shell.New` function takes a number of options to configure the shell, which are detailed below. Full documentaton\nfor them can be seen in [options.go](./options.go).\n\n#### `shell.WithHistoryFile` / `shell.WithNoHistory`\n\nBy default the shell will save the history of commands to `.bubble-shell-history` in the user's home directory, however\nusing these two options you can change this behaviour, either providing your own filename or disabling history entirely.\n\n#### `shell.WithKeyMap`\n\nYou can use this option to customise the key bindings used by the shell. The default key bindings are located in\n[the keymap package](./pkg/config/keymap/keymap.go).\n\n#### `shell.WithStyles`\n\nYou can use this option to customise the styles used by the shell. The default styles are located in\n[the styles package](./pkg/config/styles/styles.go).\n\n#### `shell.WithStackTraceFilters` / `shell.WithAdditionalStackTraceFilters`\n\nBy default the shell will filter out stack traces from the `github.com/DomBlack/bubble-shell` package and other related\npackages when rendering the stack traces of errors to the user. You can use these options to customise this behaviour,\neither by providing your own list of packages to filter out, or by adding to the default list.\n\n### Guidelines for building commands\n\n1. The shell supports autocompletion of commands and arguments, so ideally implement a `ValidArgsFunction` function or\n    `ValidArgs` property on your command.\n2. If you implement your commands using `RunE` rather than `Run` you can then return an error to bubble-shell which will\n    be displayed to the user. If the error carries a stack trace, it will be displayed to the user. (I recommend using\n    [cockroachdb/errors](https://github.com/cockroachdb/errors) to create errors with stack traces by default).\n3. If you need a context use `cmd.Context()` rather than creating your own. This is because the shell will cancel the\n    context when the user presses `Ctrl+C`.\n4. If you want to display a message to the user, use `cmd.OutOrStdout()` rather than `fmt.Println(\"Hello World\")`.  While\n    both will be captured and returned to the user, the former will be streamed to the user as it is written, while the\n    `os.Stdout` and `os.Stderr` streams are buffered and only displayed when the command completes.\n\n\n## Example Apps\n\n- [Example which shows the active keybindings](./examples/with-help/main.go)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdomblack%2Fbubble-shell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdomblack%2Fbubble-shell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdomblack%2Fbubble-shell/lists"}