{"id":13606917,"url":"https://github.com/fishi0x01/vsh","last_synced_at":"2025-04-05T14:10:03.489Z","repository":{"id":37426114,"uuid":"205700555","full_name":"fishi0x01/vsh","owner":"fishi0x01","description":"vsh - HashiCorp Vault interactive shell and cli tool","archived":false,"fork":false,"pushed_at":"2024-05-12T08:17:43.000Z","size":20765,"stargazers_count":287,"open_issues_count":15,"forks_count":11,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-29T13:09:23.285Z","etag":null,"topics":["cli","repl","shell","vault","vault-client"],"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/fishi0x01.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}},"created_at":"2019-09-01T16:06:41.000Z","updated_at":"2025-01-29T16:57:24.000Z","dependencies_parsed_at":"2023-12-19T15:16:27.242Z","dependency_job_id":"ae9f043d-0b4b-4bbf-9f32-2bbf30d4fc6a","html_url":"https://github.com/fishi0x01/vsh","commit_stats":{"total_commits":65,"total_committers":7,"mean_commits":9.285714285714286,"dds":0.2615384615384615,"last_synced_commit":"5ea17160bce5492b9255109f7d84b2a2b7d6e9eb"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fishi0x01%2Fvsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fishi0x01%2Fvsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fishi0x01%2Fvsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fishi0x01%2Fvsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fishi0x01","download_url":"https://codeload.github.com/fishi0x01/vsh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247345856,"owners_count":20924102,"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","repl","shell","vault","vault-client"],"created_at":"2024-08-01T19:01:13.770Z","updated_at":"2025-04-05T14:10:03.450Z","avatar_url":"https://github.com/fishi0x01.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# vsh\n\n[![Latest release](https://img.shields.io/github/release/fishi0x01/vsh.svg)](https://github.com/fishi0x01/vsh/releases/latest)\n![CI](https://github.com/fishi0x01/vsh/workflows/CI/badge.svg)\n[![Go Report Card](https://goreportcard.com/badge/github.com/fishi0x01/vsh)](https://goreportcard.com/report/github.com/fishi0x01/vsh)\n[![Code Climate](https://codeclimate.com/github/fishi0x01/vsh/badges/gpa.svg)](https://codeclimate.com/github/fishi0x01/vsh)\n\n![vsh usage](https://user-images.githubusercontent.com/10799507/66355982-9872a980-e969-11e9-8ca4-6a2ff215f835.gif)\n\n`vsh` is an interactive [HashiCorp Vault](https://www.vaultproject.io/) shell and cli tool. It comes with multiple common operations and treats paths like directories and files.\nCore features are:\n\n- recursive operations on paths for many operations, e.g., `cp`, `rm`, `mv`\n- search with `grep` (substring or regular-expression)\n- substitute patterns in keys and/or values (substring or regular-expression) with `replace`\n- transparency towards differences between KV1 and KV2, i.e., you can freely move/copy secrets between both\n- non-interactive mode for automation (`vsh -c \"\u003ccmd\u003e\"`)\n- merging keys with different strategies through `append`\n\n## Installation\n\n### Homebrew\n\n```sh\nbrew install vsh\n```\n\n### Nix\n\n```sh\nnix-env -i vsh\n```\n\n### Static binaries for Linux / MacOS\n\nDownload latest static binaries from [release page](https://github.com/fishi0x01/vsh/releases).\n\n## Supported commands\n\n- [add](doc/commands/add.md) adds a single key and value to a path\n- [append](doc/commands/append.md) merges secrets with different strategies (allows recursive operation on paths)\n- [cat](doc/commands/cat.md) shows the key/value pairs of a path\n- [cd](doc/commands/cd.md) allows interactive navigation through the paths\n- [cp](doc/commands/cp.md) copies secrets from one location to another (allows recursive operation on paths)\n- [grep](doc/commands/grep.md) searches for substrings or regular expressions (allows recursive operation on paths)\n- [ls](doc/commands/ls.md) shows the subpaths of a given path\n- [mv](doc/commands/mv.md) moves secrets from one location to another (allows recursive operation on paths)\n- [replace](doc/commands/replace.md) substrings or regular expressions (allows recursive operation on paths)\n- [rm](doc/commands/rm.md) removes secret(s) (allows recursive operation on paths)\n\n## Setting the vault token\n\nIn order to get a valid token, `vsh` uses vault's TokenHelper mechanism.\nThat means `vsh` supports setting vault tokens via `~/.vault-token`, `VAULT_TOKEN` and external [token-helper](https://www.vaultproject.io/docs/commands/token-helper).\n\n## TLS\n\nAdd tls certificate for server by setting `VAULT_CACERT` environment variable to the `pem` certificate path.\n\n## Token permission requirements\n\n`vsh` requires `List` permission on the operated paths.\nThis is necessary to determine if a path points to a node or leaf in the path tree.\nFurther, it is needed to gather auto-completion data.\n\nCommands which alter the data like `cp` or `mv`, additionally require `Read` and `Write` permissions on the operated paths.\n\nIn order to reliably discover all available backends, ideally the vault token used by `vsh` has `List` permission on `sys/mount`. However, this is not a hard requirement.\nIf the token doesn't have `List` permission on `sys/mount`, then `vsh` does not know the available backends beforehand.\nThat means initially there won't be path auto-completion on the top (backend) level.\nRegardless, `vsh` will try with best-effort strategy to reliably determine the kv version of every entered path.\n\n## Interactive mode\n\n```\nexport VAULT_ADDR=http://localhost:8080\nexport VAULT_TOKEN=root\nexport VAULT_PATH=secret/  # VAULT_PATH is optional\n./vsh\nhttp://localhost:8080 /secret/\u003e\n```\n\n**Note:** the given token is used for auto-completion, i.e., `List()` queries are done with that token, even if you do not `rm` or `mv` anything.\n`vsh` caches `List()` results to reduce the amount of queries. However, after execution of each command the cache is cleared\nin order to do accurate tab-completion.\nIf your token has a limited number of uses, then consider using the non-interactive mode or toggle auto-completion off, to avoid `List()` queries.\n\n### Toggle auto-completion\n\nTo reduce the number of queries against vault, you can disable path auto-completion in 2 ways:\n\n1. Disable at start time:\n\n```\n./vsh --disable-auto-completion\n```\n\n2. Toggle inside interactive mode:\n\n```\n./vsh\nhttp://localhost:8080 /secret/\u003e toggle-auto-completion\nUse path auto-completion: false\nhttp://localhost:8080 /secret/\u003e toggle-auto-completion\nUse path auto-completion: true\n```\n\n## Non-interactive mode\n\n```\nexport VAULT_ADDR=\u003caddr\u003e\nexport VAULT_TOKEN=\u003ctoken\u003e\n./vsh -c \"rm secret/dir/to/remove/\"\n```\n\n## Some words about the quality\n\nWorking on vault secrets can be critical, making quality and correct behavior a first class citizen for `vsh`.\nThat being said, `vsh` is still a small open source project, meaning we cannot give any guarantees.\nHowever, we put strong emphasis on test-driven development.\nEvery PR is tested with an extensive [suite](test/suites) of integration tests.\nVast majority of tests run on KV1 and KV2 and every test runs against vault `1.13.4` and `1.16.2`, i.e., vault versions in between are likely to be compatible too.\n\n:warning: In general, using `vsh` is at your own risk. We do not hold any responsibility and do not give any guarantees.\n\n## Contributions\n\nContributions in any form are always welcome! Without contributions from the community, `vsh` wouldn't be the tool it is today.\n\n### Local Development\n\nRequirements:\n\n- `golang` (`\u003e= v1.21`)\n- `docker` for integration testing\n- `make` for simplified commands\n\n```\nmake compile\nmake get-bats\nmake integration-tests\n```\n\n### Debugging\n\n`-v DEBUG` sets debug log level, which also creates a `vsh_trace.log` file to log any error object from the vault API.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffishi0x01%2Fvsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffishi0x01%2Fvsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffishi0x01%2Fvsh/lists"}