{"id":13714377,"url":"https://github.com/mnowotnik/fzshell","last_synced_at":"2026-04-02T14:55:54.144Z","repository":{"id":37857753,"uuid":"253086186","full_name":"mnowotnik/fzshell","owner":"mnowotnik","description":"Fuzzy shell completions you didn't know you needed","archived":false,"fork":false,"pushed_at":"2025-10-19T15:33:08.000Z","size":104,"stargazers_count":78,"open_issues_count":3,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-10-19T23:21:23.242Z","etag":null,"topics":["bash","bash-plugin","cli","fish","fish-shell","fuzzy-matching","go","golang","productivity","shell","terminal","zsh","zsh-plugin"],"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/mnowotnik.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-04-04T19:48:26.000Z","updated_at":"2025-09-06T00:08:10.000Z","dependencies_parsed_at":"2022-08-08T22:01:59.474Z","dependency_job_id":null,"html_url":"https://github.com/mnowotnik/fzshell","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/mnowotnik/fzshell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnowotnik%2Ffzshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnowotnik%2Ffzshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnowotnik%2Ffzshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnowotnik%2Ffzshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mnowotnik","download_url":"https://codeload.github.com/mnowotnik/fzshell/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mnowotnik%2Ffzshell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31308455,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["bash","bash-plugin","cli","fish","fish-shell","fuzzy-matching","go","golang","productivity","shell","terminal","zsh","zsh-plugin"],"created_at":"2024-08-02T23:01:58.314Z","updated_at":"2026-04-02T14:55:54.129Z","avatar_url":"https://github.com/mnowotnik.png","language":"Go","readme":"![fzshell3](https://user-images.githubusercontent.com/8244123/174155451-1d57eb1b-0035-4ef1-83c1-4dd002b048b3.jpg)\n\n[![Test](https://github.com/mnowotnik/fzshell/actions/workflows/test.yml/badge.svg)](https://github.com/mnowotnik/fzshell/actions/workflows/test.yml) [![Join the chat at https://gitter.im/fzshell/community](https://badges.gitter.im/fzshell/community.svg)](https://gitter.im/fzshell/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nfzshell is a fuzzy command line completer that fetches completions from sources\npredefined by a user. What does it mean? It means that now you can create custom completions for anything you want. All fzshell needs is a pattern to match and\ncommand to generate completion list. It can even insert a completion at any point in a line, not just at the end. See for yourself:\n\nhttps://user-images.githubusercontent.com/8244123/173870405-f67abf62-71fc-45e4-8557-4dec77ccd725.mov\n\nThis can be accomplished with a few lines:\n\n```yml\ncompletions:\n  - pattern: \"jq '?(\\\\.[^']*)'? (\\\\w+.json)\"\n    replacement: jq '{{._1}}[{{ .item }}]' {{._2}}\n    cmd: 'jq $1 $2 | jq keys | jq  \". []\"'\n    preview: jq -C '{{._1}}[{{.item}}]'  {{._2}}\n```\n\nIf you find fzshell useful, consider giving it a star. Appreciated!\n\n## Why?\n\nfzshell was born out of my frustration with performing the same manual tasks\nover and over. Like removing obsolete docker containers, deleting kubernetes\npods with kubectl or browsing their logs and even copy pasting ticket id from a\nbranch name to a commit message. \n\nI tried to to solve this problem in the past using only shell scripts and the result was [docker-fzf-completion](https://github.com/mnowotnik/docker-fzf-completion). However, it was not extensible at all and I had to write a lot of unreadable bash scripts to make it work for any extra command. Additionally, it required from a user more keystrokes than one.\n\nEnter fzshell. All of these tasks I mentioned can be automated at least\npartially by fzshell. It divides completions generation into familiar steps,\nnamely: matching, mapping and filtering. A user only has to provide logic for\nthose steps and doesn't have to worry about wiring it all together and edge\ncases.  Check out the\n[gallery of examples](https://github.com/mnowotnik/fzshell/wiki/Examples) to get ideas on how fzshell can help you.\n\n## Want to show your completion definitions 🦚? Need help ❓\n\nVisit [🗨️ Discussions](https://github.com/mnowotnik/fzshell/discussions)!\n\nYou can get your questions (probably) answered in [🙏 Questions \u0026 Answers ](https://github.com/mnowotnik/fzshell/discussions/categories/questions-answers).\n\nShow us your completion definitions in [🦾 Completions Expo](https://github.com/mnowotnik/fzshell/discussions/categories/completions-expo).\n\n## Quickstart\n\n### Installation\n\n#### using git\n\nExecute these lines to install fzshell on your computer.\n\n```bash\ngit clone https://github.com/mnowotnik/fzshell ~/.fzshell\ncd ~/.fzshell/\n./scripts/install.sh\n```\n\nThen follow printed instructions.\n\n#### using plugin manager\n\nIf you use package manager like [zplug](https://github.com/zplug/zplug) you\njust need to add the following line in your `.zshrc`:\n\n```bash\nzplug \"mnowotnik/fzshell\", hook-build:\"./scripts/install.sh --no-instructions\"\n```\n\n[fisher](https://github.com/jorgebucaran/fisher) is also supported. Simply run:\n\n```bash\nfisher install mnowotnik/fzshell\n```\n\n### Basic configuration\n\nfzshell needs a configuration file to load completion definitions.\nBy default, it loads them from: \n\n**~/.config/fzshell/fzshell.yaml**\n\nHowever, this can be changed by the variable `$FZSHELL_CONFIG` that should\npoint to a valid configuration.\n\nBelow, you can see an example configuration file:\n\n```yml\ncompletions:\n  - pattern: \"docker rmi\"\n    cmd: docker images --format '{{.Repository}}:{{.Tag}}\\t{{.ID}}'\n    map: ' {{ .item | splitList \"\\t\" | last }}'\n    preview: docker image inspect {{.item}}\n```\n\nAs you can see the completion definition here has several attributes:\n\n- `pattern`  – regular expression [parsable by Go](https://pkg.go.dev/regexp). It can contain subexpressions (`(xxx)`) and named subexpressions (`(?P\u003cfoo\u003exxx)`)\n- `cmd` – Bash shell expression\n- `map` – Go [template expression](https://pkg.go.dev/text/template) that has access to [sprig](https://masterminds.github.io/sprig/) and subexpression matches:\n  - `.item` – whole line returned by the command in `cmd`\n  - `._1`,`._2`,... – variables that store non-named subexpression matches\n  - `.foo` – named subexpression matches\n- `preview` – Just like `map`, but returns a preview of a matched item\n\nVisit [wiki](https://github.com/mnowotnik/fzshell/wiki/Configuration) for a complete configuration guide.\n\n## Usage\n\nThe hardest part of using fzshell is writing a correct configuration.\nIf that is the case, all you need to do is press `Ctrl-n` when a cursor is just\nafter a matching pattern.\n\nLet's consider the example above. Assume the command line looks like this:\n\n```bash\njq . pets.json▉\n```\n\nYou just need to press `Ctrl-n` to activate fzshell and get a match.\nHowever, if the line deviates from a pattern even a bit nothing will happen.\nNo match for this line:\n\n```bash\njq . pets.json ▉\n```\n\nYou would need to modify the pattern a bit to handle extra spaces at the end:\n\n```yml\npattern: \"jq '?(\\\\.[^']*)'? (\\\\w+.json) *\"\n```\n\nBy default the completion will be inserted at the cursor position, however you\ncan have complete control over the insertion by defining the `replacement` template. It *replaces* the left part of the line buffer (meaning: to the\nleft of the cursor). Check [wiki](https://github.com/mnowotnik/fzshell/wiki/Configuration) for more details.\n\n## Development\n\nDevelopment setup is smooth and easy thanks to Go modules.\n\n- requirement: go version 1.18+\n- command: `go build`\n- manual testing: `source fzshell.bash/fzshell.fish/fzshell.plugin.zsh`\n- automatic tests: `make test`\n- linting: `make lint` (requires `staticcheck`)\n- coverage report: `make cover-report`\n\n## On the way to 1.0.0\n\nfzshell is still in beta, however the specification is unlikely to change, unless\nby popular demand. fzshell will advance to 1.0 after user feedback in the coming weeks.\n\n## Similar tools\n\n### [fzf-tab](https://github.com/Aloxaf/fzf-tab)\n\nDefault zsh completions turned into fuzzy ones thanks to fzf.\n\n### [fig.io](https://fig.io/)\n\nDropdown for different completions computed from context and also framework for additional terminal apps.\nOnly for MacOS.\n\n## Acknowledgments\n\nThis tool is possible thanks to open source fuzzy finders. First fuzzy finder used was [go-fuzzyfinder](https://github.com/ktr0731/go-fuzzyfinder).\nAfter that fzshell embedded a more feature complete finder, the excellent [fzf](https://github.com/junegunn/fzf). \n\n## Disclaimer\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","funding_links":[],"categories":["Completions","Repositories"],"sub_categories":["ZSH on Windows"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmnowotnik%2Ffzshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmnowotnik%2Ffzshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmnowotnik%2Ffzshell/lists"}